> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainstream.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Holders

> Top holders, distribution, concentration and change-over-time for any token.

The **Holders** data product exposes per-token holder tables and distribution metrics, so you can answer "who owns this token?", "how concentrated is it?" and "who just moved?" without scraping explorers.

## What's inside

| Field group    | Examples                                                                     |
| :------------- | :--------------------------------------------------------------------------- |
| Table          | `rank`, `address`, `balance`, `shareOfSupply`, `entityLabel`, `costBasisUsd` |
| Distribution   | `giniCoefficient`, `top10Share`, `top100Share`                               |
| Changes        | `changesLast24h` (additions, exits, net rank movement)                       |
| Classification | `bucket` — whale / shrimp / contract / exchange / liquidity-pool             |

## Coverage & freshness

* Available on every chain in [Supported Chains](/en/docs/supported-chains).
* Holder balances refreshed within seconds of matching transfer events.
* Distribution metrics recomputed every 5 minutes.

## Access

<CardGroup cols={2}>
  <Card title="REST" icon="database" href="/en/api-reference/endpoint/data/token/v2/token-chain-tokenaddress-holders-get">
    `/v2/token/{chain}/{tokenAddress}/holders`, `/v2/token/{chain}/{tokenAddress}/topholders`.
  </Card>

  <Card title="WebSocket" icon="bolt" href="/en/api-reference/endpoint/websocket/api">
    `dex-token-holding:{chain}_{tokenAddress}` — holder distribution and balance-tag counts streamed live. SDK: `client.stream.subscribeTokenHolders`.
  </Card>

  <Card title="GraphQL" icon="diagram-project" href="/en/graphql/getting-started/overview">
    Join Holders with Wallets for enriched rows.
  </Card>

  <Card title="SDK / MCP" icon="robot" href="/en/docs/ai-agents/mcp-server/introduction">
    `tokens_analyze` tool for agents — returns holder list, top-N concentration, Gini and bucket classification in one call.
  </Card>
</CardGroup>

## Common use cases

* Detect whale accumulation or distribution
* Airdrop eligibility snapshots
* Concentration-risk scoring for token due-diligence
* Chart top-10 share over time

## Billing

Per-call **1 read unit**; large holder tables paginated.

## Next

<CardGroup cols={2}>
  <Card title="Wallets" icon="wallet" href="/en/docs/data-products/wallets">
    Drill into any holder for full profile and PnL.
  </Card>

  <Card title="Smart Money" icon="brain" href="/en/docs/data-products/smart-money">
    Detect when smart-money cohorts appear in the holder list.
  </Card>
</CardGroup>