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

# Stats

> Aggregate trading statistics for one token across tracked wallets, with current market cap, holder totals, flow stats and a per trader breakdown.

Everything CabalSpy knows about how tracked wallets trade one token. Returns the token block with its current market cap, holder totals by wallet type, aggregate flow statistics, and a per trader breakdown with each trader stats and live position.

Use it to build a token detail page that shows which KOLs and smart money are in a token, how much they hold, and whether they are buying or selling right now.

<Tip>
  Market cap, price and the live position fields (unrealized PnL, remaining value) are only present on Solana. On other chains those fields are null. Pass a single type to narrow to one wallet category, or omit type to aggregate all categories.
</Tip>

## Query Parameters

<ParamField query="blockchain" type="string" required>
  Chain of the token. One of solana, bnb, base, eth.
</ParamField>

<ParamField query="mint" type="string" required>
  The token mint or contract address.
</ParamField>

<ParamField query="type" type="string">
  Optional wallet category to narrow the breakdown kol, smart or whale. Omit to aggregate across all categories available on the chain.
</ParamField>

<ParamField query="api_key" type="string" required>
  Your API key. Alternatively pass it as an Authorization Bearer header.
</ParamField>

## Usage Example

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.cabalspy.xyz/v1/tokens/stats?blockchain=solana&mint=3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump&api_key=YOUR_KEY"
  ```

  ```python Python theme={null}
  import requests

  params = {
      "blockchain": "solana",
      "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
      "api_key": "YOUR_KEY",
  }
  r = requests.get("https://api.cabalspy.xyz/v1/tokens/stats", params=params)
  d = r.json()["data"]

  print("market cap", d["token"]["market_cap"], d["token"]["market_cap_currency"])
  for t in d["traders"]:
      h = t["trader_holdings"]
      print(t["profile"]["name"], "bag", h["bag_pct"], "uPNL", h.get("unrealized_pnl_sol"))
  ```

  ```javascript JavaScript theme={null}
  const p = new URLSearchParams({
    blockchain: "solana",
    mint: "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
    api_key: "YOUR_KEY",
  });
  const res = await fetch(`https://api.cabalspy.xyz/v1/tokens/stats?${p}`);
  const { data } = await res.json();
  console.log("market cap", data.token.market_cap);
  ```
</CodeGroup>

## Response

<ResponseField name="success" type="boolean">
  True on success.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="data">
    <ResponseField name="token" type="object">
      <Expandable title="token">
        <ResponseField name="mint" type="string">
          Token mint or contract address.
        </ResponseField>

        <ResponseField name="token_name" type="string">
          Token name.
        </ResponseField>

        <ResponseField name="blockchain" type="string">
          Chain.
        </ResponseField>

        <ResponseField name="currency" type="string">
          Native currency.
        </ResponseField>

        <ResponseField name="token_supply" type="number">
          Total supply.
        </ResponseField>

        <ResponseField name="token_decimals" type="integer">
          Token decimals.
        </ResponseField>

        <ResponseField name="market_cap" type="number">
          Current market cap in native currency. Solana only, null otherwise.
        </ResponseField>

        <ResponseField name="market_cap_usd" type="number">
          Current market cap in USD. Solana only, null otherwise.
        </ResponseField>

        <ResponseField name="market_cap_currency" type="string">
          Currency of the market cap value (SOL), or null.
        </ResponseField>

        <ResponseField name="price" type="number">
          Current token price in native currency. Solana only.
        </ResponseField>

        <ResponseField name="price_usd" type="number">
          Current token price in USD. Solana only.
        </ResponseField>

        <ResponseField name="sol_price_usd" type="number">
          SOL price in USD used for the USD conversions. Solana only.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="total_holders" type="object">
      <Expandable title="total_holders">
        <ResponseField name="kol_count" type="integer">
          Number of KOL holders.
        </ResponseField>

        <ResponseField name="smart_count" type="integer">
          Number of smart money holders.
        </ResponseField>

        <ResponseField name="whale_count" type="integer">
          Number of whale holders.
        </ResponseField>

        <ResponseField name="still_holding_count" type="integer">
          How many still hold a position.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="total_holdings" type="object">
      <Expandable title="total_holdings">
        <ResponseField name="token_amount" type="number">
          Total tokens currently held across tracked wallets.
        </ResponseField>

        <ResponseField name="token_amount_peak" type="number">
          Peak total tokens held.
        </ResponseField>

        <ResponseField name="supply_pct" type="number">
          Percent of supply currently held.
        </ResponseField>

        <ResponseField name="supply_pct_peak" type="number">
          Peak percent of supply held.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="total_statistics" type="object">
      <Expandable title="total_statistics">
        <ResponseField name="total_buy" type="number">
          Total bought (native).
        </ResponseField>

        <ResponseField name="total_buy_usd" type="number">
          Total bought in USD.
        </ResponseField>

        <ResponseField name="total_sell" type="number">
          Total sold (native).
        </ResponseField>

        <ResponseField name="total_sell_usd" type="number">
          Total sold in USD.
        </ResponseField>

        <ResponseField name="net_flow" type="number">
          Buy minus sell (native). Positive means net accumulation.
        </ResponseField>

        <ResponseField name="net_flow_usd" type="number">
          Net flow in USD.
        </ResponseField>

        <ResponseField name="total_volume" type="number">
          Buy plus sell volume (native).
        </ResponseField>

        <ResponseField name="total_volume_usd" type="number">
          Buy plus sell volume in USD.
        </ResponseField>

        <ResponseField name="avg_position_size" type="number">
          Average position size (native).
        </ResponseField>

        <ResponseField name="largest_position" type="number">
          Largest single position (native).
        </ResponseField>

        <ResponseField name="buying_pressure" type="number">
          Buy share of total volume, an indicator of pressure.
        </ResponseField>

        <ResponseField name="first_entry_time" type="string">
          When the first tracked wallet entered.
        </ResponseField>

        <ResponseField name="first_entry_type" type="string">
          buy or sell of the first entry.
        </ResponseField>

        <ResponseField name="first_entry_wallet_address" type="string">
          Address of the first entrant.
        </ResponseField>

        <ResponseField name="latest_entry_time" type="string">
          When the most recent tracked wallet entered.
        </ResponseField>

        <ResponseField name="latest_entry_type" type="string">
          buy or sell of the latest entry.
        </ResponseField>

        <ResponseField name="latest_entry_wallet_address" type="string">
          Address of the latest entrant.
        </ResponseField>

        <ResponseField name="time_since_first_entry_hours" type="number">
          Hours since the first entry.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="traders" type="array">
      <Expandable title="trader, sorted by buy volume highest first">
        <ResponseField name="profile" type="object">
          Wallet profile (name, image\_url, twitter, telegram, blockchain, currency, type).
        </ResponseField>

        <ResponseField name="trader_stats" type="object">
          <Expandable title="trader_stats">
            <ResponseField name="buy" type="number">
              Total bought (native).
            </ResponseField>

            <ResponseField name="buy_usd" type="number">
              Total bought in USD.
            </ResponseField>

            <ResponseField name="sell" type="number">
              Total sold (native).
            </ResponseField>

            <ResponseField name="sell_usd" type="number">
              Total sold in USD.
            </ResponseField>

            <ResponseField name="volume_buy" type="number">
              Buy volume (native).
            </ResponseField>

            <ResponseField name="volume_buy_usd" type="number">
              Buy volume in USD.
            </ResponseField>

            <ResponseField name="volume_sell" type="number">
              Sell volume (native).
            </ResponseField>

            <ResponseField name="volume_sell_usd" type="number">
              Sell volume in USD.
            </ResponseField>

            <ResponseField name="realized_pnl" type="number">
              Realized PnL on this token (native).
            </ResponseField>

            <ResponseField name="realized_pnl_usd" type="number">
              Realized PnL in USD.
            </ResponseField>

            <ResponseField name="realized_pnl_percentage" type="number">
              Realized PnL percentage.
            </ResponseField>

            <ResponseField name="buy_count" type="integer">
              Number of buys.
            </ResponseField>

            <ResponseField name="sell_count" type="integer">
              Number of sells.
            </ResponseField>

            <ResponseField name="buy_tokens" type="number">
              Tokens bought.
            </ResponseField>

            <ResponseField name="sell_tokens" type="number">
              Tokens sold.
            </ResponseField>

            <ResponseField name="avg_buy_price" type="number">
              Average buy price.
            </ResponseField>

            <ResponseField name="first_trade_at" type="string">
              ISO timestamp of the first trade.
            </ResponseField>

            <ResponseField name="last_trade_at" type="string">
              ISO timestamp of the last trade.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="trader_holdings" type="object">
          <Expandable title="trader_holdings">
            <ResponseField name="token_amount" type="number">
              Tokens currently held.
            </ResponseField>

            <ResponseField name="token_amount_peak" type="number">
              Peak tokens held.
            </ResponseField>

            <ResponseField name="supply_pct" type="number">
              Percent of supply held.
            </ResponseField>

            <ResponseField name="supply_pct_peak" type="number">
              Peak percent of supply held.
            </ResponseField>

            <ResponseField name="bag_pct" type="number">
              Percent of peak holding still held.
            </ResponseField>

            <ResponseField name="still_holding" type="boolean">
              Whether the trader still holds.
            </ResponseField>

            <ResponseField name="unrealized_pnl_sol" type="number">
              Unrealized PnL on the remaining bag (native). Solana only. Frozen to 0 once fully sold.
            </ResponseField>

            <ResponseField name="unrealized_pnl_usd" type="number">
              Unrealized PnL in USD. Solana only.
            </ResponseField>

            <ResponseField name="unrealized_pnl_pct" type="number">
              Unrealized PnL percentage. Solana only.
            </ResponseField>

            <ResponseField name="remaining_sol" type="number">
              Current value of the remaining bag (native). Solana only.
            </ResponseField>

            <ResponseField name="remaining_usd" type="number">
              Current value of the remaining bag in USD. Solana only.
            </ResponseField>

            <ResponseField name="entry_market_cap" type="number">
              Market cap in SOL when the wallet first bought, frozen. Solana only, null for older positions.
            </ResponseField>

            <ResponseField name="entry_market_cap_usd" type="number">
              Entry market cap in USD, frozen at buy time. Solana only, null for older positions.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "token": {
        "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
        "token_name": "invisibull",
        "blockchain": "solana",
        "currency": "SOL",
        "token_supply": 1000000000,
        "token_decimals": 6,
        "market_cap": 40.08,
        "market_cap_usd": 3301.2,
        "market_cap_currency": "SOL",
        "price": 4.008e-8,
        "price_usd": 3.3e-6,
        "sol_price_usd": 82.36
      },
      "total_holders": {
        "kol_count": 1,
        "smart_count": 0,
        "whale_count": 0,
        "still_holding_count": 1
      },
      "total_holdings": {
        "token_amount": 22113972.03,
        "token_amount_peak": 22113972.03,
        "supply_pct": 2.211397,
        "supply_pct_peak": 2.211397
      },
      "total_statistics": {
        "total_buy": 1.66,
        "total_buy_usd": 137.44,
        "total_sell": 0.0,
        "total_sell_usd": 0.0,
        "net_flow": 1.66,
        "net_flow_usd": 137.44,
        "total_volume": 1.66,
        "total_volume_usd": 137.44,
        "avg_position_size": 1.66,
        "largest_position": 1.66,
        "buying_pressure": 100.0,
        "first_entry_time": "2026-07-04T16:25:34Z",
        "first_entry_type": "buy",
        "first_entry_wallet_address": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
        "latest_entry_time": "2026-07-04T16:25:34Z",
        "latest_entry_type": "buy",
        "latest_entry_wallet_address": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
        "time_since_first_entry_hours": 42.6
      },
      "traders": [
        {
          "profile": {
            "name": "Maze",
            "image_url": "https://cabalspy.xyz/images/7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW.png",
            "twitter": "https://x.com/MazeCCC",
            "telegram": "",
            "blockchain": "solana",
            "currency": "SOL",
            "type": "kol"
          },
          "trader_stats": {
            "buy": 1.66,
            "buy_usd": 137.44,
            "sell": 0.0,
            "sell_usd": 0.0,
            "volume_buy": 1.66,
            "volume_buy_usd": 137.44,
            "volume_sell": 0.0,
            "volume_sell_usd": 0.0,
            "realized_pnl": 0.0,
            "realized_pnl_usd": 0.0,
            "realized_pnl_percentage": 0.0,
            "buy_count": 1,
            "sell_count": 0,
            "buy_tokens": 22113972.03,
            "sell_tokens": 0.0,
            "avg_buy_price": 7.5e-8,
            "first_trade_at": "2026-07-04T16:25:34Z",
            "last_trade_at": "2026-07-04T16:25:34Z"
          },
          "trader_holdings": {
            "token_amount": 22113972.03,
            "token_amount_peak": 22113972.03,
            "supply_pct": 2.211397,
            "supply_pct_peak": 2.211397,
            "bag_pct": 100.0,
            "still_holding": true,
            "unrealized_pnl_sol": -0.099817,
            "unrealized_pnl_usd": -8.22,
            "unrealized_pnl_pct": -10.12,
            "remaining_sol": 0.886537,
            "remaining_usd": 73.02,
            "entry_market_cap": 44.6,
            "entry_market_cap_usd": 3673.2
          }
        }
      ]
    },
    "meta": {
      "request_id": "req_5162c7cf7f87",
      "cached": false,
      "cache_age_seconds": 0,
      "version": "1.0.0",
      "timestamp": "2026-07-06T11:01:57Z"
    }
  }
  ```
</ResponseExample>

## Errors

| Status | Code               | Meaning                               |
| ------ | ------------------ | ------------------------------------- |
| 400    | missing\_parameter | mint is missing.                      |
| 400    | invalid\_parameter | blockchain or type invalid.           |
| 401    | unauthorized       | API key missing.                      |
| 403    | forbidden          | API key invalid or credits exhausted. |
| 429    | rate\_limited      | Rate limit exceeded.                  |