Biggest Open Positions

Live leaderboard of the largest currently open position lines across all markets, ranked by position size. Public - no authentication required.

Responses are served from a live Redis projection with ETag support 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.

GET /leaderboard/pnl/unrealized/biggest-positions

Get biggest open positions leaderboard

cURL

curl --request GET \
  --url https://api.limitless.exchange/leaderboard/pnl/unrealized/biggest-positions

200

{
  "schemaVersion": 1,
  "state": "BUILDING",
  "scope": "BIGGEST_POSITIONS",
  "limit": 25,
  "data": [
    {
      "rank": 2,
      "account": "<string>",
      "username": "<string>",
      "displayName": "<string>",
      "pfpUrl": "<string>",
      "positionSize": {
        "raw": "9000000",
        "formatted": "9",
        "usd": "9"
      },
      "heldShares": {
        "raw": "100000000",
        "formatted": "100"
      },
      "toWin": {
        "raw": "9000000",
        "formatted": "9",
        "usd": "9"
      },
      "mark": {
        "raw": "<string>",
        "formatted": "<string>",
        "source": "CLOB_DEPTH_WEIGHTED_BID",
        "asOf": "2023-11-07T05:31:56Z"
      },
      "unrealizedPnl": {
        "raw": "9000000",
        "formatted": "9",
        "usd": "9"
      },
      "side": "YES",
      "outcomeLabel": "<string>",
      "market": {
        "id": 123,
        "slug": "<string>",
        "address": "<string>",
        "title": "<string>",
        "category": "<string>"
      }
    }
  ],
  "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"
  }
}

Returns the largest currently open position lines across all markets. Each entry pins the market it belongs to. Public — no authentication required.

By default, the list is ranked by position size in collateral. Pass metric=pnl to rank by live Unrealized PnL instead.

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 specific to the requested metric, marketPageId, and limit — validators do not cross variants.

Ranking metric

The optional metric query parameter selects the ranking:

Metric	Ranking	Notes
position_size (default)	Largest open positions by position size in collateral.	Legacy behavior; omitting metric keeps existing clients unchanged.
pnl	Open positions with the highest live Unrealized PnL.	Supports the optional marketPageId filter.

The response echoes the effective metric so you can render the right column headers without tracking request state.

Filter by market page

With metric=pnl, pass marketPageId (a UUID) to scope the ranking to one public root navigation page, for example, a top-level category like Crypto or Sports. Get page ids from the navigation tree.

• marketPageId is accepted only together with metric=pnl. Sending it with the default position-size metric returns 400.
• A marketPageId that does not identify an active public root navigation page returns 400.
• The response echoes marketPageId (null when unfiltered).

Example request

curl "https://api.limitless.exchange/leaderboard/pnl/unrealized/biggest-positions?metric=pnl&marketPageId=1f0f7f3a-2c7e-4b9a-9c1d-3d2b6f4e8a11&limit=20"

Entry fields

Each entry identifies the trader and the market, and includes:

• heldShares, mark, and unrealizedPnl — the open position line and its live valuation.
• avgEntry — the position’s average entry price per share in collateral.
• market.routeSlug — the slug to use when building frontend market links; falls back to market.slug when no dedicated route exists.
• market.imageUrl — the market’s image, or null when none is set.

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 for the BIGGEST_POSITIONS scope and refetch this endpoint when a hint arrives. The same hint covers every metric and marketPageId variant of this endpoint.

Query Parameters

limit · integer · default: 20

Number of position lines to return (1-50).

Required range: 1 <= x <= 50

Response

200

application/json

Ranked biggest open positions

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: BIGGEST_POSITIONS

limit · integer · required

Required range: 1 <= x <= 50

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