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.

GET /leaderboard/pnl/unrealized/markets/{marketId}

Get Unrealized PnL leaderboard for a market

cURL

curl --request GET \
  --url https://api.limitless.exchange/leaderboard/pnl/unrealized/markets/{marketId}

200

{
  "schemaVersion": 1,
  "state": "BUILDING",
  "scope": "MARKET",
  "marketId": 2,
  "metric": "pnl",
  "limit": 50,
  "page": 1,
  "totalRows": 1,
  "totalPages": 1,
  "data": [
    {
      "rank": 2,
      "account": "<string>",
      "username": "<string>",
      "displayName": "<string>",
      "pfpUrl": "<string>",
      "side": "YES",
      "outcomeLabel": "<string>",
      "heldShares": {
        "raw": "100000000",
        "formatted": "100"
      },
      "avgEntry": {
        "raw": "100000000",
        "formatted": "100"
      },
      "costBasis": {
        "raw": "9000000",
        "formatted": "9",
        "usd": "9"
      },
      "mark": {
        "raw": "<string>",
        "formatted": "<string>",
        "source": "CLOB_DEPTH_WEIGHTED_BID",
        "asOf": "2023-11-07T05:31:56Z"
      },
      "marketValue": {
        "raw": "9000000",
        "formatted": "9",
        "usd": "9"
      },
      "unrealizedPnl": {
        "raw": "9000000",
        "formatted": "9",
        "usd": "9"
      },
      "unrealizedRoi": 123
    }
  ],
  "projectionVersion": "<string>",
  "scopeVersion": "<string>",
  "presentationVersion": "<string>",
  "asOf": "2023-11-07T05:31:56Z",
  "markAsOf": "2023-11-07T05:31:56Z",
  "staleReason": "<string>",
  "collateralToken": {
    "id": 7,
    "symbol": "USDC",
    "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "decimals": 6,
    "priceOracleId": "usd-coin"
  }
}

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.

A dedicated worker computes the rankings from a live projection. 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:

State	Meaning	How to handle
READY	Complete, current snapshot.	Render data and cache per Cache-Control.
STALE	Last complete snapshot is being replaced.	Render data; response is Cache-Control: no-store, refetch shortly.
DEGRADED	Snapshot returned with a staleReason.	Render data; treat as best-effort and refetch shortly.
BUILDING	No complete snapshot yet.	data is empty; retry after a short delay.

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

200

application/json

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

Show child attributes

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

Show child attributes