> For the complete documentation index, see [llms.txt](https://cabalspy.gitbook.io/cabalspy-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cabalspy.gitbook.io/cabalspy-docs/token-activity/token-holders.md).

# Token Holders

Every smart money, KOL and whale wallet that ever held a single token on Solana, BNB Chain, Base and Ethereum — including wallets that already sold, with current balance, all-time peak and a still-holding flag, sorted by amount held.

## Token Holders — KOL & Smart Money Wallets Holding a Token

> Get every tracked smart money, KOL and whale wallet that ever held one token on Solana, BNB Chain, Base or Ethereum — including wallets that already sold their entire position. Sold-out wallets are recognisable by \`still\_holding: false\` and \`token\_amount: 0\`, but keep their all-time peak, so you can analyse who is still holding versus who has exited. Ideal for token holder analysis and smart-money tracking.\
> \
> \*\*Sorting\*\* — descending by current amount held (\`token\_amount\`), then by all-time peak (\`token\_amount\_peak\`). Wallets still holding appear first, followed by those that have exited.\
> \
> \*\*holders vs. stats\*\* — this is the pure holder view: per wallet a \`profile\` and \`holdings\`. Per-wallet trading metrics (buy/sell, PnL) are served by \`GET /v1/tokens/stats\` (\`traders\[]\`); individual transactions by \`GET /v1/tokens/transactions\`.\
> \
> \*\*Data source\*\* — full history from the database (no 30-day cap) merged with the newest live transactions, deduplicated by signature. Peaks are computed by chronological replay and survive a full sell-off — this even survives an in-memory flush because it is recomputed from the database.\
> \
> \*\*Parameters / settings\*\*\
> \- \`blockchain\` (required) — one of: \`solana\`, \`bnb\`, \`base\`, \`eth\`\
> \- \`mint\` (required) — token mint / contract address\
> \- \`type\` (optional) — \`kol\`, \`smart\`, or \`whale\`; if omitted, all valid\
>   wallet types for the chain are merged\
> \
> \- \`limit\` (optional, default \`50\`) — maximum number of holders returned\
> \- \`api\_key\` (optional if the Bearer header is used)<br>

```json
{"openapi":"3.0.3","info":{"title":"CabalSpy API — Token Holders","version":"1.0.0"},"tags":[{"name":"Token Holders","description":"Every smart money, KOL and whale wallet that ever held a single token on Solana, BNB Chain, Base and Ethereum — including wallets that already sold, with current balance, all-time peak and a still-holding flag, sorted by amount held.\n"}],"servers":[{"url":"https://api.cabalspy.xyz"}],"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authorization: Bearer YOUR_KEY"},"apiKeyQuery":{"type":"apiKey","in":"query","name":"api_key"}},"schemas":{"TokenHoldersEnvelope":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"token":{"type":"object","description":"Token metadata (mint, name, blockchain, currency, supply, decimals)."},"total_holders":{"type":"object","description":"kol_count, smart_count, whale_count, still_holding_count."},"holders":{"type":"array","description":"Per wallet a profile and holdings (token_amount, token_amount_peak, supply_pct, supply_pct_peak, bag_pct, still_holding). Sorted by amount held descending, then by peak.\n","items":{"type":"object"}}}},"meta":{"type":"object"},"pagination":{"type":"object"}}},"ErrorEnvelope":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"docs":{"type":"string"}}}}}}},"paths":{"/v1/tokens/holders":{"get":{"tags":["Token Holders"],"summary":"Token Holders — KOL & Smart Money Wallets Holding a Token","operationId":"getTokenHolders","description":"Get every tracked smart money, KOL and whale wallet that ever held one token on Solana, BNB Chain, Base or Ethereum — including wallets that already sold their entire position. Sold-out wallets are recognisable by `still_holding: false` and `token_amount: 0`, but keep their all-time peak, so you can analyse who is still holding versus who has exited. Ideal for token holder analysis and smart-money tracking.\n\n**Sorting** — descending by current amount held (`token_amount`), then by all-time peak (`token_amount_peak`). Wallets still holding appear first, followed by those that have exited.\n\n**holders vs. stats** — this is the pure holder view: per wallet a `profile` and `holdings`. Per-wallet trading metrics (buy/sell, PnL) are served by `GET /v1/tokens/stats` (`traders[]`); individual transactions by `GET /v1/tokens/transactions`.\n\n**Data source** — full history from the database (no 30-day cap) merged with the newest live transactions, deduplicated by signature. Peaks are computed by chronological replay and survive a full sell-off — this even survives an in-memory flush because it is recomputed from the database.\n\n**Parameters / settings**\n- `blockchain` (required) — one of: `solana`, `bnb`, `base`, `eth`\n- `mint` (required) — token mint / contract address\n- `type` (optional) — `kol`, `smart`, or `whale`; if omitted, all valid\n  wallet types for the chain are merged\n\n- `limit` (optional, default `50`) — maximum number of holders returned\n- `api_key` (optional if the Bearer header is used)\n","parameters":[{"name":"blockchain","in":"query","required":true,"schema":{"type":"string","enum":["solana","bnb","base","eth"]}},{"name":"mint","in":"query","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["kol","smart","whale"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"minimum":1}},{"name":"api_key","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Token found — returns the holder counts and the holder list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenHoldersEnvelope"}}}},"400":{"description":"Missing or invalid parameter (e.g. `mint` or `blockchain`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Invalid or exhausted API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```