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

## Query Parameters

**blockchain** `string` *required*

Chain. One of solana, bnb, base, eth, rh.

**period** `string` (default: 1d)

Ranking window, one of 6h, 1d, 7d or 30d.

**sort** `string` (default: volume)

Ranking order, highest first. One of volume, pnl (native), pnl\_usd, win\_rate (ties broken by closed positions) or trades.

**limit** `integer` (default: 100)

Entries per page, 1 to 500.

**cursor** `string`

Cursor for the next page, the data.pagination.next\_cursor from the previous response.

**scope** `string` (default: instance)

`global` ranks every CabalSpy ID user. Enterprise plan only.

**instance** `string`

Your Instance ID. Only needed when your account has several instances.

**api\_key** `string` *required*

Your API key. Alternatively pass it as an Authorization Bearer header.

## Usage Example

```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));
```

## Response

**success** `boolean`

True on success.

**data** `object`

**data**

**blockchain** `string`

Chain.

**type** `string`

Always csid.

**scope** `string`

instance or global.

**period** `string`

The requested window.

**sort** `string`

The ranking order.

**currency** `string`

Native currency of the chain.

**pagination** `object`

limit, total (ranked wallets), has\_more and next\_cursor (null means end).

**leaderboard** `array`

**entry**

**rank** `integer`

Position in the ranking, starting at 1.

**wallet** `string`

Wallet address.

**profile** `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).

**period\_stats** `object`

**period\_stats**

**period** `string`

The requested window.

**total\_buy** `number`

Bought (native).

**total\_buy\_usd** `number`

Bought in USD.

**total\_sell** `number`

Sold (native).

**total\_sell\_usd** `number`

Sold in USD.

**total\_volume** `number`

Buy plus sell volume (native).

**total\_volume\_usd** `number`

Buy plus sell volume in USD.

**realized\_pnl** `number`

Realized PnL (native), sells minus buys.

**realized\_pnl\_usd** `number`

Realized PnL in USD.

**realized\_pnl\_percentage** `number`

Realized PnL percentage.

**avg\_hold\_time\_minutes** `number`

Average holding time in minutes.

**total\_txn** `integer`

All trades.

**buy\_txn** `integer`

Buys.

**sell\_txn** `integer`

Sells.

**period\_win\_rate\_distribution** `object`

win\_count, closed\_count and win\_rate\_percentage.

**period\_history\_tokens** `object`

total\_tokens, the number of tokens traded in the period.

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

## 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. |
| 403 | product\_not\_enabled | The key is not enabled for the CabalSpy ID API (API keys page, Works with). |
| 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.