> ## 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.
# Derive Scoped Token
> Creates a new scoped API token for the authenticated partner. Requires Privy authentication (Bearer token). The token secret is returned once at creation — store it securely. Requested scopes must be a subset of the partner's allowed scopes.
Requires **Privy authentication**. Pass the `token` field from the Privy authenticate response (the identity token) in the `identity` header as `Bearer `. Do **not** use `privy_access_token`. HMAC and API key auth are not accepted for this endpoint.
The `secret` field is returned **once** at creation time. Store it securely — it cannot be retrieved again.
### Scopes
| Scope | Description |
| ------------------- | ------------------------------------------------------------------------------------------ |
| `trading` | Place and cancel orders. Default scope. Required for `delegated_signing`. |
| `account_creation` | Create sub-account profiles under your partner account. |
| `delegated_signing` | Server signs orders on behalf of sub-accounts via Privy server wallet. Requires `trading`. |
If `scopes` is omitted from the request body, the token is created with `["trading"]` only.
Requested scopes must be a subset of your partner's `allowedScopes` (see [Get Partner Capabilities](/api-reference/api-tokens/get-capabilities)).
### Using the token
After deriving a token, authenticate subsequent requests using HMAC signing with the returned `apiKey` (token ID) and `secret`. See [HMAC Request Signing](/developers/authentication#hmac-request-signing) for the signing protocol.
## OpenAPI
````yaml POST /auth/api-tokens/derive
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:
/auth/api-tokens/derive:
post:
tags:
- API Tokens
summary: Derive scoped API token
description: >-
Creates a new scoped API token for the authenticated partner. Requires
Privy authentication (Bearer token). The token secret is returned once
at creation — store it securely. Requested scopes must be a subset of
the partner's allowed scopes.
operationId: ApiTokenController_deriveToken
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeriveApiTokenRequest'
responses:
'201':
description: Token created successfully. The secret is only returned once.
content:
application/json:
schema:
$ref: '#/components/schemas/DeriveApiTokenResponse'
'400':
description: Invalid scopes or profile not found
'401':
description: Requires Privy authentication
'403':
description: >-
Token management not enabled or requested scopes not allowed for
this partner
security:
- HmacAuth: []
components:
schemas:
DeriveApiTokenRequest:
type: object
properties:
label:
type: string
maxLength: 128
description: Human-readable label for the token
example: production-trading-bot
scopes:
type: array
items:
type: string
enum:
- trading
- account_creation
- delegated_signing
description: >-
Scopes to grant. Defaults to ["trading"] if omitted. Must be a
subset of the partner's allowed scopes. `delegated_signing` requires
`trading`.
example:
- trading
- account_creation
DeriveApiTokenResponse:
type: object
properties:
apiKey:
type: string
description: >-
The token ID, used as the `lmts-api-key` header value for HMAC
requests
example: dGVzdC10b2tlbi0x
secret:
type: string
description: >-
Base64-encoded secret for HMAC signing. Returned once — store
securely.
example: c2VjcmV0LWtleS1leGFtcGxlLWJhc2U2NC1lbmNvZGVk
tokenId:
type: string
description: Same as apiKey. The unique token identifier.
example: dGVzdC10b2tlbi0x
createdAt:
type: string
format: date-time
description: Token creation timestamp
scopes:
type: array
items:
type: string
description: Granted scopes
example:
- trading
- account_creation
profile:
type: object
properties:
id:
type: integer
description: Partner profile ID
example: 42
account:
type: string
description: Partner wallet address
example: '0x27b4afBD88fE7c88c6897BB0b4ADE338D0401E37'
required:
- apiKey
- secret
- tokenId
- createdAt
- scopes
- profile
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.
````