Skip to main content
GET
Get Unrealized PnL leaderboard for a market
Ranks every currently open position in one market by live Unrealized PnL or ROI, using the same mark price the frontend renders. Public — no authentication required.
Rankings are computed from a live projection maintained by a dedicated worker. Successful responses include a strong ETag; pass it back as If-None-Match to get 304 Not Modified while the projection is unchanged. ETag values are page-specific — validators do not cross pages.

Pagination

Results are paginated with limit (1–100, default 100) and page (1–100, default 1). Ranks stay absolute across pages, so page 2 with limit=10 returns ranks 11–20. Each response includes:
  • page — the page returned.
  • totalRows — number of ranked rows in the committed Top-100 generation for the market.
  • totalPages — total number of pages given the requested limit.
Request the first page of a “Top Holders” view with limit=10&page=1, then increment page until page === totalPages. To fetch the complete Top-100 in one call, use limit=100&page=1. Omitting page is treated as page 1, so existing clients keep working.

State field

Every response carries a state. Treat it as the readiness signal: For live refresh, subscribe to the unrealizedPnlProjectionChanged WebSocket event and refetch this endpoint when a hint arrives for the same marketId.
This endpoint returns 404 for markets that are not open — resolved, hidden, or otherwise ineligible for a live leaderboard.

Path Parameters

marketId
integer
required

Numeric market id.

Required range: x >= 1

Query Parameters

metric
enum<string>
default:pnl

Metric to rank by.

Available options:
pnl,
roi
limit
integer
default:100

Number of leaderboard entries to return per page (1-100).

Required range: 1 <= x <= 100
page
integer
default:1

Page number to return (1-100). Ranks stay absolute across pages, so page 2 with limit=10 returns ranks 11-20. Omitting page returns page 1.

Required range: 1 <= x <= 100

Response

Ranked Unrealized PnL leaderboard for the market

schemaVersion
enum<integer>
required
Available options:
1
state
enum<string>
required

Readiness of the underlying projection. READY is a complete, current snapshot. BUILDING means the projection is being rebuilt and data is empty. STALE and DEGRADED return the last complete snapshot with Cache-Control: no-store; callers should retry shortly.

Available options:
BUILDING,
DEGRADED,
READY,
STALE
scope
enum<string>
required
Available options:
MARKET
marketId
integer
required
Required range: x >= 1
metric
enum<string>
required
Available options:
pnl,
roi
limit
integer
required
Required range: 1 <= x <= 100
page
integer
default:1
required
Required range: x >= 1
totalRows
integer
required
Required range: x >= 0
totalPages
integer
required
Required range: x >= 0
data
object[]
required
projectionVersion
string | null
scopeVersion
string | null
presentationVersion
string | null
asOf
string<date-time> | null
markAsOf
string<date-time> | null
staleReason
string | null
collateralToken
object | null