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

# Platform leaderboard

> GET /v1/platform-users/leaderboard: the wallets of your platform users ranked by PnL, volume, win rate or trades, with external_id and verification status.

The wallets of your [platform users](https://docs.cabalspy.xyz/cabalspy-id/white-label.md) ranked for a period. Every entry carries your `external_id` of the owner and whether the wallet is payment-verified, so you can render the leaderboard with your own user data.

Only wallets with trades in the period appear, and only users within your plan's user limit. Each wallet is its own entry, so a user with several wallets on a chain can appear more than once.

> [!TIP]
>
> The leaderboard is cached for 30 seconds. To page through it, pass pagination.next\_cursor as cursor. An unknown or malformed cursor is answered with 400 invalid\_parameter.

## Which wallets are ranked

By default every wallet that counts is ranked: verified wallets and unverified wallets your instance accepts. The `leaderboard_trust` [setting](https://docs.cabalspy.xyz/cabalspy-id/platform-users-settings.md) decides for the whole instance: with `verified_only` only payment-verified wallets are ranked. The `trust` parameter can narrow this further for one request, never widen it.

## Query Parameters

**blockchain** `string` *required*

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

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

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

**sort** `string` (default: pnl\_usd)

Ranking order, highest first. One of volume, pnl (native), pnl\_usd, win\_rate or trades, as on the [leaderboard](https://docs.cabalspy.xyz/cabalspy-id/leaderboard.md).

**trust** `string` (default: all)

`verified` ranks only payment-verified wallets. `all` follows the instance setting.

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

Entries per page, 1 to 500.

**cursor** `string`

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

**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/platform-users/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, "trust": "verified"}
r = requests.get("https://api-id.cabalspy.xyz/v1/platform-users/leaderboard", params=params,
                 headers={"Authorization": "Bearer YOUR_KEY"})
for e in r.json()["data"]["leaderboard"]:
    print(e["rank"], e["external_id"], e["verified"], e["period_stats"]["realized_pnl_usd"])
```

```javascript JavaScript theme={null}
const p = new URLSearchParams({ blockchain: "base", period: "30d", sort: "volume", limit: "50" });
const res = await fetch(`https://api-id.cabalspy.xyz/v1/platform-users/leaderboard?${p}`, {
  headers: { Authorization: "Bearer YOUR_KEY" },
});
const { data, pagination } = await res.json();
data.leaderboard.forEach(e => console.log(e.rank, e.external_id, e.period_stats.total_volume_usd));
```

## Response

**data** `object`

**data**

**blockchain** `string`

Chain.

**period** `string`

The requested window.

**sort** `string`

The ranking order.

**currency** `string`

Native currency of the chain.

**trust** `string`

`verified` when only payment-verified wallets were ranked, otherwise `all`.

**leaderboard** `array`

The entries of the [leaderboard](https://docs.cabalspy.xyz/cabalspy-id/leaderboard.md#response): rank, wallet, profile, period\_stats, period\_win\_rate\_distribution and period\_history\_tokens, plus:

**extra fields**

**external\_id** `string`

Your id of the wallet's owner.

**verified** `boolean`

Whether the wallet is payment-verified on this chain.

`profile.profile_url` is always null, platform users have no public CabalSpy ID page.

**pagination** `object`

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

```json Response theme={null}
{
  "success": true,
  "data": {
    "blockchain": "solana",
    "period": "7d",
    "sort": "pnl_usd",
    "currency": "SOL",
    "trust": "all",
    "leaderboard": [
      {
        "wallet": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
        "profile": {
          "csid_id": "3f9a1c2e-5b7d-4e8f-a1b2-c3d4e5f60718",
          "name": "Maze",
          "blockchain": "solana",
          "currency": "SOL",
          "profile_url": null,
          "...": "the profile fields of the leaderboard"
        },
        "period_stats": {
          "period": "7d",
          "total_volume_usd": 33649.8,
          "realized_pnl": 48.2,
          "realized_pnl_usd": 3968.6,
          "total_txn": 40,
          "...": "the period_stats fields of the leaderboard"
        },
        "period_win_rate_distribution": { "win_count": 14, "closed_count": 18, "win_rate_percentage": 77.78 },
        "period_history_tokens": { "total_tokens": 21 },
        "rank": 1,
        "external_id": "user_8412",
        "verified": false
      }
    ]
  },
  "pagination": {
    "limit": 25,
    "total": 1,
    "has_more": false,
    "next_cursor": null
  },
  "meta": {
    "request_id": "req_5162c7cf7f87",
    "cached": true,
    "cache_age_seconds": 12,
    "version": "v1",
    "timestamp": "2026-10-26T08:04:11Z"
  }
}
```

## Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | missing\_parameter | blockchain is missing. |
| 400 | invalid\_parameter | blockchain, period, sort, trust, limit or cursor invalid. |
| 401 | missing\_api\_key | API key missing. |
| 403 | invalid\_api\_key | API key invalid or not enabled for CabalSpy ID. |
| 429 | rate\_limit\_exceeded | Rate limit exceeded. |

See [Errors](https://docs.cabalspy.xyz/cabalspy-id/errors.md) for the full list.


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