Get Leaderboard - PolyNode

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

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

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

string

default:"pnl"

Sort metric. pnl (Profit/Loss) or vol (Volume).

number

default:"50"

Maximum entries per category. Max 500.

number

default:"0"

Pagination offset.

Response: all categories (default)

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

curl "https://api.polynode.dev/v2/leaderboard/custom?timePeriod=all&key=YOUR_API_KEY"

{
  "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.

curl "https://api.polynode.dev/v2/leaderboard/custom?timePeriod=week&category=crypto&key=YOUR_API_KEY"

{
  "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

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

{
  "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

curl "https://api.polynode.dev/v2/leaderboard/custom?timePeriod=day&category=sports&key=YOUR_API_KEY"

{
  "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

curl "https://api.polynode.dev/v2/leaderboard/custom?timePeriod=week&key=YOUR_API_KEY"

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

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

Get a single category

curl "https://api.polynode.dev/v2/leaderboard/custom?timePeriod=month&category=crypto&orderBy=pnl&key=YOUR_API_KEY"

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

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']})")

Sort by volume, paginated

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

// 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));
}

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:

{
  "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).

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

​Authentication

​Parameters

​Response: all categories (default)

​Response: single category

​Response: sorted by volume

​Response: today’s activity

​Top-level response fields

​Leaderboard entry fields

​Code examples

​Get everything for the current week

​Get a single category

​Sort by volume, paginated

​Rate limiting

Authentication

Parameters

Response: all categories (default)

Response: single category

Response: sorted by volume

Response: today’s activity

Top-level response fields

Leaderboard entry fields

Code examples

Get everything for the current week

Get a single category

Sort by volume, paginated

Rate limiting