> ## 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. # Get Order Status (Batch) > Fetches historical order statuses for multiple orders by internal order IDs and/or client-provided order IDs. Partner API tokens with `delegated_signing` scope may read a sub-account by sending the `x-on-behalf-of: ` header. Look up orders by either `orderId` (internal) or `clientOrderId` (your identifier). Provide exactly one per item, not both. ## Authentication and delegation Use HMAC authentication. Looking up your own orders does not require a specific token scope. To look up a managed sub-account, send `x-on-behalf-of: `. The HMAC token must carry `delegated_signing`, and the target profile must belong to the authenticated partner. ## Validation behavior The request accepts 1–50 items and preserves their input order in `results` through the `index` field. * An item with both identifiers, neither identifier, or a blank `clientOrderId` returns an item-level `status: "invalid"`; the rest of the batch is processed. * An unknown identifier, including an order owned by another profile, returns item-level `status: "not_found"`. * Malformed UUIDs or field types, client IDs longer than 128 characters, unknown fields, malformed nesting, and batch-size violations reject the whole request with `400 Bad Request`. For `status: "found"`, `data` directly contains `order`, optional `makerMatches`, and `execution`. There is no additional response envelope inside `data.order`. Historical status reports `UNMATCHED`, `DELAYED`, `MATCHED`, `MINED`, `CONFIRMED`, `RETRYING`, or `FAILED`. It returns the latest known execution state; it does not include placement-time STP reasons, STP maker-cancel IDs, or a historical `CANCELED` state. ## Errors | Status | Meaning | | ------ | -------------------------------------------------------------------------------------------------------------------- | | `400` | Whole-request validation failed, the delegated header is malformed, or the authenticated profile cannot be resolved. | | `401` | Authentication failed. | | `403` | Delegation lacks `delegated_signing` or the target is not owned by the partner. | | `500` | Historical status lookup failed unexpectedly. | ## OpenAPI ````yaml POST /orders/status/batch 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: /orders/status/batch: post: tags: - Trading summary: Get Order Status Batch description: >- Fetches historical order statuses for multiple orders by internal order IDs and/or client-provided order IDs. Partner API tokens with `delegated_signing` scope may read a sub-account by sending the `x-on-behalf-of: ` header. operationId: OrderController_getOrderStatusBatch parameters: - name: x-on-behalf-of in: header description: >- Managed sub-account profile ID. Requires an HMAC token with `delegated_signing` and a partner relationship with the target. required: false schema: type: integer minimum: 1 maximum: 2147483647 example: 326 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BatchOrderStatusRequestDto' responses: '200': description: Batch order statuses content: application/json: schema: $ref: '#/components/schemas/BatchOrderStatusResponseDto' '400': description: >- Whole-request validation failure, malformed delegation header, or unresolved authenticated profile content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationErrorResponse' - $ref: '#/components/schemas/NestErrorResponse' - $ref: '#/components/schemas/ErrorMessageResponse' '401': description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/NestErrorResponse' '403': description: >- Delegation lacks delegated_signing or the target is not owned by the partner content: application/json: schema: $ref: '#/components/schemas/NestErrorResponse' '500': description: Unexpected historical-status lookup failure content: application/json: schema: $ref: '#/components/schemas/ErrorMessageResponse' security: - HmacAuth: [] components: schemas: BatchOrderStatusRequestDto: type: object properties: items: description: List of status lookup queries minItems: 1 maxItems: 50 type: array items: $ref: '#/components/schemas/BatchOrderStatusItemDto' additionalProperties: false required: - items BatchOrderStatusResponseDto: type: object properties: results: type: array items: $ref: '#/components/schemas/BatchOrderStatusResultDto' required: - results ValidationErrorResponse: type: object properties: message: type: array items: $ref: '#/components/schemas/ValidationErrorItem' error: type: string enum: - Bad Request statusCode: type: number enum: - 400 additionalProperties: false required: - message - error - statusCode NestErrorResponse: type: object properties: message: type: string error: type: string statusCode: type: integer additionalProperties: false required: - message - error - statusCode ErrorMessageResponse: type: object properties: message: type: string additionalProperties: false required: - message BatchOrderStatusItemDto: type: object properties: orderId: type: string description: >- Internal order ID. Provide either orderId or clientOrderId, not both. example: 4aa706dd-6c57-4f3c-945a-99818dfd95f1 format: uuid clientOrderId: type: string description: >- Client-provided order ID. Provide either orderId or clientOrderId, not both. example: client-order-001 maxLength: 128 BatchOrderStatusResultDto: type: object properties: index: type: integer example: 0 minimum: 0 status: type: string enum: - found - not_found - invalid example: found error: type: string example: Exactly one of orderId or clientOrderId is required orderId: type: string example: 4aa706dd-6c57-4f3c-945a-99818dfd95f1 format: uuid clientOrderId: type: string example: client-order-001 maxLength: 128 data: $ref: '#/components/schemas/HistoricalOrderResponseDto' required: - index - status ValidationErrorItem: type: object properties: field: type: string example: orderIds message: type: string example: orderIds should not be empty additionalProperties: false required: - field - message HistoricalOrderResponseDto: type: object properties: order: $ref: '#/components/schemas/HistoricalOrderDto' makerMatches: type: array items: $ref: '#/components/schemas/MakerMatch' execution: $ref: '#/components/schemas/OrderExecutionSummary' required: - order - execution HistoricalOrderDto: type: object properties: id: type: string format: uuid description: Internal order ID salt: type: string description: Order salt as a decimal string example: '1778155025318314496' maker: type: string pattern: ^0x[a-fA-F0-9]{40}$ signer: type: string pattern: ^0x[a-fA-F0-9]{40}$ taker: type: string nullable: true pattern: ^0x[a-fA-F0-9]{40}$ tokenId: type: string expiration: type: string format: date-time nullable: true signatureType: type: number enum: - 0 - 1 - 2 - 3 feeRateBps: type: integer nullable: true signature: type: string pattern: ^0x([a-fA-F0-9]{2})*$ orderType: type: string enum: - GTC - FAK - FOK side: type: number enum: - 0 - 1 description: 0 = BUY, 1 = SELL marketId: type: string ownerId: type: integer createdAt: type: string format: date-time market: $ref: '#/components/schemas/MarketSlimDto' makerAmount: type: string description: Raw 6-decimal amount as a decimal string example: '5000000' takerAmount: type: string description: Raw 6-decimal amount as a decimal string example: '10000000' nonce: type: string enum: - '0' description: Numeric zero as a decimal string price: type: string nullable: true example: '0.75' owner: $ref: '#/components/schemas/HistoricalOrderOwner' required: - id - salt - maker - signer - tokenId - signatureType - signature - orderType - side - marketId - ownerId - createdAt - market - makerAmount - takerAmount - nonce - owner MakerMatch: type: object properties: id: type: string format: uuid matchedSize: type: string description: Matched contracts in raw 6-decimal units. example: '1000000' fillPrice: type: string description: Effective taker-perspective fill price. example: '0.55' fillCost: type: string description: Fill collateral cost in raw 6-decimal units. example: '550000' orderId: type: string format: uuid order: $ref: '#/components/schemas/MakerMatchOrder' required: - id - matchedSize - fillPrice - fillCost - orderId - order OrderExecutionSummary: type: object properties: clientOrderId: type: string feeRateBps: type: number example: 0 effectiveFeeBps: type: number example: 0 matched: type: boolean settlementStatus: type: string enum: - UNMATCHED - DELAYED - MATCHED - MINED - CONFIRMED - RETRYING - FAILED eligibleAt: type: string format: date-time tradeEventId: type: string txHash: type: string nullable: true totalsRaw: $ref: '#/components/schemas/OrderExecutionTotalsRawDto' required: - feeRateBps - effectiveFeeBps - matched - settlementStatus - totalsRaw MarketSlimDto: type: object properties: id: type: integer example: 7348 slug: type: string example: btc-up-or-down-1-hour title: type: string example: BTC Up or Down - Hourly status: type: string example: FUNDED enum: - CREATED - DRAFTED - FUNDED - LOCKED - RESOLVED yesPositionId: type: string example: 11514974713064423461... nullable: true noPositionId: type: string example: 14525308260861904048... nullable: true group: $ref: '#/components/schemas/MarketGroupSlimDto' required: - id - slug - title - status - yesPositionId - noPositionId HistoricalOrderOwner: type: object properties: id: type: integer account: type: string pattern: ^0x[a-fA-F0-9]{40}$ client: type: string tradeWalletOption: type: string nullable: true enum: - eoa - smartWallet smartWallet: type: string nullable: true points: type: number enum: - 0 referredUsersCount: type: number enum: - 0 required: - id - account - client - tradeWalletOption - smartWallet - points - referredUsersCount MakerMatchOrder: type: object properties: id: type: string format: uuid maker: type: string pattern: ^0x[a-fA-F0-9]{40}$ price: type: string nullable: true example: '0.55' side: type: number enum: - 0 - 1 tokenId: type: string owner: $ref: '#/components/schemas/MakerMatchOwner' required: - id - maker - price - side - tokenId - owner OrderExecutionTotalsRawDto: type: object properties: contractsGross: type: string example: '1000000' contractsFee: type: string example: '1000' contractsNet: type: string example: '999000' usdGross: type: string example: '500000' usdFee: type: string example: '500' usdNet: type: string example: '499500' required: - contractsGross - contractsFee - contractsNet - usdGross - usdFee - usdNet MarketGroupSlimDto: type: object properties: id: type: integer example: 42 slug: type: string example: btc-price-markets title: type: string example: BTC Price Markets required: - id - slug - title MakerMatchOwner: type: object properties: id: type: integer account: type: string pattern: ^0x[a-fA-F0-9]{40}$ client: type: string tradeWalletOption: type: string nullable: true enum: - eoa - smartWallet smartWallet: type: string nullable: true username: type: string displayName: type: string pfpUrl: type: string nullable: true socialUrl: type: string nullable: true points: type: number enum: - 0 referredUsersCount: type: number enum: - 0 required: - id - account - client - tradeWalletOption - smartWallet - username - displayName - pfpUrl - socialUrl - points - referredUsersCount securitySchemes: HmacAuth: type: apiKey in: header name: lmts-api-key description: >- Scoped API token with HMAC-SHA256 signing. Requires three headers: lmts-api-key (token ID), lmts-timestamp (ISO-8601), lmts-signature (Base64-encoded HMAC). See Authentication docs for details. ````