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

# Leaderboard

> Rank tracked KOL, Smart Money and Whale wallets by trading volume for a period, with realized PnL, win rate and trade counts.

Rank the wallets CabalSpy tracks by trading volume over a chosen period, each enriched with period statistics such as buy and sell volume, realized PnL, average hold time and a win rate breakdown (how many closed positions were winners).

Use it to surface the hottest traders right now, build a Top KOLs this week board, spot who is rotating capital, or seed a copytrade shortlist. The leaderboard is served from a permanently cached, WebSocket driven store, so reads are fast and consistent (meta.cached tells you the cache age).

<Tip>
  Pick the window with period, one of 6h, 1d, 7d or 30d. Without a limit you get the full ranking, set limit and page with cursor (the cursor is a wallet address) for large boards.
</Tip>

## Query Parameters

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

<ParamField query="type" default="kol" type="string">
  Wallet category kol, smart or whale. Availability per chain. Solana has kol, smart, whale. BNB and Base have kol, smart. ETH has kol.
</ParamField>

<ParamField query="period" default="1d" type="string">
  Ranking window, one of 6h, 1d, 7d or 30d.
</ParamField>

<ParamField query="limit" type="integer">
  Maximum wallets per page. Omit to return the full ranking.
</ParamField>

<ParamField query="cursor" type="string">
  Cursor for the next page, the pagination.next\_cursor (a wallet address) from the previous response.
</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/wallets/leaderboard?blockchain=solana&type=kol&period=7d&limit=20&api_key=YOUR_KEY"
  ```

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

  params = {"blockchain": "solana", "type": "kol", "period": "7d", "limit": 20, "api_key": "YOUR_KEY"}
  r = requests.get("https://api.cabalspy.xyz/v1/wallets/leaderboard", params=params)

  for i, w in enumerate(r.json()["data"]["leaderboard"], 1):
      ps = w["period_stats"]
      wr = w["period_win_rate_distribution"]["win_rate_percentage"]
      print(f'{i:>2}. {w["profile"]["name"] or w["wallet"]:<16} vol {ps["total_volume"]:>8.1f} win {wr:.0f}%')
  ```

  ```javascript JavaScript theme={null}
  const p = new URLSearchParams({
    blockchain: "solana", type: "kol", period: "7d", limit: "20", api_key: "YOUR_KEY",
  });
  const res = await fetch(`https://api.cabalspy.xyz/v1/wallets/leaderboard?${p}`);
  const { data } = await res.json();
  data.leaderboard.forEach((w, i) =>
    console.log(`${i + 1}. ${w.profile.name || w.wallet} vol ${w.period_stats.total_volume}`));
  ```
</CodeGroup>

## Response

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

<ResponseField name="data" type="object">
  <Expandable title="data">
    <ResponseField name="blockchain" type="string">
      Requested chain.
    </ResponseField>

    <ResponseField name="type" type="string">
      Requested wallet type.
    </ResponseField>

    <ResponseField name="period" type="string">
      Ranking window 6h, 1d, 7d or 30d.
    </ResponseField>

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

    <ResponseField name="pagination" type="object">
      <Expandable title="pagination">
        <ResponseField name="total" type="integer">
          Total ranked wallets.
        </ResponseField>

        <ResponseField name="limit" type="integer">
          Requested limit (null means all).
        </ResponseField>

        <ResponseField name="next_cursor" type="string">
          Wallet address to start the next page (null means end).
        </ResponseField>

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

    <ResponseField name="leaderboard" type="array">
      <Expandable title="entry, sorted by volume highest first">
        <ResponseField name="wallet" type="string">
          Wallet address.
        </ResponseField>

        <ResponseField name="profile" type="object">
          <Expandable title="profile">
            <ResponseField name="name" type="string">
              Display name (may be empty).
            </ResponseField>

            <ResponseField name="image_url" type="string">
              Avatar URL.
            </ResponseField>

            <ResponseField name="twitter" type="string">
              Twitter or X link.
            </ResponseField>

            <ResponseField name="telegram" type="string">
              Telegram link.
            </ResponseField>

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

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

            <ResponseField name="wallet_type" type="string">
              kol, smart or whale.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="period_stats" type="object">
          <Expandable title="period_stats">
            <ResponseField name="period" type="string">
              The requested window.
            </ResponseField>

            <ResponseField name="total_buy" type="number">
              Buy volume in the period (native).
            </ResponseField>

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

            <ResponseField name="total_sell" type="number">
              Sell volume in the period (native).
            </ResponseField>

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

            <ResponseField name="total_volume" type="number">
              Buy plus sell volume (native). This is the ranking key.
            </ResponseField>

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

            <ResponseField name="realized_pnl" type="number">
              Realized PnL in the period (native).
            </ResponseField>

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

            <ResponseField name="realized_pnl_percentage" type="number">
              Realized PnL as a percentage of buy volume.
            </ResponseField>

            <ResponseField name="avg_hold_time_minutes" type="number">
              Average holding time in minutes.
            </ResponseField>

            <ResponseField name="total_txn" type="integer">
              Total transactions (buys plus sells).
            </ResponseField>

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

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

        <ResponseField name="period_win_rate_distribution" type="object">
          <Expandable title="period_win_rate_distribution">
            <ResponseField name="win_count" type="integer">
              Closed positions that ended in profit.
            </ResponseField>

            <ResponseField name="closed_count" type="integer">
              Total closed positions in the period.
            </ResponseField>

            <ResponseField name="win_rate_percentage" type="number">
              win\_count divided by closed\_count times 100.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="period_history_tokens" type="object">
          <Expandable title="period_history_tokens">
            <ResponseField name="total_tokens" type="integer">
              Distinct tokens traded in the period.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "blockchain": "solana",
      "type": "kol",
      "period": "7d",
      "currency": "SOL",
      "pagination": {
        "total": 342,
        "limit": 20,
        "next_cursor": "8CvFWU1Hfmy7HkS7eWG2x8EMtQxAzCr7KcukKwspGFwB",
        "has_more": true
      },
      "leaderboard": [
        {
          "wallet": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
          "profile": {
            "name": "Maze",
            "image_url": "https://cabalspy.xyz/images/7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW.png",
            "twitter": "https://x.com/MazeCCC",
            "telegram": "",
            "blockchain": "solana",
            "currency": "SOL",
            "wallet_type": "kol"
          },
          "period_stats": {
            "period": "7d",
            "total_buy": 180.25,
            "total_buy_usd": 14840.6,
            "total_sell": 132.25,
            "total_sell_usd": 10890.65,
            "total_volume": 312.5,
            "total_volume_usd": 25731.25,
            "realized_pnl": 48.2,
            "realized_pnl_usd": 3968.6,
            "realized_pnl_percentage": 26.74,
            "avg_hold_time_minutes": 84.5,
            "total_txn": 40,
            "buy_txn": 22,
            "sell_txn": 18
          },
          "period_win_rate_distribution": {
            "win_count": 14,
            "closed_count": 18,
            "win_rate_percentage": 77.78
          },
          "period_history_tokens": {
            "total_tokens": 23
          }
        }
      ]
    },
    "meta": {
      "request_id": "req_5162c7cf7f87",
      "cached": true,
      "cache_age_seconds": 42,
      "version": "1.0.0",
      "timestamp": "2026-07-06T11:01:57Z"
    }
  }
  ```
</ResponseExample>

## Errors

| Status | Code               | Meaning                                                                                           |
| ------ | ------------------ | ------------------------------------------------------------------------------------------------- |
| 400    | invalid\_parameter | blockchain, type or period missing or invalid (for example an unknown period, or eth with whale). |
| 401    | unauthorized       | API key missing.                                                                                  |
| 403    | forbidden          | API key invalid or credits exhausted.                                                             |
| 429    | rate\_limited      | Rate limit exceeded.                                                                              |