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

> GET /v1/wallets/leaderboard: your users' verified wallets ranked by volume, PnL, win rate or trades for a period.

Your users' verified wallets ranked for a period, by volume, realized PnL, win rate or number of trades. Every entry carries the owner's profile and KOL badge, so you can render a verified leaderboard in your app directly.

Only wallets with trades in the period appear. Enterprise keys can add scope=global to rank every CabalSpy ID user.

<Tip>
  The leaderboard is cached for 30 seconds. To page through it, pass the wallet of the last entry, data.pagination.next\_cursor, as cursor.
</Tip>

## Query Parameters

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

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

<ParamField query="sort" default="volume" type="string">
  Ranking order, highest first. One of volume, pnl (native), pnl\_usd, win\_rate (ties broken by closed positions) or trades.
</ParamField>

<ParamField query="limit" default="100" type="integer">
  Entries per page, 1 to 500.
</ParamField>

<ParamField query="cursor" type="string">
  Cursor for the next page, the data.pagination.next\_cursor from the previous response.
</ParamField>

<ParamField query="scope" default="instance" type="string">
  `global` ranks every CabalSpy ID user. Enterprise plan only.
</ParamField>

<ParamField query="instance" type="string">
  Your Instance ID. Only needed when your account has several instances.
</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-id.cabalspy.xyz/v1/wallets/leaderboard?blockchain=solana&period=7d&sort=pnl_usd&limit=25" \
    -H "Authorization: Bearer YOUR_KEY"
  ```

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

  params = {"blockchain": "solana", "period": "7d", "sort": "pnl_usd", "limit": 25}
  r = requests.get("https://api-id.cabalspy.xyz/v1/wallets/leaderboard", params=params,
                   headers={"Authorization": "Bearer YOUR_KEY"})
  for e in r.json()["data"]["leaderboard"]:
      print(e["rank"], e["profile"]["username"], e["period_stats"]["realized_pnl_usd"])
  ```

  ```javascript JavaScript theme={null}
  const p = new URLSearchParams({ blockchain: "solana", period: "7d", sort: "pnl_usd", limit: "25" });
  const res = await fetch(`https://api-id.cabalspy.xyz/v1/wallets/leaderboard?${p}`, {
    headers: { Authorization: "Bearer YOUR_KEY" },
  });
  const { data } = await res.json();
  data.leaderboard.forEach(e => console.log(e.rank, e.profile.username, e.period_stats.realized_pnl_usd));
  ```
</CodeGroup>

## Response

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

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

    <ResponseField name="type" type="string">
      Always csid.
    </ResponseField>

    <ResponseField name="scope" type="string">
      instance or global.
    </ResponseField>

    <ResponseField name="period" type="string">
      The requested window.
    </ResponseField>

    <ResponseField name="sort" type="string">
      The ranking order.
    </ResponseField>

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

    <ResponseField name="pagination" type="object">
      limit, total (ranked wallets), has\_more and next\_cursor (null means end).
    </ResponseField>

    <ResponseField name="leaderboard" type="array">
      <Expandable title="entry">
        <ResponseField name="rank" type="integer">
          Position in the ranking, starting at 1.
        </ResponseField>

        <ResponseField name="wallet" type="string">
          Wallet address.
        </ResponseField>

        <ResponseField name="profile" type="object">
          csid\_id, username, name, image\_url, twitter (null without X), telegram (t.me link or empty), blockchain, currency, wallet\_type (always csid), kol and public\_trading (whether the user shows their trading publicly on CabalSpy ID).
        </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">
              Bought (native).
            </ResponseField>

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

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

            <ResponseField name="total_sell_usd" type="number">
              Sold 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="realized_pnl" type="number">
              Realized PnL (native), sells minus buys.
            </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="avg_hold_time_minutes" type="number">
              Average holding time in minutes.
            </ResponseField>

            <ResponseField name="total_txn" type="integer">
              All trades.
            </ResponseField>

            <ResponseField name="buy_txn" type="integer">
              Buys.
            </ResponseField>

            <ResponseField name="sell_txn" type="integer">
              Sells.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="period_win_rate_distribution" type="object">
          win\_count, closed\_count and win\_rate\_percentage.
        </ResponseField>

        <ResponseField name="period_history_tokens" type="object">
          total\_tokens, the number of tokens traded in the period.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "blockchain": "solana",
      "type": "csid",
      "scope": "instance",
      "period": "7d",
      "sort": "pnl_usd",
      "currency": "SOL",
      "pagination": {
        "limit": 25,
        "total": 1,
        "has_more": false,
        "next_cursor": null
      },
      "leaderboard": [
        {
          "wallet": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
          "profile": {
            "csid_id": "0b7c4a52-3f1e-4f43-9d0a-2b5e7c1d9a11",
            "username": "MazeCCC",
            "name": "Maze",
            "image_url": "https://pbs.twimg.com/profile_images/.../photo.jpg",
            "twitter": "https://x.com/MazeCCC",
            "telegram": "",
            "blockchain": "solana",
            "currency": "SOL",
            "wallet_type": "csid",
            "kol": true,
            "public_trading": true
          },
          "period_stats": {
            "period": "7d",
            "total_buy": 180.25,
            "total_buy_usd": 14840.6,
            "total_sell": 228.45,
            "total_sell_usd": 18809.2,
            "total_volume": 408.7,
            "total_volume_usd": 33649.8,
            "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": 21 },
          "rank": 1
        }
      ]
    },
    "meta": {
      "request_id": "req_5162c7cf7f87",
      "cached": true,
      "cache_age_seconds": 12,
      "version": "v1",
      "timestamp": "2026-10-13T08:04:11Z"
    }
  }
  ```
</ResponseExample>

## Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | missing\_parameter | blockchain is missing. |
| 400 | invalid\_parameter | blockchain, period, sort, limit, cursor or scope invalid. |
| 401 | missing\_api\_key | API key missing. |
| 403 | invalid\_api\_key | API key invalid or not enabled for CabalSpy ID. |
| 403 | scope\_not\_allowed | scope=global needs the Enterprise plan. |
| 429 | rate\_limit\_exceeded | Rate limit exceeded. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.