Skip to main content
GET
Trader leaderboard
GET /v3/leaderboard supports two ranking modes:
  • Omit period, or use period=all, for the all-time leaderboard. All-time views can rank by total P&L, realized P&L, unrealized P&L, profit, loss, volume, wins, or position count.
  • Use period=1d, 7d, or 30d for a rolling realized-P&L leaderboard. Rolling views rank by realized_pnl in descending order and do not include historical unrealized P&L.
All monetary values are in USD.
A rolling leaderboard measures realized-state changes recorded inside the selected window. It is not a historical snapshot of each wallet’s all-time total P&L. See Wallet P&L for the matching time-window semantics.

Request

Query parameters

All-time sort aliases include total, pnl, and net_pnl for total_pnl; realized and net_realized_pnl for realized_pnl; unrealized for unrealized_pnl; profit for gross_profit; loss for gross_loss; total_volume for volume; and positions for position_count.

Rolling scope rules

A rolling request can use exactly one of these scopes: Leaderboard requests do not accept after or before; use period for a dated ranking. Rolling requests also do not accept market, event, condition, multiple-tag, or combined category-and-tag filters.

All-time example

Rolling examples

Global 7-day realized P&L

30-day category and tag rankings

Rolling response

Response envelope

Row fields

All-time rows

Rolling rows

Rolling rows do not contain unrealized_pnl, total_pnl, open_positions, or total_volume.

Pagination and empty results

  • Global all-time pagination exposes ranks 1 through 10,000. If offset + limit exceeds 10,000, the API returns 400 leaderboard_offset_too_deep.
  • Rolling pagination is capped at rank 1,000 for every scope. Shorter rankings end at their last returned row. If offset + limit exceeds 1,000, the API returns 400 leaderboard_offset_too_deep.
  • A valid category or tag with no realized results in the selected rolling window returns HTTP 200 with an empty leaderboard, count: 0, and has_more: false.

Errors

Authorizations

x-api-key
string
header
required

Query Parameters

period
enum<string>
default:all

Ranking window. Aliases day, week, and month are also accepted. Values all_time and all-time also select all-time mode.

Available options:
1d,
7d,
30d,
all
sort
string

All-time supports total_pnl, realized_pnl, unrealized_pnl, gross_profit, gross_loss, volume, wins, and position_count, plus documented aliases. Rolling supports realized_pnl only.

order
enum<string>
default:desc

All-time supports ascending or descending order. Rolling supports descending order only.

Available options:
asc,
desc
category
string

Filter to one market category. A rolling request may use one category or one tag, not both.

tags
string

Filter by tag. Rolling mode accepts exactly one tag.

tag_slug
string

Alias for one tags value.

market
string

All-time only. Filter by condition ID or market slug.

market_slug
string

All-time only. Filter by market slug.

event_slug
string

All-time only. Filter by parent event slug.

condition_id
string

All-time only. Filter by market condition ID.

limit
integer
default:20

Rows per page. Values below 1 use 1; values above 100 use 100.

Required range: 1 <= x <= 100
offset
integer
default:0

Pagination offset. Negative values use 0. Global all-time rankings stop at 10,000; rolling rankings stop at 1,000.

Required range: x >= 0

Response

Ranked wallets. A valid rolling category or tag with no results returns an empty leaderboard.