How to View Historical Futures Orders on OKX

Accessing Historical Futures Orders via OKX Web Interface

1. Log in to your OKX account and navigate to the Futures trading section.

2. Click on the Orders tab located at the top of the trading interface.

3. Select the History sub-tab to display completed, canceled, and expired futures orders.

4. Use the date range filter to specify the start and end timestamps for retrieval—default window covers the last 90 days.

5. Apply instrument filters such as BTC-USDT-SWAP or ETH-USDT-QUARTER to narrow results by contract type and underlying asset.

Retrieving Futures Order History via REST API

1. Initialize the TradeAPI class from python-okx with valid credentials and set flag='0' for production environment.

2. Call get_orders_history_archive method, passing parameters including instType='SWAP', instId='BTC-USDT-SWAP', and limit=100.

3. Paginate through responses using the before parameter—the value is extracted from the ordId field of the oldest record in each batch.

4. Parse returned JSON structure: each entry contains ordId, px, sz, side, state, fillSz, avgPx, and ts (millisecond timestamp).

5. Store raw responses in chronological order after reversing the default descending sort, then validate completeness by checking for gaps in ts values across consecutive pages.

Data Integrity and Time Range Constraints

1. OKX retains futures order history for up to 180 days on the web interface, but API access extends to 365 days for institutional-tier accounts.

2. Records older than 90 days require explicit instType specification—omitting it returns empty data even when instId is provided.

3. The state field includes values such as filled, canceled, partially_filled, expired, and failed; failed indicates order rejection due to insufficient margin or invalid parameters.

4. Timestamps are always in UTC and do not adjust for daylight saving; local time conversion must be handled client-side using datetime.timezone.utc in Python.

5. Order IDs are immutable strings prefixed with ORD followed by 18 alphanumeric characters—no numeric sequence guarantees exist across batches.

Common Pitfalls During Historical Order Retrieval

1. Using get_orders_history instead of get_orders_history_archive yields only the most recent 90 days regardless of pagination attempts.

2. Passing an invalid before value—such as a non-existent ordId or one older than 365 days—triggers error code 50015 ('Invalid before parameter').

3. Omitting instType while specifying instId returns HTTP 200 with empty data array instead of throwing an explicit validation error.

4. Mixing flag='1' (demo mode) with production instId values causes silent mismatches—orders placed in demo mode never appear in real-account history endpoints.

5. Assuming fillSz equals sz for filled orders ignores partial fills from liquidation-triggered executions, where fillSz may exceed original sz due to cascading market impact.

Frequently Asked Questions

Q: Can I retrieve historical futures orders without API keys? No. All endpoints under /api/v5/trade/orders-history-archive require full authentication including OK-ACCESS-KEY, OK-ACCESS-SIGN, OK-ACCESS-TIMESTAMP, and OK-ACCESS-PASSPHRASE. Public endpoints do not expose order history.

Q: Why does the same ordId appear in both orders-history and orders-history-archive responses? This occurs when an order was placed within the last 90 days and also qualifies for archival retention. The system maintains dual indexing but guarantees identical payload content across both endpoints for overlapping records.

Q: Is there a rate limit for get_orders_history_archive calls? Yes. The endpoint enforces 20 requests per 2 seconds per IP address. Exceeding this triggers HTTP 429 with Retry-After header indicating mandatory pause duration.

Q: Do stop-market orders appear in historical order records if they were never triggered? Yes. Untriggered conditional orders remain in history with state='canceled' if manually removed, or state='pending' if still active beyond their expiration time, which defaults to 30 days unless overridden during placement.