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

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

Returns the largest currently open position lines across all markets, ranked by position size in collateral. Each entry pins the market it belongs to. 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.
</Info>

## 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 for the `BIGGEST_POSITIONS` scope and refetch this endpoint when a hint arrives.


## OpenAPI

````yaml GET /leaderboard/pnl/unrealized/biggest-positions
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/biggest-positions:
    get:
      tags:
        - Leaderboard
      summary: Get biggest open positions leaderboard
      description: >-
        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.
      operationId: UnrealizedPnlLeaderboardController_getBiggestPositions
      parameters:
        - name: limit
          in: query
          required: false
          description: Number of position lines to return (1-50).
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
      responses:
        '200':
          description: Ranked biggest open positions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnrealizedPnlBiggestPositionsResponseDto'
        '304':
          description: Snapshot matches the caller's `If-None-Match` ETag
        '400':
          description: Invalid query parameters
components:
  schemas:
    UnrealizedPnlBiggestPositionsResponseDto:
      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:
            - BIGGEST_POSITIONS
        limit:
          type: integer
          minimum: 1
          maximum: 50
        data:
          type: array
          items:
            $ref: '#/components/schemas/UnrealizedPnlBiggestPositionEntryDto'
      required:
        - schemaVersion
        - state
        - scope
        - limit
        - 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
    UnrealizedPnlBiggestPositionEntryDto:
      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
        positionSize:
          $ref: '#/components/schemas/UnrealizedPnlMoneyValueDto'
        heldShares:
          $ref: '#/components/schemas/UnrealizedPnlAmountValueDto'
        toWin:
          $ref: '#/components/schemas/UnrealizedPnlMoneyValueDto'
        mark:
          $ref: '#/components/schemas/UnrealizedPnlMarkValueDto'
        unrealizedPnl:
          $ref: '#/components/schemas/UnrealizedPnlMoneyValueDto'
        side:
          type: string
          enum:
            - 'YES'
            - 'NO'
            - UP
            - DOWN
        outcomeLabel:
          type: string
          nullable: true
        market:
          $ref: '#/components/schemas/UnrealizedPnlMarketIdentityDto'
      required:
        - rank
        - account
        - username
        - displayName
        - pfpUrl
        - positionSize
        - heldShares
        - toWin
        - mark
        - unrealizedPnl
        - side
        - outcomeLabel
        - market
    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
    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
    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
    UnrealizedPnlMarketIdentityDto:
      type: object
      properties:
        id:
          type: integer
        slug:
          type: string
        address:
          type: string
          nullable: true
        title:
          type: string
        category:
          type: string
          nullable: true
      required:
        - id
        - slug
        - address
        - title
        - category

````