> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polynode.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Leaderboard

> Query your custom leaderboard ranked by P&L or volume, filtered by time period and category.

Returns your custom leaderboard built from the wallets in your BYOL set. By default, returns all categories in a single response. You can also filter to a specific category.

```
GET /v2/leaderboard/custom
```

## Authentication

Pass your API key via query parameter `?key=`, header `x-api-key`, or `Authorization: Bearer`.

## Parameters

<ParamField query="timePeriod" type="string" default="all">
  Time period for P\&L and volume. Matches Polymarket's leaderboard tabs.

  * `day` — Today
  * `week` — Last 7 days
  * `month` — Last 30 days
  * `all` — All time
</ParamField>

<ParamField query="category" type="string" default="all">
  Market category filter. Use `all` to get every category in one response, or specify one:

  * `all` — Returns all categories grouped in a `categories` object (default)
  * `overall` — All markets combined
  * `politics` `sports` `crypto` `finance` `tech` `weather` `culture` `mentions`
</ParamField>

<ParamField query="orderBy" type="string" default="pnl">
  Sort metric. `pnl` (Profit/Loss) or `vol` (Volume).
</ParamField>

<ParamField query="limit" type="number" default="50">
  Maximum entries per category. Max 500.
</ParamField>

<ParamField query="offset" type="number" default="0">
  Pagination offset.
</ParamField>

## Response: all categories (default)

When `category=all` or omitted, the response groups results by category. Each category is sorted and ranked independently.

```bash theme={null}
curl "https://api.polynode.dev/v2/leaderboard/custom?timePeriod=all&key=YOUR_API_KEY"
```

```json theme={null}
{
  "timePeriod": "all",
  "category": "all",
  "orderBy": "pnl",
  "offset": 0,
  "limit": 50,
  "lastRefreshed": "2026-04-01T16:04:19.000Z",
  "categories": {
    "overall": [
      {
        "localRank": 1,
        "rank": "1",
        "proxyWallet": "0x56687bf447db6ffa42ffe2204a05edaa20f55839",
        "userName": "Theo4",
        "xUsername": "",
        "verifiedBadge": false,
        "vol": 43013258.52,
        "pnl": 22053933.75,
        "profileImage": ""
      },
      {
        "localRank": 2,
        "rank": "8",
        "proxyWallet": "0x8119010a6e589062aa03583bb3f39ca632d9f887",
        "userName": "PrincessCaro",
        "xUsername": "",
        "verifiedBadge": false,
        "vol": 23520809.95,
        "pnl": 6083643.10,
        "profileImage": ""
      },
      {
        "localRank": 3,
        "rank": "5004",
        "proxyWallet": "0xb595d09ce5bbc4d39e3b3d04e80c402d2c8d5922",
        "userName": "...",
        "xUsername": "",
        "verifiedBadge": false,
        "vol": 2467445.01,
        "pnl": 22617.64,
        "profileImage": ""
      }
    ],
    "politics": [
      {
        "localRank": 1,
        "rank": "1",
        "proxyWallet": "0x56687bf447db6ffa42ffe2204a05edaa20f55839",
        "userName": "Theo4",
        "xUsername": "",
        "verifiedBadge": false,
        "vol": 43012710.75,
        "pnl": 22053952.53,
        "profileImage": ""
      }
    ],
    "sports": [
      {
        "localRank": 1,
        "rank": "1696",
        "proxyWallet": "0xb595d09ce5bbc4d39e3b3d04e80c402d2c8d5922",
        "userName": "...",
        "xUsername": "",
        "verifiedBadge": false,
        "vol": 2466252.61,
        "pnl": 22677.91,
        "profileImage": ""
      }
    ],
    "crypto": [...],
    "finance": [...],
    "tech": [],
    "weather": [],
    "culture": [...],
    "mentions": [...]
  }
}
```

## Response: single category

When you specify a category like `category=crypto`, the response is a flat leaderboard with a `total` count.

```bash theme={null}
curl "https://api.polynode.dev/v2/leaderboard/custom?timePeriod=week&category=crypto&key=YOUR_API_KEY"
```

```json theme={null}
{
  "timePeriod": "week",
  "category": "crypto",
  "orderBy": "pnl",
  "total": 6,
  "offset": 0,
  "limit": 50,
  "lastRefreshed": "2026-04-01T16:04:19.000Z",
  "leaderboard": [
    {
      "localRank": 1,
      "rank": "551",
      "proxyWallet": "0x53decedc72531ef57b2d54b5542c509e233c822f",
      "userName": "jack118",
      "xUsername": "",
      "verifiedBadge": false,
      "vol": 0,
      "pnl": 11077.58,
      "profileImage": ""
    },
    {
      "localRank": 2,
      "rank": "34808",
      "proxyWallet": "0x05d5e0403427a6223f5673b3234ac9405c19db37",
      "userName": "0x05d5e0403427a6223f5673b3234ac9405c19db37",
      "xUsername": "",
      "verifiedBadge": false,
      "vol": 0,
      "pnl": 23.24,
      "profileImage": ""
    }
  ]
}
```

## Response: sorted by volume

```bash theme={null}
curl "https://api.polynode.dev/v2/leaderboard/custom?timePeriod=month&category=overall&orderBy=vol&limit=5&key=YOUR_API_KEY"
```

```json theme={null}
{
  "timePeriod": "month",
  "category": "overall",
  "orderBy": "vol",
  "total": 18,
  "offset": 0,
  "limit": 5,
  "lastRefreshed": "2026-04-01T16:04:19.000Z",
  "leaderboard": [
    {
      "localRank": 1,
      "rank": "1086",
      "proxyWallet": "0xb595d09ce5bbc4d39e3b3d04e80c402d2c8d5922",
      "userName": "...",
      "xUsername": "",
      "verifiedBadge": false,
      "vol": 43406.94,
      "pnl": 22107.49,
      "profileImage": ""
    },
    {
      "localRank": 2,
      "rank": "129764",
      "proxyWallet": "0xc0220b02ad4cf50f8d612dbb3aa7783973266494",
      "userName": "...",
      "xUsername": "",
      "verifiedBadge": false,
      "vol": 25.75,
      "pnl": 11.87,
      "profileImage": ""
    }
  ]
}
```

## Response: today's activity

```bash theme={null}
curl "https://api.polynode.dev/v2/leaderboard/custom?timePeriod=day&category=sports&key=YOUR_API_KEY"
```

```json theme={null}
{
  "timePeriod": "day",
  "category": "sports",
  "orderBy": "pnl",
  "total": 9,
  "offset": 0,
  "limit": 50,
  "lastRefreshed": "2026-04-01T16:04:19.000Z",
  "leaderboard": [
    {
      "localRank": 1,
      "rank": "768",
      "proxyWallet": "0xb595d09ce5bbc4d39e3b3d04e80c402d2c8d5922",
      "userName": "...",
      "xUsername": "",
      "verifiedBadge": false,
      "vol": 43406.94,
      "pnl": 516.36,
      "profileImage": ""
    },
    {
      "localRank": 2,
      "rank": "96658",
      "proxyWallet": "0x1116147499ba1da24081a5f09077cdbc4586997c",
      "userName": "...",
      "xUsername": "",
      "verifiedBadge": false,
      "vol": 0,
      "pnl": 0.13,
      "profileImage": ""
    }
  ]
}
```

## Top-level response fields

| Field           | Type   | Description                                                        |
| --------------- | ------ | ------------------------------------------------------------------ |
| `timePeriod`    | string | The time period used for this query                                |
| `category`      | string | `"all"` or the specific category queried                           |
| `orderBy`       | string | Sort metric used (`pnl` or `vol`)                                  |
| `total`         | number | Total wallets with data for this query (single-category mode only) |
| `offset`        | number | Pagination offset                                                  |
| `limit`         | number | Maximum entries returned                                           |
| `lastRefreshed` | string | ISO timestamp of the last background data refresh                  |
| `categories`    | object | Leaderboard entries grouped by category (when `category=all`)      |
| `leaderboard`   | array  | Flat leaderboard entries (when a specific category is requested)   |

## Leaderboard entry fields

| Field           | Type    | Description                                                                                 |
| --------------- | ------- | ------------------------------------------------------------------------------------------- |
| `localRank`     | number  | Rank within your custom leaderboard set                                                     |
| `rank`          | string  | Global rank on Polymarket's leaderboard. This is a string matching Polymarket's API format. |
| `proxyWallet`   | string  | Polymarket proxy wallet address                                                             |
| `userName`      | string  | Polymarket display name                                                                     |
| `xUsername`     | string  | Twitter/X username (if set)                                                                 |
| `verifiedBadge` | boolean | Polymarket verified badge                                                                   |
| `vol`           | number  | Trading volume (USD) for this time period                                                   |
| `pnl`           | number  | Profit/Loss (USD) for this time period                                                      |
| `profileImage`  | string  | Profile image URL                                                                           |

## Code examples

### Get everything for the current week

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.polynode.dev/v2/leaderboard/custom?timePeriod=week&key=YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.polynode.dev/v2/leaderboard/custom?timePeriod=week&key=YOUR_API_KEY"
  );
  const data = await response.json();

  // All 9 categories in one response
  for (const [category, traders] of Object.entries(data.categories)) {
    if (traders.length > 0) {
      console.log(`${category}: ${traders.length} traders`);
      console.log(`  Top trader: ${traders[0].userName} ($${traders[0].pnl.toFixed(2)})`);
    }
  }
  ```

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

  response = requests.get(
      "https://api.polynode.dev/v2/leaderboard/custom",
      params={"timePeriod": "week", "key": "YOUR_API_KEY"}
  )
  data = response.json()

  for category, traders in data["categories"].items():
      if traders:
          top = traders[0]
          print(f"{category}: {len(traders)} traders, top: {top['userName']} (${top['pnl']:,.2f})")
  ```
</CodeGroup>

### Get a single category

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.polynode.dev/v2/leaderboard/custom?timePeriod=month&category=crypto&orderBy=pnl&key=YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.polynode.dev/v2/leaderboard/custom?timePeriod=month&category=crypto&orderBy=pnl&key=YOUR_API_KEY"
  );
  const data = await response.json();

  // Flat leaderboard array
  console.log(`${data.total} traders in crypto this month`);
  for (const trader of data.leaderboard || []) {
    console.log(`#${trader.localRank} ${trader.userName} — $${trader.pnl.toFixed(2)} P&L (global rank: ${trader.rank})`);
  }
  ```

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

  response = requests.get(
      "https://api.polynode.dev/v2/leaderboard/custom",
      params={
          "timePeriod": "month",
          "category": "crypto",
          "orderBy": "pnl",
          "key": "YOUR_API_KEY"
      }
  )
  data = response.json()

  print(f"{data['total']} traders in crypto this month")
  for trader in data["leaderboard"]:
      print(f"#{trader['localRank']} {trader['userName']} — ${trader['pnl']:,.2f} (global #{trader['rank']})")
  ```
</CodeGroup>

### Sort by volume, paginated

<CodeGroup>
  ```bash cURL theme={null}
  # Top 10 by volume, all time
  curl "https://api.polynode.dev/v2/leaderboard/custom?timePeriod=all&category=overall&orderBy=vol&limit=10&key=YOUR_API_KEY"

  # Next 10
  curl "https://api.polynode.dev/v2/leaderboard/custom?timePeriod=all&category=overall&orderBy=vol&limit=10&offset=10&key=YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  // Paginate through all results
  let offset = 0;
  const limit = 50;

  while (true) {
    const response = await fetch(
      `https://api.polynode.dev/v2/leaderboard/custom?timePeriod=all&category=overall&orderBy=vol&limit=${limit}&offset=${offset}&key=YOUR_API_KEY`
    );
    const data = await response.json();

    for (const trader of data.leaderboard || []) {
      console.log(`#${trader.localRank} ${trader.userName} — $${trader.vol.toFixed(2)} volume`);
    }

    if (!data.leaderboard || data.leaderboard.length < limit) break;
    offset += limit;

    // Respect rate limit: 1 request per 5 seconds
    await new Promise(resolve => setTimeout(resolve, 5000));
  }
  ```
</CodeGroup>

## Rate limiting

This endpoint is rate limited to **1 request per 5 seconds** per API key. If you exceed this, you'll get a 429 response:

```json theme={null}
{
  "error": "Leaderboard is rate limited to 1 request per 5 seconds.",
  "retryAfterMs": 3784
}
```

| Field          | Type   | Description                          |
| -------------- | ------ | ------------------------------------ |
| `error`        | string | Error message                        |
| `retryAfterMs` | number | Milliseconds to wait before retrying |

The response also includes a `Retry-After` header (in seconds).

<Note>
  Data refreshes every \~30 minutes in the background. Repeat requests within 60 seconds are served from an in-memory cache for maximum speed.
</Note>