> ## 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.

# Holders

> The tracked wallets holding a token, ranked by amount held, each with live position, unrealized PnL, remaining value and entry market cap.

List the tracked wallets holding a token, ranked by how much they hold. Each holder carries its profile and a live position with bag percentage, unrealized PnL, remaining value and the market cap at which it first entered. The token block carries the current market cap.

This is the data behind a holder table, the classic view that shows which KOLs and smart money are sitting in a token and whether they are up or down on the position.

<Tip>
  The live position fields (unrealized PnL, remaining value, entry market cap) are Solana only and null on other chains. entry\_market\_cap is null for positions that were opened before entry tracking started. Holders are sorted by amount held, highest first, and the list is paginated with limit.
</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 kol, smart or whale. Omit to include all categories.
</ParamField>

<ParamField query="limit" type="integer">
  Maximum number of holders to return.
</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/holders?blockchain=solana&mint=3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump&limit=50&api_key=YOUR_KEY"
  ```

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

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

  print("market cap", d["token"]["market_cap"])
  for h in d["holders"]:
      pos = h["holdings"]
      print(h["profile"]["name"], "bag", pos["bag_pct"], "uPNL", pos.get("unrealized_pnl_sol"))
  ```

  ```javascript JavaScript theme={null}
  const p = new URLSearchParams({
    blockchain: "solana",
    mint: "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
    limit: "50", api_key: "YOUR_KEY",
  });
  const res = await fetch(`https://api.cabalspy.xyz/v1/tokens/holders?${p}`);
  const { data } = await res.json();
  data.holders.forEach(h => console.log(h.profile.name, h.holdings.bag_pct));
  ```
</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 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="holders" type="array">
      <Expandable title="holder, sorted by amount held highest first">
        <ResponseField name="profile" type="object">
          Wallet profile (name, image\_url, twitter, telegram, blockchain, currency, type).
        </ResponseField>

        <ResponseField name="holdings" type="object">
          <Expandable title="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 holder 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>

    <ResponseField name="pagination" type="object">
      <Expandable title="pagination">
        <ResponseField name="limit" type="integer">
          Holders per page.
        </ResponseField>

        <ResponseField name="total" type="integer">
          Total holders.
        </ResponseField>

        <ResponseField name="has_more" type="boolean">
          Whether more pages follow.
        </ResponseField>

        <ResponseField name="next_cursor" type="string">
          Cursor for the next page (null means end).
        </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
      },
      "holders": [
        {
          "profile": {
            "name": "Maze",
            "image_url": "https://cabalspy.xyz/images/7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW.png",
            "twitter": "https://x.com/MazeCCC",
            "telegram": "",
            "blockchain": "solana",
            "currency": "SOL",
            "type": "kol"
          },
          "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
          }
        }
      ]
    },
    "pagination": {
      "limit": 50,
      "total": 1,
      "has_more": false,
      "next_cursor": null
    },
    "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.                  |