Skip to main content
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

​
timePeriod
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
​
category
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
​
orderBy
string
default:"pnl"
Sort metric. pnl (Profit/Loss) or vol (Volume).
​
limit
number
default:"50"
Maximum entries per category. Max 500.
​
offset
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

FieldTypeDescription
timePeriodstringThe time period used for this query
categorystring"all" or the specific category queried
orderBystringSort metric used (pnl or vol)
totalnumberTotal wallets with data for this query (single-category mode only)
offsetnumberPagination offset
limitnumberMaximum entries returned
lastRefreshedstringISO timestamp of the last background data refresh
categoriesobjectLeaderboard entries grouped by category (when category=all)
leaderboardarrayFlat leaderboard entries (when a specific category is requested)

​
Leaderboard entry fields

FieldTypeDescription
localRanknumberRank within your custom leaderboard set
rankstringGlobal rank on Polymarket’s leaderboard. This is a string matching Polymarket’s API format.
proxyWalletstringPolymarket proxy wallet address
userNamestringPolymarket display name
xUsernamestringTwitter/X username (if set)
verifiedBadgebooleanPolymarket verified badge
volnumberTrading volume (USD) for this time period
pnlnumberProfit/Loss (USD) for this time period
profileImagestringProfile image URL

​
Code examples

​
Get everything for the current week

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

​
Get a single category

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

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

​
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
}
FieldTypeDescription
errorstringError message
retryAfterMsnumberMilliseconds 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.