Stream name: clusters

What Are Clusters?

Most tokens appear to have thousands of independent holders. In reality, a significant portion of supply is often controlled by a small number of entities operating through multiple wallets.

Cluster analysis uncovers these hidden relationships. InsightX analyzes on-chain activity -- funding patterns, intermediary wallets, and transfer behaviour -- to group related wallet addresses into clusters. Each cluster represents a single entity or coordinated group, and shows their true combined holdings as a percentage of total supply.

Use clusters to:

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 flagged 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.

Labels

Every wallet in a cluster is tagged with one or more labels. These labels also appear at the cluster level as an aggregate.

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.

Subscribing

Single Token

{
  "op": "subscribe",
  "network": "sol",
  "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "stream": "clusters"
}

Multiple Tokens

{
  "op": "subscribe",
  "subs": [
    { "network": "sol", "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "stream": "clusters" },
    { "network": "sol", "address": "So11111111111111111111111111111111111111112", "stream": "clusters" }
  ]
}

Event Format

When cluster data changes for a token you're subscribed to, you receive an event:

{
  "op": "event",
  "network": "sol",
  "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "stream": "clusters",
  "timestamp": "2026-02-07T14:30:00.000Z",
  "data": {
    "total_supply": 10000000000.0,
    "total_cluster_pct": 32.95,
    "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"]
          }
        ]
      }
    ]
  }
}

Data Reference

Top-Level Fields

Field	Type	Description
`op`	string	Always `"event"`
`network`	string	Network ID (`sol`, `eth`, `base`, etc.)
`address`	string	Token contract address
`stream`	string	Always `"clusters"`
`timestamp`	string	ISO 8601 UTC timestamp of when the event was generated
`data`	object	Cluster analysis payload (see below)

`data` Object

Field	Type	Description
`total_supply`	number	Total token supply used for percentage calculations
`total_cluster_pct`	number	Sum of all cluster `pct` values -- the total percentage of supply held by clustered wallets
`clusters`	array	Array of cluster objects, sorted by `pct` descending (largest first)

Cluster Object

Each entry in clusters represents a group of wallets identified as related.

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

Cluster Address Object

Each entry in cluster_addresses represents one wallet in the cluster.

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 (see Labels)

Update Frequency

Cluster events are delivered in real time as holder balances change on-chain. The frequency depends on trading activity:

High-activity tokens (actively traded) -- updates every few seconds.
Moderate-activity tokens -- updates every few minutes.
Low-activity tokens -- updates may be hours apart.

Each event contains the full, current cluster state for the token -- not a diff. You can always replace your local state with the latest event.

Related REST Endpoint

You can also fetch cluster data on-demand via the REST API:

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

The REST response uses the same data structure as the WebSocket event. Use the REST endpoint for initial data loading or one-off queries, and the WebSocket stream for continuous real-time updates.

Network Support

The clusters stream is available on all supported networks: sol, eth, base, bsc, monad, xlayer, abs.