# OKX Swap OKX historical data for **all its perpetual swap instruments** is available since **2019-03-30**. {% embed url="" %} See OKX Swap historical data coverage: available symbols, channels, date ranges and incidents {% endembed %} ### Downloadable **CSV** files Historical CSV datasets for the first day of each month are **available to download without API key**. See [downloadable CSV files documentation](https://docs.tardis.dev/downloadable-csv-files/overview). {% hint style="info" %} Liquidations datasets are available since 2020-12-18. {% endhint %} | data type | symbol | date | | | --------------------- | ------------ | ---------- | -------------------------------------------------------------------------------------------------------------- | | incremental\_book\_L2 | BTC-USD-SWAP | 2020-01-01 | [Download sample](https://datasets.tardis.dev/v1/okex-swap/incremental_book_L2/2020/01/01/BTC-USD-SWAP.csv.gz) | | trades | BTC-USD-SWAP | 2020-01-01 | [Download sample](https://datasets.tardis.dev/v1/okex-swap/trades/2020/01/01/BTC-USD-SWAP.csv.gz) | | derivative\_ticker | BTC-USD-SWAP | 2020-01-01 | [Download sample](https://datasets.tardis.dev/v1/okex-swap/derivative_ticker/2020/01/01/BTC-USD-SWAP.csv.gz) | ### API Access and data format Historical data format is the same as provided by real-time OKX WebSocket **v5** API with addition of local timestamps (before 2021-12-23 it was **v3** API version). If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](https://docs.tardis.dev/downloadable-csv-files/overview) or official [client libs](https://docs.tardis.dev/api/quickstart) that can perform data normalization client-side. {% tabs %} {% tab title="Python" %} ```python # pip install tardis-dev import asyncio from tardis_dev import Channel, replay async def main(): async for local_timestamp, message in replay( exchange="okex-swap", from_date="2024-01-01", to_date="2024-01-02", filters=[Channel(name="books-l2-tbt", symbols=["BTC-USD-SWAP"])], api_key="YOUR_API_KEY", ): # messages as provided by OKX real-time stream print(message) asyncio.run(main()) ``` See [Python client docs](https://docs.tardis.dev/python-client/quickstart). {% endtab %} {% tab title="Node.js" %} ```javascript // npm install tardis-dev import { replay } from 'tardis-dev'; const messages = replay({ exchange: 'okex-swap', from: '2024-01-01', to: '2024-01-02', filters: [{ channel: 'books-l2-tbt', symbols: ['BTC-USD-SWAP'] }], apiKey: 'YOUR_API_KEY' }); // messages as provided by OKX real-time stream for await (const { localTimestamp, message } of messages) { console.log(localTimestamp, message); } ``` See [Node.js client docs](https://docs.tardis.dev/node-client/quickstart). {% endtab %} {% tab title="cURL & HTTP API" %} ```bash curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/okex-swap?from=2024-01-01&filters=[{"channel":"books-l2-tbt","symbols":["BTC-USD-SWAP"]}]&offset=0' ``` {% embed url="" %} Example API response for OKX Swap historical market data request {% endembed %} See [HTTP API docs](https://docs.tardis.dev/api/http-api-reference). {% endtab %} {% tab title="cURL & tardis-machine" %} ```bash curl -g 'localhost:8000/replay?options={"exchange":"okex-swap","filters":[{"channel":"books-l2-tbt","symbols":["BTC-USD-SWAP"]}],"from":"2024-01-01","to":"2024-01-02"}' ``` [Tardis-machine](https://docs.tardis.dev/tardis-machine/quickstart) is a locally runnable server that exposes API allowing efficiently requesting historical market data for whole time periods in contrast to [HTTP API](https://docs.tardis.dev/api/http-api-reference) that provides data only in minute by minute slices. See [tardis-machine](https://docs.tardis.dev/tardis-machine/quickstart) docs. {% endtab %} {% endtabs %} ### Captured real-time channels {% embed url="" %} See OKX WebSocket API docs providing documentation for each captured channel's format {% endembed %} {% hint style="info" %} Click any channel below to see [HTTP API](https://docs.tardis.dev/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it. {% endhint %} **Current channels (API v5, since 2021-12-23):** * [trades](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2024-01-01\&filters=\[{%22channel%22:%22trades%22,%22symbols%22:\[%22BTC-USDT-SWAP%22]}]) Public swap trade executions stream * [trades-all](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2024-01-01\&filters=\[{%22channel%22:%22trades-all%22,%22symbols%22:\[%22BTC-USDT-SWAP%22]}]) — available since **2023-10-19** All trades stream including non-aggregated trade messages * [books-l2-tbt](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2024-01-01\&filters=\[{%22channel%22:%22books-l2-tbt%22,%22symbols%22:\[%22BTC-USDT-SWAP%22]}]) Tick-by-tick L2 swap order book updates (10ms) * [books](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2023-06-01\&filters=\[{%22channel%22:%22books%22,%22symbols%22:\[%22BTC-USDT-SWAP%22]}]) — available since **2023-02-24**, until **2024-07-19** Incremental swap order book depth updates (100ms) * [bbo-tbt](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2024-01-01\&filters=\[{%22channel%22:%22bbo-tbt%22,%22symbols%22:\[%22BTC-USDT-SWAP%22]}]) — available since **2022-05-05** Tick-by-tick best bid and offer updates (10ms) * [tickers](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2024-01-01\&filters=\[{%22channel%22:%22tickers%22,%22symbols%22:\[%22BTC-USDT-SWAP%22]}]) 24h swap ticker updates (100ms) * [liquidations](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2024-01-01\&filters=\[{%22channel%22:%22liquidations%22,%22symbols%22:\[%22BTC-USDT-SWAP%22]}]) Liquidation events with at most one update per second per contract * [liquidation-orders](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2024-03-01\&filters=\[{%22channel%22:%22liquidation-orders%22}]) — available since **2023-03-30** Liquidation orders with at most one update per second per contract * [open-interest](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2024-01-01\&filters=\[{%22channel%22:%22open-interest%22,%22symbols%22:\[%22BTC-USDT-SWAP%22]}]) Open interest updates (3s) * [mark-price](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2024-01-01\&filters=\[{%22channel%22:%22mark-price%22,%22symbols%22:\[%22BTC-USDT-SWAP%22]}]) Mark price updates with keepalive up to 10s when unchanged (200ms) * [funding-rate](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2024-01-01\&filters=\[{%22channel%22:%22funding-rate%22,%22symbols%22:\[%22BTC-USDT-SWAP%22]}]) Funding rate updates with upcoming funding time (30s to 90s cadence) * [index-tickers](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2024-01-01\&filters=\[{%22channel%22:%22index-tickers%22}]) Index ticker updates with keepalive up to 1m when unchanged (100ms) * [price-limit](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2024-01-01\&filters=\[{%22channel%22:%22price-limit%22,%22symbols%22:\[%22BTC-USDT-SWAP%22]}]) Price limit updates (200ms) * [status](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2024-01-01\&filters=\[{%22channel%22:%22status%22}]) Exchange status and maintenance notifications * [instruments](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2024-01-01\&filters=\[{%22channel%22:%22instruments%22}]) Instrument state updates (listing, suspension, parameter changes) * [long-short-account-ratio](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2024-01-01\&filters=\[{%22channel%22:%22long-short-account-ratio%22}]) Long/short account ratio snapshots from REST statistics endpoint (1m) * [taker-volume](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2024-01-01\&filters=\[{%22channel%22:%22taker-volume%22}]) Taker buy/sell volume snapshots from REST statistics endpoint (1m) * [public-block-trades](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2024-01-01\&filters=\[{%22channel%22:%22public-block-trades%22}]) — available since **2023-01-01** Public block trades stream (15m) * [public-struc-block-trades](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2024-01-01\&filters=\[{%22channel%22:%22public-struc-block-trades%22}]) — available since **2023-01-01** Public structured block trades stream (15m) * [taker-volume-contract](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2024-09-01\&filters=\[{%22channel%22:%22taker-volume-contract%22}]) — available since **2024-08-08** Contract-level taker buy/sell volume snapshots from REST statistics endpoint (1m) * [long-short-account-ratio-contract-top-trader](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2024-09-01\&filters=\[{%22channel%22:%22long-short-account-ratio-contract-top-trader%22}]) — available since **2024-08-08** Contract-level top-trader long/short account ratio snapshots (1m) * [long-short-position-ratio-contract-top-trader](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2024-09-01\&filters=\[{%22channel%22:%22long-short-position-ratio-contract-top-trader%22}]) — available since **2024-08-08** Contract-level top-trader long/short position ratio snapshots (1m) * [long-short-account-ratio-contract](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2024-09-01\&filters=\[{%22channel%22:%22long-short-account-ratio-contract%22}]) — available since **2024-08-08** Contract-level long/short account ratio snapshots from REST statistics endpoint (1m) **Legacy channels (API v3, until 2021-12-23):** * [swap/trade](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2020-01-01\&filters=\[{%22channel%22:%22swap/trade%22,%22symbols%22:\[%22BTC-USD-SWAP%22]}]) — until **2021-12-23** Public swap trade executions stream * [swap/depth](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2019-08-01\&filters=\[{%22channel%22:%22swap/depth%22,%22symbols%22:\[%22BTC-USD-SWAP%22]}]) — until **2020-02-13** Incremental swap order book updates (legacy depth channel, 100ms) * [swap/depth\_l2\_tbt](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2020-06-01\&filters=\[{%22channel%22:%22swap/depth_l2_tbt%22,%22symbols%22:\[%22BTC-USD-SWAP%22]}]) — available since **2020-02-07**, until **2021-12-23** Tick-by-tick L2 swap order book updates with sequencing * [swap/ticker](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2020-01-01\&filters=\[{%22channel%22:%22swap/ticker%22,%22symbols%22:\[%22BTC-USD-SWAP%22]}]) — until **2021-12-23** 24h swap ticker updates * [swap/liquidation](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2021-01-01\&filters=\[{%22channel%22:%22swap/liquidation%22}]) — available since **2020-12-18**, until **2021-12-23** Swap liquidation events * [swap/funding\_rate](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2020-01-01\&filters=\[{%22channel%22:%22swap/funding_rate%22,%22symbols%22:\[%22BTC-USD-SWAP%22]}]) — until **2021-12-23** Funding rate updates * [swap/mark\_price](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2020-01-01\&filters=\[{%22channel%22:%22swap/mark_price%22,%22symbols%22:\[%22BTC-USD-SWAP%22]}]) — until **2021-12-23** Mark price with keepalive up to 10s when unchanged * [index/ticker](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2020-01-01\&filters=\[{%22channel%22:%22index/ticker%22}]) — available since **2019-09-20**, until **2021-12-23** Index ticker for swap contracts with keepalive up to 1m when unchanged * [system/status](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2020-08-01\&filters=\[{%22channel%22:%22system/status%22}]) — available since **2020-07-01**, until **2021-12-23** Exchange status and maintenance notifications * [information/sentiment](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2021-01-01\&filters=\[{%22channel%22:%22information/sentiment%22}]) — available since **2020-10-28**, until **2021-12-23** Market sentiment ratio metrics (75s, REST polling) * [information/long\_short\_ratio](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2021-01-01\&filters=\[{%22channel%22:%22information/long_short_ratio%22}]) — available since **2020-10-28**, until **2021-12-23** Long/short account ratio metrics (75s, REST polling) * [information/margin](https://api.tardis.dev/v1/data-feeds/okex-swap?from=2021-01-01\&filters=\[{%22channel%22:%22information/margin%22}]) — available since **2020-10-28**, until **2021-12-23** Margin ratio metrics (75s, REST polling) ### Market data collection details [Market data collection infrastructure](https://docs.tardis.dev/faq/general#what-is-your-infrastructure-setup) for OKX Swap since **2022-05-04**T16:45 is located in AWS HK region (Hong Kong, China, VPC colo setup), before that, starting since **2020-05-15** it was located in GCP asia-northeast1 (Tokyo, Japan) and initially it was located in GCP europe-west2 region (London, UK). Real-time market data is captured via **multiple WebSocket connections** to `wss://awscolows1.okx.com:8443/ws/v5/public`. {% hint style="info" %} OKX servers are located in Alibaba Cloud cn-hongkong region (Hong Kong, China). {% endhint %}