> ## 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. 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](/api-reference/navigation/get-navigation). * `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). ```bash Example request theme={null} 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`](/developers/websocket/unrealized-pnl#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. ## OpenAPI ````yaml GET /leaderboard/pnl/unrealized/biggest-positions openapi: 3.0.0 info: title: Limitless Exchange API description: >- # Limitless Exchange Trading API *Production-ready API for prediction market trading, portfolio management, and market data* > 🎯 **Quick Navigation**: [Authentication](#tag/authentication) | [Markets](#tag/markets) | [Trading](#tag/trading) | [Portfolio](#tag/portfolio) --- ## 🚀 Quick Start Choose your preferred programming language for complete end-to-end implementation: ### Overview The Limitless Exchange API offers both REST and WebSocket integration: **REST API (Trading)**: 1. **🔐 Authentication**: Use API key for all programmatic access 2. **📊 Fetch Market Data**: Get market info including venue contract addresses (once per market) 3. **📋 Order Creation**: Build and sign orders using EIP-712 structured data 4. **🚀 Order Submission**: Submit signed orders and receive confirmations **WebSocket API (Real-Time Data)**: 1. **🔌 Connection**: Connect to `/markets` namespace for real-time updates 2. **📊 Subscriptions**: Subscribe to market prices and position changes 3. **📡 Events**: Handle live market data and transaction updates ### 🔐 Authentication for API Users > **⚠️ DEPRECATION NOTICE**: Cookie-based session authentication is deprecated and will be removed within weeks. Please migrate to API keys immediately. | Method | Header | Status | |--------|--------|--------| | **API Key** | `X-API-Key: lmts_...` | ✅ Required for programmatic access | | Cookie Session | `Cookie: limitless_session=...` | ⚠️ Deprecated (removal imminent) | **Getting an API Key** API keys can only be created via the Limitless Exchange UI: 1. Log in to [limitless.exchange](https://limitless.exchange) using your wallet 2. Click your profile menu (top right) 3. Select "Api keys" 4. Generate a new key **Using Your API Key** Include in all requests via the `X-API-Key` header: ```bash # REST API curl -H "X-API-Key: lmts_your_key_here" https://api.limitless.exchange/markets # WebSocket - pass X-API-Key header during connection handshake ``` ### Migration from Cookie to API Key If you're currently using cookie-based authentication, migrate by: 1. **Generate an API key** via the UI (profile menu → Api keys) 2. **Replace cookie header** with API key header: ```diff # Before (deprecated) - Cookie: limitless_session=your_session_token # After + X-API-Key: lmts_your_key_here ``` 3. **Remove session management code** - no more login flow or cookie handling needed ### Important: Venue System for CLOB Markets CLOB markets use a **venue system** where each market is associated with specific contract addresses. Before placing orders: 1. **Fetch market data once**: `GET /markets/:slug` returns venue information 2. **Use venue.exchange**: This is the `verifyingContract` for EIP-712 order signing 3. **Cache the venue**: Venue data is static per market - fetch once and reuse **Sample venue response:** ```json { "venue": { "exchange": "0xA1b2C3...", "adapter": "0xD4e5F6..." } } ``` ### Required Approvals Before trading, set up token approvals based on order type: | Order Type | Market Type | Approve To | |------------|-------------|------------| | BUY | All CLOB | USDC → `venue.exchange` | | SELL | Simple CLOB | CT → `venue.exchange` | | SELL | NegRisk/Grouped | CT → `venue.exchange` AND `venue.adapter` | ### Checksummed Addresses All addresses must use **checksummed format** (EIP-55 mixed-case): - Authentication: `x-account` header - Orders: `maker` and `signer` fields - Example: `0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed` ### Implementation Guides **[🐍 Python Quick Start](#description/-python-quick-start)** - REST API: eth-account, requests, and web3.py libraries - WebSocket: python-socketio, asyncio integration **[☕ Java Quick Start](#description/-java-quick-start)** - REST API: Web3j, OkHttp3, and Jackson libraries **[📦 Node.js/TypeScript Quick Start](#description/-nodejs-typescript-quick-start)** - REST API: viem, ethers, and cross-fetch libraries - WebSocket: socket.io-client for real-time trading - Full TypeScript support with end-to-end examples **[🔌 WebSocket Integration](#description/-websocket-integration)** - Real-time market data and position updates - Production-ready Python client with authentication --- ## 🐍 Python Quick Start Complete end-to-end Python implementation for Limitless Exchange API integration. ### 🐍 Python E2E Order Creation Guide Complete Python implementation guide is being loaded from external documentation... **Guide Contents:** - 🔐 Complete authentication flow with eth-account - 📋 Order construction with Web3.py calculations - ✍️ EIP-712 structured data signing - 🚀 Order submission with requests library - ⚠️ Comprehensive error handling - 🛠️ Production deployment considerations *For the complete Python guide, ensure the file is available at docs/scripts-samples/python-e2e-order-creation.md* ## ☕ Java Quick Start Complete end-to-end Java implementation for Limitless Exchange API integration. ### ☕ Java E2E Order Creation Guide Complete Java enterprise implementation guide is being loaded from external documentation... **Guide Contents:** - 🔐 Complete authentication flow with Web3j - 📋 Order construction with BigInteger precision - ✍️ EIP-712 structured data signing - 🚀 Order submission with OkHttp3 - ⚠️ Enterprise error handling patterns - 🏗️ Production Maven project structure *For the complete Java guide, ensure the file is available at docs/scripts-samples/java-e2e-order-creation.md* ## 📦 Node.js/TypeScript Quick Start Complete end-to-end Node.js/TypeScript implementation for trading and WebSocket subscriptions. ### 📦 Node.js/TypeScript Trading & WebSocket Guide Complete Node.js/TypeScript implementation guide is being loaded from external documentation... **Guide Contents:** - 🔐 **Authentication**: Wallet-based auth with ethers and viem - 📋 **Order Creation**: EIP-712 signing with viem WalletClient - 🚀 **Order Submission**: REST API integration with cross-fetch - 🔌 **WebSocket Subscriptions**: socket.io-client for real-time updates - 📊 **Market Data**: AMM prices and CLOB orderbook subscriptions - ⚠️ **Type Safety**: Full TypeScript support with proper types - 🛠️ **Production Ready**: Complete end-to-end working example **Key Features:** - **Combined Subscriptions**: Subscribe to both AMM and CLOB markets simultaneously - **Authentication Flow**: Complete wallet-based authentication with session management - **Trading Integration**: Place orders and receive real-time updates - **TypeScript First**: Type-safe implementation with proper interfaces *For the complete Node.js guide, ensure the file is available at docs/scripts-samples/node-socket-trading-and-subscribe.md* ## 🔌 WebSocket Integration Real-time market data and position updates using WebSocket connections. ### 🔌 WebSocket Real-Time Integration Guide Complete WebSocket implementation guide is being loaded from external documentation... **Guide Contents:** - 🔌 **WebSocket Connection**: python-socketio client with async support - 🔐 **Authentication**: JWT session cookie integration - 📊 **Market Subscriptions**: Real-time price updates and position changes - ⚡ **Event Handling**: Comprehensive event processing patterns - 🔄 **Auto-Reconnection**: Production-ready reconnection logic - 🛠️ **Error Recovery**: Robust error handling and fallback strategies **Key Features:** - **Public Mode**: Market price updates without authentication - **Authenticated Mode**: Full access to positions and transactions - **Multi-Market Support**: Subscribe to multiple markets simultaneously - **Production Ready**: Tested patterns for production deployment *For the complete WebSocket guide, ensure the file is available at docs/scripts-samples/python-socket-subscribe.md* version: '1.0' contact: name: API Support url: https://limitless.exchange email: hey@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: Feed description: Public trading activity feeds 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 ````