GET /dex-metrics/v1/{network}/{token_address}/clusters

Groups related wallet addresses into clusters based on on-chain relationships. Reveals the true ownership distribution behind wallets that appear independent but are controlled by the same entity or coordinated group.

Parameters

Parameter	In	Type	Required	Description
`network`	path	string	Yes	Network ID (see Supported Networks)
`token_address`	path	string	Yes	Token contract address

Example Request

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.insightx.network/dex-metrics/v1/sol/pumpCmXqMfrsAkQ5r49WcJnRayYRqmXz6ae8H7H9Dfn/clusters

Response

{
  "total_cluster_pct": 45.32,
  "clusters": [
    {
      "pct": 18.75,
      "tags": ["funding_address", "wallet"],
      "cluster_addresses": [
        {
          "address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
          "balance": 1250000000.0,
          "percentage": 12.5,
          "tags": ["wallet", "funding_address"]
        },
        {
          "address": "5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9",
          "balance": 625000000.0,
          "percentage": 6.25,
          "tags": ["wallet"]
        }
      ]
    },
    {
      "pct": 14.20,
      "tags": ["volume_bot", "team", "wallet"],
      "cluster_addresses": [
        {
          "address": "HN7cABqLq46Es1jh92dQQisAq662SmxELLLsHHe4YWrH",
          "balance": 920000000.0,
          "percentage": 9.2,
          "tags": ["wallet", "volume_bot", "team"]
        },
        {
          "address": "3Kz9FKL8pVNBEj2dGNvxFHMABGFzuTS5THad9gJ4bSMp",
          "balance": 500000000.0,
          "percentage": 5.0,
          "tags": ["wallet"]
        }
      ]
    }
  ]
}

Fields

Top Level

Field	Type	Description
`total_cluster_pct`	number	Sum of all cluster `pct` values -- the total percentage of supply held by wallets that belong to a cluster
`clusters`	array	Cluster groups, sorted by `pct` descending (largest first)

Cluster Object

Field	Type	Description
`pct`	number	Combined holding percentage of all addresses in this cluster
`tags`	array	Aggregate labels for the cluster (inherited from member wallets)
`cluster_addresses`	array	Individual wallet entries, sorted by `percentage` descending

Cluster Address Object

Field	Type	Description
`address`	string	Wallet or contract address
`balance`	number	Current token balance (in token units, not raw decimals)
`percentage`	number	Percentage of total supply held by this address
`tags`	array	Labels for this specific address

Labels

Every wallet and cluster is tagged with one or more labels:

Label	Meaning
`wallet`	Standard externally-owned wallet address
`smart_contract`	A smart contract address
`funding_address`	Address that funded other wallets in the cluster -- a strong signal of common ownership
`intermediary`	Address used as a pass-through between wallets
`volume_bot`	Address performing wash trading or artificial volume generation
`exchange`	Known centralized exchange address
`team`	Address associated with the token's team or deployer
`liquidity_pool`	DEX liquidity pool contract
`vesting`	Token vesting or lock contract
`presale`	Presale distribution contract
`burn`	Burn address (tokens permanently removed from circulation)

Labels appear at two levels:

Cluster-level tags -- if any wallet in the cluster has a label, the cluster inherits it. Useful for quickly filtering clusters by type.
Address-level tags -- the specific labels for each individual wallet.

Use Cases

Detect concentrated ownership -- see if a token's supply is really distributed or just spread across wallets owned by the same entity.
Identify wash trading -- wallets tagged as volume_bot are generating artificial trading volume.
Track insider movements -- team wallets and funding sources are tagged so you can monitor their activity.
Assess rug-pull risk -- large clusters with funding_address relationships may indicate coordinated accumulation before a dump.
Enrich holder data -- combine with Labels API data for full context on who controls what.

Real-Time Updates

For continuous updates as holder balances change, subscribe to the Clusters WebSocket Stream. The WebSocket event uses the same data structure as this REST endpoint, with the addition of total_supply in the payload.

Network Support

Network	Status
All networks	Supported

If no cluster data or snapshot exists for a token, an empty response is returned:

{
  "total_cluster_pct": 0.0,
  "clusters": []
}