Sign in

v1

latestOpenAPI 3.1.02026-07-243035381.4 MB
Prediction API

Get top traders leaderboard

/v4/data/prediction/top-traders

200 credits per API call

Ranked leaderboard of top traders, scoped by category and time period. Each row carries the trader's wallet, display fields (username, X handle, profile image), verified-badge status, and the metrics used for ranking (volume and PnL within the requested window).

Platform support

  • Polymarket only.

Filtering, sorting and pagination

  • category selects the leaderboard slice — one of OVERALL, POLITICS, SPORTS, CRYPTO, CULTURE, MENTIONS, WEATHER, ECONOMICS, TECH, FINANCE. Defaults to OVERALL.
  • timePeriod sets the lookback window — DAY, WEEK, MONTH, ALL. Defaults to DAY.
  • orderBy chooses the ranking metric: PNL (realised + unrealised profit) or VOL (trading volume). Defaults to PNL.
  • user filters the leaderboard to a single wallet — useful for "where does this trader rank" lookups. userName filters by trader display name (substring match).
  • Pagination is offset-based — limit (1..50, default 25) and offset (0..1000, default 0). Higher offsets are not supported by the upstream leaderboard.

Other notes

  • rank is the continuous 1-indexed position given the requested filters — rank = 1 is the leader for the chosen category and time period.
  • proxyWallet is returned lowercased.
  • vol and pnl are USD figures, scoped to the requested category and timePeriod.
get/v4/data/prediction/top-traders

Query parameters

category'OVERALL' | 'POLITICS' | 'SPORTS' | 'CRYPTO' | 'CULTURE' | 'MENTIONS' | 'WEATHER' | 'ECONOMICS' | 'TECH' | 'FINANCE'

Leaderboard category slice.

Example:OVERALL

Leaderboard category slice. Defaults to OVERALL.

timePeriod'DAY' | 'WEEK' | 'MONTH' | 'ALL'

Leaderboard lookback window.

Example:DAY

Lookback window. Defaults to DAY.

orderBy'PNL' | 'VOL'

Leaderboard ranking metric. PNL = realised + unrealised profit; VOL = trading volume.

Example:PNL

Ranking metric. Defaults to PNL.

limitinteger
Example:25

Page size. Defaults to 25.

offsetinteger

Page offset. Defaults to 0. The upstream leaderboard caps offsets at 1000.

userstring
Example:0x56687bf447db6ffa42ffe2204a05edaa20f55839

Filter the leaderboard to a single wallet (0x + 40 hex). Useful for "where does this trader rank" lookups.

userNamestring
Example:JaneDoe

Filter by trader display name (substring match).

Response

OK

Example response

{
  "data": [
    {
      "rank": 1,
      "proxyWallet": "0x56687bf447db6ffa42ffe2204a05edaa20f55839",
      "userName": "JaneDoe",
      "xUsername": "jane_doe_x",
      "verifiedBadge": true,
      "vol": 1543200.5,
      "pnl": 281450.75,
      "profileImage": "https://polymarket.com/avatars/jane.png"
    }
  ],
  "pagination": {
    "pageSize": 25
  }
}