> 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-statistics.md). # Token Statistics Aggregated smart-money statistics and analytics for a single token on Solana, BNB Chain, Base and Ethereum — holder counts, total holdings with all-time peaks, buy/sell volume, net flow and realized PnL, plus a per-trader breakdown. ## Token Smart Money Stats — Volume, Net Flow & Realized PnL > Get aggregated smart-money statistics for one token on Solana, BNB Chain, Base or Ethereum: how tracked KOL, smart money and whale wallets traded it, with buy/sell volume, net flow, buying pressure and realized PnL in native currency and USD, plus a per-trader breakdown in \`traders\[]\`. Use it for token due diligence, smart-money dashboards and trading signals. This endpoint does NOT return individual transactions — use \`GET /v1/tokens/transactions\` for those.\ > \ > \*\*What you get\*\*\ > \- \`token\` — token metadata.\ > \- \`total\_holders\` — wallet counts per type plus the number of wallets\ > still holding.\ > \ > \- \`total\_holdings\` — summed current balance and all-time peak across all\ > traders, each also as a percentage of supply.\ > \ > \- \`total\_statistics\` — buy/sell, volume, net flow (native + USD),\ > buying pressure, first and latest entry.\ > \ > \- \`traders\[]\` — per wallet the \`profile\`, \`trader\_holdings\` and\ > \`trader\_stats\`, sorted by buy volume descending.\ > \ > \ > \*\*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 (\`token\_amount: 0\`, \`token\_amount\_peak > 0\`). Historical USD values come straight from the transactions.\ > \ > \*\*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 (counts stay split per type)\ > \ > \- \`api\_key\` (optional if the Bearer header is used)
```json {"openapi":"3.0.3","info":{"title":"CabalSpy API — Token Stats","version":"1.0.0"},"tags":[{"name":"Token Statistics","description":"Aggregated smart-money statistics and analytics for a single token on Solana, BNB Chain, Base and Ethereum — holder counts, total holdings with all-time peaks, buy/sell volume, net flow and realized PnL, plus a per-trader breakdown.\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":{"TokenStatsEnvelope":{"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."},"total_holdings":{"type":"object","description":"token_amount, token_amount_peak, supply_pct, supply_pct_peak (summed over all traders)."},"total_statistics":{"type":"object","description":"total_buy(_usd), total_sell(_usd), net_flow(_usd), total_volume(_usd), avg_position_size, largest_position, buying_pressure, first/latest entry, time_since_first_entry_hours.\n"},"traders":{"type":"array","description":"Per wallet: profile, trader_holdings (balance + peaks) and trader_stats (buy/sell, realized PnL, counts, avg buy price, first/last trade), sorted by buy volume descending.\n","items":{"type":"object"}}}},"meta":{"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/stats":{"get":{"tags":["Token Statistics"],"summary":"Token Smart Money Stats — Volume, Net Flow & Realized PnL","operationId":"getTokenStats","description":"Get aggregated smart-money statistics for one token on Solana, BNB Chain, Base or Ethereum: how tracked KOL, smart money and whale wallets traded it, with buy/sell volume, net flow, buying pressure and realized PnL in native currency and USD, plus a per-trader breakdown in `traders[]`. Use it for token due diligence, smart-money dashboards and trading signals. This endpoint does NOT return individual transactions — use `GET /v1/tokens/transactions` for those.\n\n**What you get**\n- `token` — token metadata.\n- `total_holders` — wallet counts per type plus the number of wallets\n still holding.\n\n- `total_holdings` — summed current balance and all-time peak across all\n traders, each also as a percentage of supply.\n\n- `total_statistics` — buy/sell, volume, net flow (native + USD),\n buying pressure, first and latest entry.\n\n- `traders[]` — per wallet the `profile`, `trader_holdings` and\n `trader_stats`, sorted by buy volume descending.\n\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 (`token_amount: 0`, `token_amount_peak > 0`). Historical USD values come straight from the transactions.\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 (counts stay split per type)\n\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":"api_key","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Token found — returns aggregated statistics and the trader breakdown.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenStatsEnvelope"}}}},"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"}}}}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://cabalspy.gitbook.io/cabalspy-docs/token-activity/token-statistics.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.