> 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"}}}}}}}}} ```