> ## 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 History > Paginated history including AMM, CLOB trades, splits/merges, NegRisk conversions. Partner API tokens with `delegated_signing` scope may read a sub-account by sending the `x-on-behalf-of: ` header. **CLOB fills live here.** Limitless does not expose a dedicated fills endpoint. This endpoint returns every CLOB fill for the authenticated account as a history entry. Use the `strategy` field to distinguish fill types: * `Limit Buy` / `Limit Sell` — CLOB **maker** fills (a resting limit order of yours was hit). * `Market Buy` / `Market Sell` — CLOB **taker** fills (your order crossed the book on submission). * `Buy` / `Sell` — AMM trades (also available via [Get Trades](/api-reference/portfolio/trades)). * `Split` / `Merge` — position split/merge. * `Convert` — NegRisk conversion. * `Claim` — winnings redemption. Each entry includes `outcomeTokenPrice` (effective fill price), `outcomeTokenAmounts`, `collateralAmount`, `blockTimestamp`, and `transactionHash` (present once settled on-chain). Paginate with `cursor` and `limit`. **Deposits and withdrawals are not included.** This endpoint covers on-platform activity only (fills, splits, merges, conversions, and claims). Raw USDC deposits and withdrawal transfers are not returned here and the API does not expose a dedicated deposit/withdrawal history endpoint. [`POST /portfolio/withdraw`](/api-reference/portfolio/withdraw) executes a withdrawal but does not return past withdrawals. To reconstruct transfers, query the on-chain USDC transfers to and from your account on Base. **No historical orderbook.** The API does not expose historical orderbook snapshots. [Get Orderbook](/api-reference/trading/orderbook) returns only the current live snapshot. To reconstruct past activity for a market, combine your own fill history from this endpoint with [Get Historical Prices](/api-reference/trading/historical-price) and [Get Feed Events](/api-reference/markets/feed-events). ## OpenAPI ````yaml GET /portfolio/history 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: /portfolio/history: get: tags: - Portfolio summary: Get History description: >- Paginated history including AMM, CLOB trades, splits/merges, NegRisk conversions. Partner API tokens with `delegated_signing` scope may read a sub-account by sending the `x-on-behalf-of: ` header. operationId: PortfolioController_getHistory parameters: - name: cursor required: false in: query description: Opaque cursor for cursor-based pagination. Omit for first page. schema: type: string - name: market required: false in: query description: >- Market slug. When set, only history for that market is returned. Cursors are only valid together with the same market value they were issued for. schema: type: string - name: limit required: true in: query description: Number of items per page schema: example: 20 type: number responses: '200': description: Paginated history of all user actions content: application/json: schema: $ref: '#/components/schemas/HistoryResponseDto' '400': description: Invalid pagination parameters '401': description: Unauthorized security: - bearer: [] - limitless_session: [] components: schemas: HistoryResponseDto: type: object properties: data: description: List of history entries type: array items: $ref: '#/components/schemas/HistoryEntryDto' totalCount: type: number description: Total count of entries (null in cursor mode) example: 8 nullable: true nextCursor: type: string description: Opaque cursor for the next page (null when no more pages) nullable: true required: - data - totalCount HistoryEntryDto: type: object properties: blockTimestamp: type: number description: Block timestamp of the operation example: 1744115608 tradeEventId: type: string description: CLOB trade event ID orderId: type: string description: CLOB order ID makerMatchId: type: string description: CLOB maker match ID collateralAmount: type: string description: Collateral amount involved in the operation example: '0' market: description: Market information allOf: - $ref: '#/components/schemas/HistoryMarketDto' outcomeTokenAmount: type: string description: Amount of outcome tokens involved example: '100' outcomeTokenAmounts: description: Amounts of outcome tokens for each outcome example: - '100' - '0' type: array items: type: string outcomeIndex: type: number description: Index of the outcome example: 0 outcomeTokenPrice: type: number description: Price of the outcome token example: 0.5 strategy: type: string description: Type of operation example: Convert enum: - Buy - Sell - Limit Buy - Limit Sell - Market Buy - Market Sell - Split - Merge - Convert transactionHash: type: string description: Transaction hash of the operation example: '0x992f36465f938b21a6a5fe3c417c98c3268a616a05479d2dc53870c6cd1a0761' required: - blockTimestamp - collateralAmount - market - outcomeTokenAmount - outcomeTokenAmounts - outcomeIndex - outcomeTokenPrice - strategy HistoryMarketDto: type: object properties: closed: type: boolean description: Whether the market is closed example: false collateral: type: object description: Collateral token information example: symbol: USDC id: 7 decimals: 6 group: description: Market group information allOf: - $ref: '#/components/schemas/HistoryMarketGroupDto' condition_id: type: string description: Condition ID of the market example: '0x08518bc4bb8a3dbb89aac4425ace0876b94a5dfa77dee47a20737a19cf67e325' funding: type: number description: Market funding amount example: 0 id: type: number description: Market ID example: 980 slug: type: string description: Market slug example: market-1-1744046422691 title: type: string description: Market title example: Market 1 deadline: type: string description: Market deadline example: '2025-04-11T22:34:56.000Z' imageUrl: type: string description: Market logo image URL nullable: true example: https://storage.googleapis.com/limitless-exchange-assets/market.png required: - closed - collateral - group - condition_id - funding - id - slug - title - deadline HistoryMarketGroupDto: type: object properties: id: type: number description: Unique identifier of the group example: 10000037 slug: type: string description: Slug identifier of the group example: positionconverted-test-1744046422596 title: type: string description: Title of the group example: PositionConverted test imageUrl: type: string description: Group logo image URL nullable: true example: https://storage.googleapis.com/limitless-exchange-assets/group.png status: type: string description: Status of the group example: FUNDED deadline: type: string description: Deadline for the group example: '2025-04-11T22:34:56.000Z' hidden: type: boolean description: Whether the group is hidden example: false txHash: type: string description: Transaction hash for the group example: null resolutionTxHash: type: string description: Resolution transaction hash example: null priorityIndex: type: number description: Priority index of the group example: 0 metadata: type: object description: Group metadata example: isBannered: false negRiskMarketId: type: string description: >- Onchain NegRisk market ID as identified by the NegriskAdapter smart-contract example: '0xe103633b40e9b664f8acc89e8cf7b7916475961ae1708a249fa5d6c933168c00' createdAt: type: string description: Creation timestamp example: '2025-04-07T17:20:22.135Z' updatedAt: type: string description: Last update timestamp example: '2025-04-07T17:22:08.464Z' required: - id - slug - title - status - deadline - hidden - priorityIndex - metadata - negRiskMarketId - createdAt - updatedAt securitySchemes: bearer: scheme: bearer bearerFormat: JWT description: JWT token for API access (alternative to cookie auth) type: http ````