> ## Documentation Index
> Fetch the complete documentation index at: https://docs.limitless.exchange/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`.

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.

<Info>
  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.
</Info>

## 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`](/developers/websocket-events#unrealizedpnlprojectionchanged) WebSocket event and refetch this endpoint when a hint arrives for the same `marketId`.

<Note>
  This endpoint returns `404` for markets that are not open — resolved, hidden, or otherwise ineligible for a live leaderboard.
</Note>


## OpenAPI

````yaml GET /leaderboard/pnl/unrealized/markets/{marketId}
openapi: 3.0.0
info:
  title: Limitless Exchange API
  description: >-
    Production-ready REST API for prediction market trading, portfolio
    management, and market data on Limitless Exchange (Base L2).
  version: '1.0'
  contact:
    name: API Support
    url: https://limitless.exchange
    email: help@limitless.network
servers:
  - url: https://api.limitless.exchange
    description: Production API
security: []
tags:
  - name: Authentication
    description: User authentication and session management
  - name: Markets
    description: Browse, search, and analyze prediction markets
  - name: Market Navigation
    description: Navigation tree, market pages, and property filters
  - name: Trading
    description: Create, manage, and cancel orders
  - name: Portfolio
    description: Position tracking, trade history, and performance
  - name: API Tokens
    description: Scoped API token management for partner integrations
  - name: Partner Accounts
    description: Sub-account creation and allowance recovery for partner integrations
  - name: System
    description: Public API state and availability information
  - name: Referral
    description: Referral program earnings, referred users, and leaderboards
  - name: Leaderboard
    description: >-
      Live Unrealized PnL leaderboards for open markets and biggest open
      positions
paths:
  /leaderboard/pnl/unrealized/markets/{marketId}:
    get:
      tags:
        - Leaderboard
      summary: Get Unrealized PnL leaderboard for a market
      description: >-
        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`.
      operationId: UnrealizedPnlLeaderboardController_getMarket
      parameters:
        - name: marketId
          in: path
          required: true
          description: Numeric market id.
          schema:
            type: integer
            minimum: 1
        - name: metric
          in: query
          required: false
          description: Metric to rank by.
          schema:
            type: string
            enum:
              - pnl
              - roi
            default: pnl
        - name: limit
          in: query
          required: false
          description: Number of leaderboard entries to return per page (1-100).
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 100
        - name: page
          in: query
          required: false
          description: >-
            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.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 1
      responses:
        '200':
          description: Ranked Unrealized PnL leaderboard for the market
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnrealizedPnlMarketResponseDto'
        '304':
          description: Snapshot matches the caller's `If-None-Match` ETag
        '400':
          description: Invalid market id or query parameters
        '404':
          description: Market is not open for Unrealized PnL
components:
  schemas:
    UnrealizedPnlMarketResponseDto:
      type: object
      properties:
        schemaVersion:
          type: integer
          enum:
            - 1
        state:
          $ref: '#/components/schemas/UnrealizedPnlSnapshotState'
        projectionVersion:
          type: string
          nullable: true
        scopeVersion:
          type: string
          nullable: true
        presentationVersion:
          type: string
          nullable: true
        asOf:
          type: string
          format: date-time
          nullable: true
        markAsOf:
          type: string
          format: date-time
          nullable: true
        staleReason:
          type: string
          nullable: true
        collateralToken:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/UnrealizedPnlCollateralTokenDto'
        scope:
          type: string
          enum:
            - MARKET
        marketId:
          type: integer
          minimum: 1
        metric:
          type: string
          enum:
            - pnl
            - roi
        limit:
          type: integer
          minimum: 1
          maximum: 100
        page:
          type: integer
          minimum: 1
          default: 1
        totalRows:
          type: integer
          minimum: 0
        totalPages:
          type: integer
          minimum: 0
        data:
          type: array
          items:
            $ref: '#/components/schemas/UnrealizedPnlMarketEntryDto'
      required:
        - schemaVersion
        - state
        - scope
        - marketId
        - metric
        - limit
        - page
        - totalRows
        - totalPages
        - data
    UnrealizedPnlSnapshotState:
      type: string
      description: >-
        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.
      enum:
        - BUILDING
        - DEGRADED
        - READY
        - STALE
    UnrealizedPnlCollateralTokenDto:
      type: object
      properties:
        id:
          type: integer
          example: 7
        symbol:
          type: string
          example: USDC
        address:
          type: string
          example: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
        decimals:
          type: integer
          example: 6
        priceOracleId:
          type: string
          nullable: true
          example: usd-coin
      required:
        - id
        - symbol
        - address
        - decimals
        - priceOracleId
    UnrealizedPnlMarketEntryDto:
      type: object
      properties:
        rank:
          type: integer
          minimum: 1
        account:
          type: string
        username:
          type: string
          nullable: true
        displayName:
          type: string
          nullable: true
        pfpUrl:
          type: string
          nullable: true
        side:
          type: string
          enum:
            - 'YES'
            - 'NO'
            - UP
            - DOWN
        outcomeLabel:
          type: string
          nullable: true
        heldShares:
          $ref: '#/components/schemas/UnrealizedPnlAmountValueDto'
        avgEntry:
          $ref: '#/components/schemas/UnrealizedPnlAmountValueDto'
        costBasis:
          $ref: '#/components/schemas/UnrealizedPnlMoneyValueDto'
        mark:
          $ref: '#/components/schemas/UnrealizedPnlMarkValueDto'
        marketValue:
          $ref: '#/components/schemas/UnrealizedPnlMoneyValueDto'
        unrealizedPnl:
          $ref: '#/components/schemas/UnrealizedPnlMoneyValueDto'
        unrealizedRoi:
          type: number
          nullable: true
          description: ROI as a percent (e.g. 37.5 = +37.5%). Null when cost basis is zero.
      required:
        - rank
        - account
        - username
        - displayName
        - pfpUrl
        - side
        - outcomeLabel
        - heldShares
        - avgEntry
        - costBasis
        - mark
        - marketValue
        - unrealizedPnl
        - unrealizedRoi
    UnrealizedPnlAmountValueDto:
      type: object
      description: >-
        Numeric amount rendered both as an integer `raw` string in collateral
        base units and a human-readable `formatted` decimal string.
      properties:
        raw:
          type: string
          example: '100000000'
        formatted:
          type: string
          example: '100'
      required:
        - raw
        - formatted
    UnrealizedPnlMoneyValueDto:
      type: object
      description: >-
        Money amount in the market's collateral with an optional USD-denominated
        value.
      properties:
        raw:
          type: string
          example: '9000000'
        formatted:
          type: string
          example: '9'
        usd:
          type: string
          nullable: true
          example: '9'
      required:
        - raw
        - formatted
        - usd
    UnrealizedPnlMarkValueDto:
      type: object
      description: >-
        Current mark price used to value the open position, plus the source that
        produced it and the time it was observed.
      properties:
        raw:
          type: string
        formatted:
          type: string
        source:
          type: string
          enum:
            - CLOB_DEPTH_WEIGHTED_BID
            - CLOB_LAST_MINED_TRADE
            - AMM_SPOT
            - AMM_LAST_INDEXED_TRADE
            - AVG_ENTRY_FALLBACK
        asOf:
          type: string
          format: date-time
          nullable: true
      required:
        - raw
        - formatted
        - source
        - asOf

````