Unrealized PnL Leaderboard by Market
Live leaderboard of open positions for one market, ranked by Unrealized PnL or ROI. Public - no authentication required. Ranks are absolute across pages, so page 2 with limit=10 returns ranks 11-20.
Results are paginated with limit (1-100, default 100) and page (1-100, default 1). The response also includes totalRows and totalPages describing the committed Top-100 generation for the market. ETag values are page-specific, so a validator returned for one page will not match another.
Responses are served from a live Redis projection maintained by a dedicated worker. When the projection is warm the response is a READY snapshot with a strong ETag and short client cache. When the projection is still being rebuilt, callers may receive a BUILDING, STALE, or DEGRADED snapshot with Cache-Control: no-store and (for BUILDING) an empty data array - retry after a short delay. If the market is not open (RESOLVED, hidden, or otherwise ineligible), the endpoint returns 404.
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 withlimit (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 requestedlimit.
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 astate. Treat it as the readiness signal:
unrealizedPnlProjectionChanged WebSocket event and refetch this endpoint when a hint arrives for the same marketId.
404 for markets that are not open — resolved, hidden, or otherwise ineligible for a live leaderboard.Path Parameters
Numeric market id.
x >= 1Query Parameters
Metric to rank by.
pnl, roi Number of leaderboard entries to return per page (1-100).
1 <= x <= 100Page 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.
1 <= x <= 100Response
Ranked Unrealized PnL leaderboard for the market
1 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.
BUILDING, DEGRADED, READY, STALE MARKET x >= 1pnl, roi 1 <= x <= 100x >= 1x >= 0x >= 0