Get the trader leaderboard

The ranked board of realized PnL, combos included.

?time_period= is day (default), week, month or all; ?category= is overall (default) or a market category; ?sort_by= picks the PNL (default) or VOLUME board. Deeper pages come only from ?cursor=.

A cursor pins the board it was minted on; sort, window and category; so following it needs no params at all, and restating a different one is a 400 rather than a silent re-point (the builders-board pattern).

?user= answers a different question; one wallet’s standing, carrying both the PnL and volume ranks in a single object rather than a page. A rank of 0 there means unranked for that board, not first. sort_by, limit and cursor do not apply to that arm.

rank ties and skips: tied users share a rank and the next one jumps, so a partition’s highest rank approaches its row count. Page with the cursor; never compute a page from a rank.

Finite windows (day/week/month) serve the MARKED equity change net of flows; they move with unrealized marks; all is the realized-only lifetime ledger. volume is in shares, not USDC.

GET /v2/leaderboard

Get the trader leaderboard

cURL

curl --request GET \
  --url https://data-api.polymarket.com/v2/leaderboard \
  --header 'Authorization: Bearer <token>'

200

{
  "data": [
    {
      "pnl": 123,
      "profile_image": "<string>",
      "rank": 1,
      "user_id": "<string>",
      "user_name": "<string>",
      "verified": true,
      "volume": 123,
      "x_username": "<string>"
    }
  ],
  "pagination": {
    "has_more": true,
    "limit": 1,
    "offset": 1,
    "next_cursor": "<string>"
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

time_period · string | null

Window: day | week | month | all. Defaults to day.

category · string | null

overall (default), a Gamma market category (e.g. sports), or a synthetic category: combos (combinatorial positions; PNL boards only; the volume board has no combos rows) or esports (promoted subcategory).

sort_by · string | null

Which board: PNL (default) or VOLUME.

user · string | null

Look up one wallet's standing instead of reading the board. Returns a single object carrying both ranks, not a page.

limit · integer<int32> | null

First-page size. Ignored when cursor is supplied.

Required range: 0 <= x <= 1000

cursor · string | null

Opaque pagination cursor from a prior response's next_cursor.

Response

200

application/json

A page of the board, or one wallet's standing when user is given

Option 1

Option 2

Either arm's body. ?user= answers with one standing; everything else with a page of the board; genuinely different shapes, so the spec says oneOf rather than pretending one covers both.

data · object[] · required

The page's rows.

Show child attributes

pagination · object · required

Paging envelope: follow next_cursor until null.

Show child attributes