(field `id`) |
#### Query Parameters
| Name | Type | Description |
| -------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| from\* | string | requested UTC start date of historical market data feed (e.g.: `2019-04-05` or `2019-04-05T01:02:00.000Z`) |
| offset | number | Minute offset that, together with `from`, specifies the first minute of historical data returned. For example, `from=2019-04-05`, `offset=2` and default `sliceSize=1` returns data between `2019-04-05T00:02:00.000Z` and `2019-04-05T00:03:00.000Z`. With `sliceSize` greater than `1`, the response starts at the same offset and covers consecutive minutes. Minute boundaries are based on `localTimestamp` (when we received the message), not exchange event timestamps. An empty response for a given offset is normal and means no data was recorded during that minute. |
| filters | string | URL-encoded JSON string in {channel:string, symbols?: string\[]}\[] format with optional historical market data filters, e.g.: \[{"channel":"trade", "symbols":\["XBTUSD"]}]
To request all active symbols for a channel, omit symbols or pass an empty symbols array. Use this when you need the whole channel instead of sending one request per symbol.
If you need selected symbols, put them in one symbols array. One filter can include up to 50 symbols.
Symbols are case-sensitive and must match the format returned by the /exchanges/:exchange API. For example, Binance uses lowercase symbols (btcusdt), not uppercase.
To get the list of allowed channels and symbols for each exchange, use the
Subscriptions with limited scope (e.g., perpetuals data plan) must provide explicit symbols in filters. Omitting symbols on a limited-scope plan will return an entitlement error.
|
| sliceSize | number | Number of consecutive minutes returned by one request. Valid values are whole integers from 1 to 10. Default is 1.
Values greater than 1 require the filters query parameter.
sliceSize reduces /data-feeds request count when replaying consecutive minutes with the same filters.
|
| compression | string | Optional response compression override for `/data-feeds`. Allowed values are `gzip`, `zstd` and `zstd-multiframe`. Prefer `zstd-multiframe` for Zstandard-capable clients; use `zstd` only when the decoder cannot consume concatenated frames. |
#### Headers
| Name | Type | Description |
| --------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization | string | For authenticated requests, provide the Authorization header with value `Bearer YOUR_API_KEY`. Without API key historical data feeds for the first day of each month are available. |
| Accept-Encoding | string | Required unless `compression` is set. Use `gzip` for default responses. To request Zstandard, set `compression=zstd`; `Accept-Encoding: zstd` alone is not enough. |
{% tabs %}
{% tab title="200: OK " %}
Each line contains local timestamp (ISO 8601) and JSON message in exchange native data format. Compression is indicated by the `content-encoding` response header and can be `zstd` or `gzip`.
The `x-slice-size` response header contains the slice size used for this response. The `x-suggested-slice-size` response header contains a recommended `sliceSize` for later requests with the same exchange, filters and compression. Official Node.js and Python clients do this automatically.
`compression=zstd-multiframe` is more efficient and usually returns faster because it avoids server-side recompression. The response uses `content-encoding: zstd` and contains one independent Zstandard frame per minute, including one frame when `sliceSize=1`. Clients must decode every concatenated frame; the official clients handle this automatically. Plain `compression=zstd` remains available for decoders that support only a single Zstandard stream.
```javascript
2019-04-01T00:00:34.8345516Z {"table":"trade","action":"insert","data":[{"timestamp":"2019-04-01T00:00:34.815Z","symbol":"ETHUSD","side":"Sell","size":7000,"price":141.2,"tickDirection":"ZeroMinusTick","trdMatchID":"baa369de-cb3b-b18f-685e-0ffdec00358c","grossValue":98840000,"homeNotional":28.654468050268125,"foreignNotional":4046.010888697859}]}
2019-04-01T00:00:34.8346465Z {"table":"orderBookL2","action":"update","data":[{"symbol":"ETHUSD","id":29699997176,"side":"Buy","size":65350}]}
2019-04-01T00:00:34.8395743Z {"table":"orderBookL2","action":"update","data":[{"symbol":"BCHM19","id":32999999571,"side":"Sell","size":333},{"symbol":"BCHM19","id":32999999572,"side":"Sell","size":576},{"symbol":"BCHM19","id":32999999573,"side":"Sell","size":353}]}
2019-04-01T00:00:34.8567501Z {"table":"trade","action":"insert","data":[{"timestamp":"2019-04-01T00:00:34.830Z","symbol":"XBTUSD","side":"Buy","size":182,"price":4089,"tickDirection":"ZeroPlusTick","trdMatchID":"fa93bd9b-e1b6-d38d-f4d4-65337a766e34","grossValue":4450992,"homeNotional":0.04450992,"foreignNotional":182}]}
2019-04-01T00:00:34.8567741Z {"table":"orderBookL2","action":"update","data":[{"symbol":"XBTUSD","id":8799591100,"side":"Sell","size":351568}]}
2019-04-01T00:00:34.8567783Z {"table":"orderBookL2","action":"update","data":[{"symbol":"ETHUSD","id":29699997176,"side":"Buy","size":55349}]}
2019-04-01T00:00:34.8567812Z {"table":"orderBookL2","action":"update","data":[{"symbol":"ETHUSD","id":29699997167,"side":"Sell","size":430305}]}
2019-04-01T00:00:34.8567847Z {"table":"orderBookL2","action":"insert","data":[{"symbol":"EOSM19","id":33199989652,"side":"Buy","size":216,"price":0.0010348}]}
2019-04-01T00:00:34.8605618Z {"table":"orderBookL2","action":"update","data":[{"symbol":"XBTUSD","id":8799591850,"side":"Buy","size":154511}]}
2019-04-01T00:00:34.8605944Z {"table":"orderBookL2","action":"update","data":[{"symbol":"TRXM19","id":33299999258,"side":"Sell","size":1493}]}
2019-04-01T00:00:34.8617223Z {"table":"orderBookL2","action":"update","data":[{"symbol":"ADAM19","id":33099998260,"side":"Buy","size":224039}]}
```
{% endtab %}
{% tab title="400: Bad Request " %}
Invalid request parameters. This includes `sliceSize` values outside `1` to `10`, non-integer `sliceSize` values, and `sliceSize` greater than `1` without `filters`.
Example response headers:
```http
HTTP/1.1 400 Bad Request
content-type: application/json
```
Example response body:
```json
{
"code": 300,
"message": "Invalid 'sliceSize' query string param value: '11'. Please provide a whole integer from 1 to 10."
}
```
{% endtab %}
{% tab title="429: Too Many Requests " %}
Too many requests. Retry later. A 429 response for filtered `/data-feeds` requests may include `x-suggested-slice-size`; use that value as `sliceSize` on later requests with the same exchange, filters and compression.
Example response headers:
```http
HTTP/1.1 429 Too Many Requests
content-type: application/json
x-suggested-slice-size: 5
```
Example response body:
```json
{
"code": 30,
"message": "Too many requests. Retry later. Use x-suggested-slice-size as sliceSize on later filtered /data-feeds requests with the same exchange, filters and compression."
}
```
{% endtab %}
{% endtabs %}
{% hint style="info" %}
Lines in the response are ordered by capture time. When multiple events share the same millisecond exchange timestamp, use line order as the tie-breaker — see [event ordering FAQ](/faq/data#how-are-events-ordered-when-multiple-messages-share-the-same-timestamp).
{% endhint %}
{% hint style="info" %}
Not sure [what is the channel field?](/faq/data#what-is-the-channel-field-used-in-the-http-api-and-client-libs-replay-functions)
{% endhint %}
{% hint style="info" %}
See [downloadable CSV files documentation](/downloadable-csv-files/overview) and related [datasets API](/downloadable-csv-files/api#datasets-api-reference) if you'd like to access historical tick-level trades, order book snapshots, incremental order book L2 updates, options chains, quotes, derivative tickers and liquidations datasets in daily intervals split by exchange, data type and symbol. It may be faster and more native to your toolkit to access historical data this way.
{% endhint %}
{% tabs %}
{% tab title="Python" %}
```python
import json
import requests
def get_data_feeds():
filters = [
{"channel": "trade", "symbols": ["btcusdt"]},
{"channel": "depth", "symbols": ["btcusdt"]},
]
qs_params = {"from": "2024-03-01", "offset": 3, "filters": json.dumps(filters)}
headers = {"Authorization": "Bearer YOUR_API_KEY"}
url = "https://api.tardis.dev/v1/data-feeds/binance"
response = requests.get(url, headers=headers, params=qs_params, stream=True)
for line in response.iter_lines():
# empty lines in response are being used as markers
# for disconnect events that occurred when collecting the data
if len(line) <= 1:
continue
parts = line.decode("utf-8").split(" ")
local_timestamp = parts[0]
message = json.loads(parts[1])
# local_timestamp string marks message arrival timestamp
# message is a message dict as provided by exchange real-time stream
print(local_timestamp, message)
get_data_feeds()
```
{% hint style="info" %}
The [Python client](/python-client/quickstart) adds local caching and date-range replay on top of this endpoint, so you can request longer periods while the client handles raw data replay requests.
{% endhint %}
{% endtab %}
{% tab title="Node.js" %}
```javascript
import split2 from 'split2'
import { Readable } from 'node:stream'
const serialize = (options) => encodeURIComponent(JSON.stringify(options))
const filters = serialize([
{
channel: 'trade',
symbols: ['btcusdt']
},
{
channel: 'depth',
symbols: ['btcusdt']
}
])
const baseUrl = 'https://api.tardis.dev/v1/data-feeds/binance'
const url = `${baseUrl}?from=2024-03-01&offset=3&filters=${filters}`
const response = await fetch(url)
const lines = Readable.fromWeb(response.body).pipe(split2())
for await (const line of lines) {
// empty lines in response are being used as markers
// for disconnect events that occurred when collecting the data
if (line.length === 0) {
continue
}
const parts = line.split(' ')
const localTimestamp = parts[0]
const message = JSON.parse(parts[1])
// localTimestamp string marks message arrival timestamp
// message is a message dict as provided by exchange real-time stream
console.log(localTimestamp, message)
}
```
{% hint style="info" %}
The [Node.js client](/node-client/quickstart) adds local caching, date-range replay, and normalized data helpers on top of this endpoint, so you can request longer periods while the client handles raw data replay requests.
{% endhint %}
{% endtab %}
{% tab title="cURL" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/binance?from=2024-03-01&filters=[{"channel":"trade","symbols":["btcusdt"]}]&offset=3'
```
{% embed url="" %}
Click to see API response in the browser
{% endembed %}
{% endtab %}
{% endtabs %}
#### Sample requests
{% embed url="" %}
Full BitMEX data feed from 2019-04-01T00:02:00.000Z to 2019-04-01T00:03:00.000Z
{% endembed %}
{% embed url="]" %}
BitMEX trades for all instruments from 2019-05-01T00:00:00.000Z to 2019-05-01T00:01:00.000Z
{% endembed %}
{% embed url="]" %}
BitMEX trades for XBTUSD from 2019-06-01T00:00:00.000Z to 2019-06-01T00:01:00.000Z
{% endembed %}
{% embed url="" %}
BitMEX trades for XBTUSD from 2019-06-01T00:00:00.000Z to 2019-06-01T00:05:00.000Z (`sliceSize=5`)
{% endembed %}
{% embed url="" %}
Full Deribit data feed from 2019-06-01T00:10:00.000Z to 2019-06-01T00:11:00.000Z
{% endembed %}
## /exchanges
`GET` `https://api.tardis.dev/v1/exchanges`
Gets the list of all supported exchanges that historical market data is available for.
{% tabs %}
{% tab title="200 Response contains JSON array of supported exchanges with basic details for each" %}
Example response shortened for readability. Use the live endpoint for the current full exchange list.
```javascript
[
{
"id": "bitmex",
"name": "BitMEX",
"enabled": true,
"supportsDatasets": true,
"availableSince": "2019-03-30T00:00:00.000Z",
"availableChannels": ["trade", "orderBookL2", "quote", "liquidation", "instrument", "..."]
},
{
"id": "deribit",
"name": "Deribit",
"enabled": true,
"supportsDatasets": true,
"availableSince": "2019-03-30T00:00:00.000Z",
"availableChannels": ["trades", "book", "ticker", "deribit_price_index", "..."]
},
...
]
```
{% endtab %}
{% endtabs %}
#### Sample request
{% embed url="" %}
List of all supported exchanges that historical market data is available for
{% endembed %}
## /exchanges/:exchange
`GET` `https://api.tardis.dev/v1/exchanges/:exchange`
Gets the exchanges details: available symbols, availability dates, available channels, CSV datasets info, incidents etc.
#### Path Parameters
| Name | Type | Description |
| ------------------------------------------ | ------ | --------------------------------------------------------- |
| exchange\* | string | one of (field `id`) |
{% tabs %}
{% tab title="200 Response contains JSON object with exchange details - available symbols, available channels, CSV datasets info, incidents etc." %}
```javascript
{
"id": "bitmex",
"name": "BitMEX",
"enabled": true,
"availableSince": "2019-03-30T00:00:00.000Z",
"availableChannels": [
"trade",
"orderBookL2",
"quote",
"liquidation",
"instrument",
"connected",
"announcement",
"chat",
"publicNotifications",
"settlement",
"funding",
"insurance",
"orderBookL2_25",
"orderBook10",
"quoteBin1m",
"quoteBin5m",
"quoteBin1h",
"quoteBin1d",
"tradeBin1m",
"tradeBin5m",
"tradeBin1h",
"tradeBin1d"
],
"availableSymbols": [
{
"id": "XBTUSD",
"type": "perpetual",
"availableSince": "2019-03-30T00:00:00.000Z"
},
{
"id": "XBTUSDT",
"type": "perpetual",
"availableSince": "2021-11-10T00:00:00.000Z"
},
{
"id": "ETHUSD",
"type": "perpetual",
"availableSince": "2019-03-30T00:00:00.000Z"
},
{
"id": "ETHUSDT",
"type": "perpetual",
"availableSince": "2021-11-10T00:00:00.000Z"
},
...
],
"incidentReports": [],
"channelDetails": [
{
"name": "trade",
"description": "Public trade executions stream",
"frequency": "real-time",
"frequencySource": "exchange-docs",
"exchangeDocsUrl": "https://www.bitmex.com/app/wsAPI",
"sourceFor": ["trade"],
"availableSince": "2019-03-30T00:00:00.000Z"
},
{
"name": "orderBookL2",
"description": "Order book snapshots and deltas by price level",
"frequency": "real-time",
"frequencySource": "exchange-docs",
"exchangeDocsUrl": "https://www.bitmex.com/app/wsAPI",
"sourceFor": ["book_change"],
"availableSince": "2019-03-30T00:00:00.000Z"
},
{
"name": "quote",
"description": "Best bid and ask quote updates",
"frequency": "real-time",
"frequencySource": "exchange-docs",
"exchangeDocsUrl": "https://www.bitmex.com/app/wsAPI",
"sourceFor": ["book_ticker"],
"availableSince": "2019-03-30T00:00:00.000Z"
},
{
"name": "liquidation",
"description": "Liquidation events stream",
"frequency": "real-time",
"frequencySource": "exchange-docs",
"exchangeDocsUrl": "https://www.bitmex.com/app/wsAPI",
"sourceFor": ["liquidation"],
"availableSince": "2019-03-30T00:00:00.000Z"
},
{
"name": "instrument",
"description": "Instrument state snapshots and deltas with bidPrice/askPrice/midPrice on 5s timer",
"frequency": "5s",
"frequencySource": "exchange-docs",
"exchangeDocsUrl": "https://www.bitmex.com/app/wsAPI",
"sourceFor": ["derivative_ticker"],
"availableSince": "2019-03-30T00:00:00.000Z"
}
],
"apiDocsUrl": "https://www.bitmex.com/app/wsAPI",
"dataCollectionDetails": {
"recorderDataCenter": {
"host": "GCP",
"regionId": "asia-northeast1",
"location": "Tokyo, Asia Pacific"
},
"wssConnection": {
"url": "wss://direct.bitmex.com:443/realtimePublic"
},
"exchangeDataCenter": {
"host": "AWS",
"regionId": "ap-northeast-1",
"location": "Tokyo, Asia Pacific"
}
},
"datasets": {
"formats": ["csv"],
"exportedFrom": "2019-03-30T00:00:00.000Z",
"exportedUntil": "2026-03-15T00:00:00.000Z",
"symbols": [
{
"id": "XBTUSD",
"type": "perpetual",
"availableSince": "2019-03-30T00:00:00.000Z",
"dataTypes": ["trades", "incremental_book_L2", "quotes", "derivative_ticker", "book_snapshot_25", "liquidations"]
},
...
]
}
}
```
{% endtab %}
{% endtabs %}
`channelDetails[].changes` is optional. When present, each entry describes previous user-visible metadata for the same public channel up to `until`; omitted fields are unchanged from the current channel detail. Typical changed fields are `apiVersion`, `frequency`, `sourceFor`, `description`, `additionalInfo`, and `generated`.
#### Sample request
{% embed url="" %}
BitMEX exchange details
{% endembed %}
## /api-key-info
`GET` `https://api.tardis.dev/v1/api-key-info`
Given `API_KEY` provided in request header provides information about what historical data (exchanges, date ranges, symbols) is available for given `API_KEY`.
#### Headers
| Name | Type | Description |
| ----------------------------------------------- | ------ | -------------------------------------------------------- |
| Authorization\* | string | Authorization header with value: `'Bearer YOUR_API_KEY'` |
{% tabs %}
{% tab title="200 " %}
```javascript
[
{
"exchange": "bitmex",
"accessType": "pro",
"from": "2019-03-30T00:00:00.000Z",
"to": "2050-12-02T00:00:00.000Z",
"symbols": [],
"dataPlan": "unlimited"
},
{
"exchange": "deribit",
"accessType": "one-off-purchase",
"from": "2019-03-30T00:00:00.000Z",
"to": "2050-12-02T00:00:00.000Z",
"symbols": [],
"dataPlan": "unlimited"
}
]
```
{% endtab %}
{% endtabs %}
# API Rate Limits
Account-level API request and data transfer limits
API request and data transfer limits apply per account, based on the active subscription.
Historical data transfer is included; we do not charge separately per GB or TB. Limits keep API access fair and reliable and may change as usage patterns and available capacity change.
## Request Limits
| Active subscription type | Requests/minute |
| ------------------------------ | --------------- |
| Solo / Academic / Professional | 3,000 |
| Business | 9,000 |
* Request limits count authenticated HTTP requests to the [raw data replay API](/api/http-api-reference#data-feeds-exchange).
* [Official clients](/api/quickstart) and [Tardis Machine](/tardis-machine/quickstart) call this API in parallel during historical replay, so several replay sessions running at the same time can hit request limits quickly.
## Data Transfer Limits
Data transfer limits count compressed data sent by [CSV dataset downloads](/downloadable-csv-files/api) and [raw data replay API](/api/http-api-reference#data-feeds-exchange) responses.
They depend on the active subscription type and billing interval:
| Billing interval | Solo / Academic / Professional | Business |
| ---------------- | ------------------------------ | -------- |
| Monthly | 20 TB | 60 TB |
| Quarterly | 60 TB | 180 TB |
| Yearly | 240 TB | 720 TB |
Quarterly and yearly limits are available from the start of the billing interval and reset on renewal. This helps with larger initial historical backfills.
## API Key Usage
* Solo, Academic and Professional subscriptions include one active API key.
* Business subscriptions include up to 10 active API keys for multiple team members, servers or locations.
Each key can be used from one source IP address at a time. All API keys on the account share the same request and transfer limits.
## Reduce Data Transfer
* Use `zstd` compression for [raw data replay](/api/http-api-reference#data-feeds-exchange). Latest official [Node.js](/node-client/replaying-historical-data) and [Python](/python-client/replaying-historical-data) clients request `zstd` by default. For direct HTTP calls, set [`compression=zstd`](/api/http-api-reference#data-feeds-exchange) in the query string.
* Keep the official client cache enabled when replaying the same historical data repeatedly.
* Use [`filters`](/api/http-api-reference#data-feeds-exchange) to request only the channels and symbols needed for the current replay.
## Reduce Replay Requests
Treat the API as an on-demand historical data source. Fetch what you need now, then fetch more later instead of mirroring the full archive upfront.
* Use the latest [official clients](/api/quickstart) or [Tardis Machine](/tardis-machine/quickstart) for filtered replay. They apply the recommended `sliceSize` automatically, so one raw data replay request can return up to 10 consecutive minutes and reduce API request count.
* For direct [raw data replay API](/api/http-api-reference#data-feeds-exchange) calls with filters, use the `x-suggested-slice-size` response header as the next `sliceSize` for the same exchange, filters and compression.
* For the same exchange and time range, request multiple channels in the same replay call by putting them in one `filters` array.
* If your account can access all symbols for a channel, request that channel once by omitting `symbols` or passing `symbols: []`.
* If you need selected symbols, put them in one filter for the same exchange, channel and time range instead of one request per symbol. One filter can include up to 50 symbols.
# Quickstart
Install, configure and get started with the tardis-dev npm package
Node.js `tardis-dev` library provides access to tick-level historical and real-time cryptocurrency market data both in [exchange-native and normalized formats](/faq/data#what-is-a-difference-between-exchange-native-and-normalized-data-format). Instead of callbacks, it uses [async iteration (for await ...of)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of), which works well for [switching between real-time streaming and historical replay](/node-client/normalization#seamless-switching-between-real-time-streaming-and-historical-market-data-replay) and [computing derived data locally](/node-client/normalization#computing-derived-data-locally).
## Features
* [historical](/historical-data-details/overview) tick-level [market data replay](/node-client/replaying-historical-data) backed by Tardis.dev [HTTP API](/api/http-api-reference#data-feeds-exchange) — includes full order book depth snapshots plus incremental updates, trades, historical open interest, funding, index, mark prices, liquidations and more
* consolidated [real-time data streaming API](/node-client/streaming-real-time-data) connecting directly to exchanges' public WebSocket APIs
* support for both [exchange-native](/faq/data#what-is-a-difference-between-exchange-native-and-normalized-data-format) and [normalized market data](/node-client/normalization) formats (unified format for accessing market data across all supported exchanges — normalized trades, order book and ticker data)
* [seamless switching between real-time streaming and historical market data replay](/node-client/normalization#seamless-switching-between-real-time-streaming-and-historical-market-data-replay) thanks to [`async iterables`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of) providing unified way of consuming data messages
* transparent historical local data caching (cached data is stored on disk in compressed format and decompressed on demand when reading the data)
* support for top cryptocurrency exchanges: [BitMEX](/historical-data-details/bitmex), [Deribit](/historical-data-details/deribit), [Binance Spot](/historical-data-details/binance), [Binance USDS-M Futures](/historical-data-details/binance-futures), [OKX Spot](/historical-data-details/okex), [HTX Spot](/historical-data-details/huobi), [bitFlyer](/historical-data-details/bitflyer), [Bitstamp](/historical-data-details/bitstamp), [Coinbase Exchange](/historical-data-details/coinbase), [Kraken Futures (Crypto Facilities)](/historical-data-details/cryptofacilities), [Gemini](/historical-data-details/gemini), [Kraken](/historical-data-details/kraken), [Bitfinex](/historical-data-details/bitfinex), [Bybit Derivatives](/historical-data-details/bybit) and more
* automatic closed connections and stale connections reconnection logic for real-time streams
* [combining multiple exchanges feeds into single one](/node-client/normalization#combining-data-streams) via [`combine`](/node-client/normalization#combining-data-streams) helper function — synchronized historical market data replay and consolidated real-time data streaming from multiple exchanges
* [computing derived data locally](/node-client/normalization#computing-derived-data-locally) like order book imbalance, customizable trade bars, book snapshots and more via [`compute`](/node-client/normalization#computing-derived-data-locally) helper function and `computables`, e.g., volume based bars, top 20 levels order book snapshots taken every 10 ms etc
* [full limit order book reconstruction](/node-client/normalization#limit-order-book-reconstruction) both for real-time and historical data via `OrderBook` object
* fast and lightweight architecture — low memory footprint and no heavy in-memory buffering
* [extensible mapping logic](/node-client/normalization#modifying-built-in-and-adding-custom-normalizers) that allows adjusting normalized formats for specific needs
* built-in TypeScript support
* [Open Source](https://github.com/tardis-dev/tardis-node)
{% embed url="" %}
Tardis-dev GitHub repository
{% endembed %}
## Installation
Requires Node.js v24.19+ installed.
```bash
npm install tardis-dev --save
```
{% hint style="info" %}
Node.js examples on this page use ES modules and top-level await. Save snippets as `.mjs` or set `"type": "module"` in your `package.json`.
{% endhint %}
## Historical Replay
{% tabs %}
{% tab title="Exchange-native" %}
```javascript
import { replay } from 'tardis-dev'
const messages = replay({
exchange: 'binance',
filters: [
{ channel: 'trade', symbols: ['btcusdt'] },
{ channel: 'depth', symbols: ['btcusdt'] }
],
from: '2024-03-01',
to: '2024-03-02'
})
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message)
}
```
{% endtab %}
{% tab title="Normalized" %}
```javascript
import { replayNormalized, normalizeTrades, normalizeBookChanges } from 'tardis-dev'
const messages = replayNormalized(
{
exchange: 'binance',
symbols: ['btcusdt'],
from: '2024-03-01',
to: '2024-03-02'
},
normalizeTrades,
normalizeBookChanges
)
for await (const message of messages) {
console.log(message)
}
```
{% endtab %}
{% endtabs %}
{% content-ref url="/pages/gkHZyu4v8WrMNBBiqduR" %}
[Replaying Historical Data](/node-client/replaying-historical-data)
{% endcontent-ref %}
## Real-Time Streaming
{% tabs %}
{% tab title="Exchange-native" %}
```javascript
import { stream } from 'tardis-dev'
const messages = stream({
exchange: 'binance',
filters: [
{ channel: 'trade', symbols: ['btcusdt'] },
{ channel: 'depth', symbols: ['btcusdt'] }
]
})
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message)
}
```
{% endtab %}
{% tab title="Normalized" %}
```javascript
import { streamNormalized, normalizeTrades, normalizeBookChanges } from 'tardis-dev'
const messages = streamNormalized(
{
exchange: 'binance',
symbols: ['btcusdt']
},
normalizeTrades,
normalizeBookChanges
)
for await (const message of messages) {
console.log(message)
}
```
{% endtab %}
{% endtabs %}
{% content-ref url="/pages/NugzOsZ9SfKsMBMmecqk" %}
[Streaming Real-Time Data](/node-client/streaming-real-time-data)
{% endcontent-ref %}
## Debugging and logging
`tardis-dev` lib uses [debug](https://github.com/visionmedia/debug) package for verbose logging and debugging purposes that can be enabled via `DEBUG` environment variable set to `tardis-dev*`.
## ES Modules and TypeScript
Examples in this page use standard ES module imports and top-level await:
```typescript
import { replay, stream } from 'tardis-dev'
const messages = replay({ exchange: 'binance', from: '2024-03-01', to: '2024-03-02' })
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message)
}
```
This works in modern Node.js and gives you first class TypeScript typings.
## Historical market data helpers
### `init(options)`
{% hint style="info" %}
This function doesn't affect real-time streaming functionality in any way, it's useful only for historical data replay.
{% endhint %}
When working with market data via [`replay`](/node-client/replaying-historical-data#replay-options) and [`replayNormalized`](https://docs.tardis.dev/node-client/pages/gkHZyu4v8WrMNBBiqduR#replaynormalized-options-...normalizers), by default only the first day of each month of historical data is available for replay, and locally cached historical data is stored in the default location on disk (OS temp dir).
Use `init` to set an `apiKey`, custom `cacheDir`, and preferred compression for historical replay requests. `apiKey` can also be provided directly via [`replay`](/node-client/replaying-historical-data#replay-options) and [`replayNormalized`](https://docs.tardis.dev/node-client/pages/gkHZyu4v8WrMNBBiqduR#replaynormalized-options-...normalizers) options; that overrides anything set via `init`.
```javascript
import { init } from 'tardis-dev'
init({
apiKey: 'YOUR API KEY',
cacheDir: 'CUSTOM CACHE DIR PATH',
dataFeedCompression: 'gzip'
})
```
#### init options
| name | type | default | description |
| ----------------------- | ----------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **apiKey** | string (optional) | undefined | API key for Tardis.dev[ HTTP API](/api/http-api-reference#data-feeds-exchange) - if not provided only first day of each month of historical data is accessible |
| **cacheDir** | string | \/.tardis-cache | path to local dir that will be used as cache location - if not provided default `temp` dir for given OS will be used |
| **dataFeedCompression** | `'zstd' \| 'gzip'` (optional) | `'zstd'` | preferred compression for historical replay requests; set to `'gzip'` when you need the client to request gzip-compressed slices |
### `getExchangeDetails(exchange)`
Given exchange id provides exchange details (available symbols, availability dates, available channels, pricing info etc) provided by [exchanges/:exchange](/api/http-api-reference#exchanges-exchange) API endpoint.
```javascript
import { getExchangeDetails } from 'tardis-dev'
const binanceExchangeDetails = await getExchangeDetails('binance')
console.log(binanceExchangeDetails.id)
```
#### type of response returned by awaiting on `getExchangeDetails`
```typescript
{
id: string
name: string
enabled: boolean
delisted?: boolean
availableSince: string
availableTo?: string
availableChannels: string[]
availableSymbols: {
id: string
type: 'spot' | 'future' | 'perpetual' | 'option' | 'combo' | 'prediction'
availableSince: string
availableTo?: string
name?: string
}[]
incidentReports: {
from: string
to: string
status: 'resolved' | 'wontfix' | 'unresolved'
details: string
}[]
channelDetails: {
name: string
description: string
frequency: string
frequencySource: string
exchangeDocsUrl?: string
sourceFor?: string[]
availableSince: string
availableTo?: string
apiVersion?: string
additionalInfo?: string
generated?: true
changes?: {
until: string
frequency?: string
sourceFor?: string[]
apiVersion?: string
description?: string
additionalInfo?: string
generated?: true
}[]
}[]
apiDocsUrl?: string
dataCollectionDetails?: {
recorderDataCenter: {
host: string
regionId: string
location: string
}
recorderDataCenterChanges?: {
until: string
dataCenter: { host: string; regionId: string; location: string }
}[]
wssConnection?: {
url: string
apiVersion?: string
proxiedViaCloudflare?: boolean
}
wssConnectionChanges?: {
until: string
url?: string
apiVersion?: string
proxiedViaCloudflare?: boolean
}[]
exchangeDataCenter?: {
host: string
regionId: string
location: string
}
exchangeDataCenterChanges?: {
until: string
dataCenter: { host: string; regionId: string; location: string }
}[]
}
datasets: {
formats: ['csv']
exportedFrom: string
exportedUntil: string
stats: {
trades: number
bookChanges: number
}
symbols: {
id: string
type: 'spot' | 'future' | 'perpetual' | 'option' | 'combo' | 'prediction'
availableSince: string
availableTo?: string
dataTypes: DatasetType[]
}[]
}
}
// where DatasetType is one of:
type DatasetType =
| 'trades'
| 'incremental_book_L2'
| 'quotes'
| 'derivative_ticker'
| 'options_chain'
| 'book_snapshot_25'
| 'book_snapshot_5'
| 'liquidations'
| 'book_ticker'
```
### `getApiKeyAccessInfo(apiKey?)`
Given `apiKey` provided as optional parameter or provided in [`init`](#init-options) function provides information about the account's historical data access: exchanges, access type, data plan, date ranges, and symbol restrictions.
```javascript
import { getApiKeyAccessInfo } from 'tardis-dev'
const details = await getApiKeyAccessInfo('YOUR_API_KEY')
console.log(details)
```
#### type of response returned by awaiting on `getApiKeyAccessInfo()`
```typescript
{
exchange: string
accessType: string
from: string
to: string
symbols: string[]
dataPlan: string
}[]
```
### `clearCache()`
Clears local data cache dir.
```javascript
import { clearCache } from 'tardis-dev'
await clearCache()
```
### `downloadDatasets(options)`
Downloads CSV datasets for specified exchange, data types, symbols and date range. Handles day-by-day downloads, retries and skipping already-downloaded files automatically.
```javascript
import { downloadDatasets } from 'tardis-dev'
await downloadDatasets({
exchange: 'binance',
dataTypes: ['trades', 'incremental_book_L2'],
from: '2024-03-01',
to: '2024-03-02',
symbols: ['BTCUSDT'],
apiKey: 'YOUR_API_KEY'
})
```
{% content-ref url="/pages/qqtWvA83hsjBsfDmZ6Jg#download-via-client-libraries" %}
[API Reference](/downloadable-csv-files/api#download-via-client-libraries)
{% endcontent-ref %}
### `getInstrumentInfo(exchange, symbol)`
Returns instrument metadata (tick sizes, contract multipliers, base/quote currencies) for a given exchange and symbol.
```javascript
import { getInstrumentInfo, init } from 'tardis-dev'
init({ apiKey: 'YOUR_API_KEY' }) // set API key globally for instrument info requests
const info = await getInstrumentInfo('binance', 'btcusdt')
console.log(info)
```
You can also pass an instrument metadata filter, or an array of exchanges, when you need full metadata records.
### `findInstrumentSymbols(exchanges, filter, selector?)`
Use this helper when you know the market you want but not each exchange's symbol format. It queries the [Instruments Metadata API](/api/instruments-metadata-api) with normalized criteria and returns the correct exchange-specific `id` for each requested exchange, ready to pass to replay, streaming, or raw data feeds.
```javascript
import { findInstrumentSymbols, init } from 'tardis-dev'
init({ apiKey: 'YOUR_API_KEY' })
const symbolsByExchange = await findInstrumentSymbols(['bitmex', 'binance-futures', 'okex-swap', 'bybit'], {
baseCurrency: 'BTC',
quoteCurrency: 'USDT',
contractType: 'linear_perpetual',
active: true
})
console.log(symbolsByExchange)
// [
// { exchange: 'bitmex', symbols: ['XBTUSDT'] },
// { exchange: 'binance-futures', symbols: ['btcusdt'] },
// { exchange: 'okex-swap', symbols: ['BTC-USDT-SWAP'] },
// { exchange: 'bybit', symbols: ['BTCUSDT'] }
// ]
```
The optional `selector` defaults to `id`. Pass `datasetId` only when you need symbols for direct CSV dataset file downloads:
```javascript
const csvSymbolsByExchange = await findInstrumentSymbols(
['bitmex', 'binance-futures', 'okex-swap', 'bybit'],
{
baseCurrency: 'BTC',
quoteCurrency: 'USDT',
contractType: 'linear_perpetual',
active: true
},
'datasetId'
)
```
Returned `id` symbols are exchange-provided IDs and are not normalized by the client. Returned `datasetId` symbols are CSV dataset IDs for instruments whose symbols appear in exported dataset metadata; `downloadDatasets()` URL-encodes them when constructing dataset URLs.
# Replaying Historical Data
Replaying historical market data in exchange-native and normalized formats
{% hint style="info" %}
See [historical data details](/historical-data-details/overview) page to get detailed information about historical market data available for each exchange.
{% endhint %}
## `replay(options)`
Replays historical market data messages for given replay options in [exchange-native format](/faq/data#what-is-a-difference-between-exchange-native-and-normalized-data-format). Historical market data is fetched efficiently (in parallel) from the [Tardis.dev HTTP API](/api/http-api-reference#data-feeds-exchange) and cached locally. Returns [`async iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of).
Replay requests use `zstd` compression by default. To force `gzip`, set `init({ dataFeedCompression: 'gzip' })` before calling `replay()` or `replayNormalized()`.
{% hint style="info" %}
For filtered historical replay, the client automatically uses the [recommended `sliceSize`](/api/http-api-reference#data-feeds-exchange) to reduce `/data-feeds` request count.
{% endhint %}
```javascript
import { replay } from 'tardis-dev'
const messages = replay({
exchange: 'binance',
filters: [
{ channel: 'trade', symbols: ['btcusdt'] },
{ channel: 'depth', symbols: ['btcusdt'] }
],
from: '2024-03-01',
to: '2024-03-02'
})
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message)
}
```
{% hint style="info" %}
[stream(options)](/node-client/streaming-real-time-data#stream-options) is the real-time counterpart of `replay` function, returning real-time market data in the same format.
{% endhint %}
When `symbols` array is empty or omitted in filters, data for all active symbols for that channel is returned. Use that form when you need the whole channel instead of starting one replay per symbol. If you need selected symbols, pass them together in one `symbols` array for the channel.
#### replay options
| name | type | default | description |
| ------------------------------- | ---------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **exchange** | string | - | requested exchange id - one of [allowed values](https://github.com/tardis-dev/tardis-node/blob/master/src/consts.ts#L1) |
| **filters** | {channel:string, symbols?: string\[]}\[] | \[] | optional filters of requested historical data feed - use [`getExchangeDetails`](/node-client/quickstart#historical-market-data-helpers) function from [Getting Started](/node-client/quickstart#historical-market-data-helpers) to get allowed channels and symbols ids for requested exchange |
| **from** | string | - | replay period start date (UTC) in a format recognized by the [Date.parse()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse), e.g., `2019-04-01` |
| **to** | string | - | replay period end date (UTC) in a format recognized by the [Date.parse()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse), e.g., `2019-04-02` |
| **skipDecoding** | boolean (optional) | undefined | when set to `true` returns messages as buffers instead of decoding them to objects |
| **withDisconnects** | boolean (optional) | undefined | when set to `true` returns message with value `undefined` for events when connection that was recording the historical data got disconnected |
| **apiKey** | string (optional) | undefined | API key for Tardis.dev[ HTTP API](/api/http-api-reference#data-feeds-exchange) - if not provided only first day of each month of historical data is accessible. It can also be set via [`init`](/node-client/quickstart#historical-market-data-helpers) function from [Getting Started](/node-client/quickstart#historical-market-data-helpers) for all replay calls. |
| **autoCleanup** | boolean (optional) | undefined | when set to `true`, automatically removes cached data from disk after it has been processed — useful for large backfills where disk space is a concern. Not safe for concurrent replay — see warning below. |
| **waitWhenDataNotYetAvailable** | boolean or number (optional) | undefined | when set to `true`, waits for data that is not yet available using a 30-minute offset. When set to a number, specifies the offset in minutes (minimum effective value is 6 minutes) |
| **withMicroseconds** | boolean (optional) | undefined | when set to `true`, `localTimestamp` is returned with microsecond precision instead of millisecond |
{% hint style="warning" %}
The client can fetch replay data with up to 60 concurrent `/data-feeds` HTTP requests per replay job. Long date ranges, many channel/symbol filters and multiple concurrent replay processes can quickly exceed [API rate limits](/api/rate-limits), causing request failures.
{% endhint %}
{% hint style="warning" %}
**`autoCleanup` concurrency**: avoid using `autoCleanup` with concurrent replay — the cache path is keyed by exchange, a hash of the filters, and the calendar day, so any concurrent jobs sharing those three components will conflict (even with non-overlapping time windows within the same day) and cause file-not-found errors. Clean the cache manually after all jobs complete instead.
{% endhint %}
#### type of messages provided by `replay` iterator ([`for await ...of`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of))
```typescript
type Message =
| {
localTimestamp: Date // local timestamp when message has been received
message: any // message in exchange-native data format
}
// when skipDecoding is set to true
| {
localTimestamp: Buffer
message: Buffer
}
// when withDisconnects is set to true whole message can be undefined (disconnect)
Message | undefined
```
#### sample message
```javascript
{
localTimestamp: 2024-03-01T00:00:00.001Z,
message: {
stream: 'btcusdt@trade',
data: {
e: 'trade',
E: 1709251199998,
s: 'BTCUSDT',
t: 3445374963,
p: '61130.98000000',
q: '0.00145000',
b: 25230662315,
a: 25230662808,
T: 1709251199998,
m: true,
M: true
}
}
}
```
## `replayNormalized(options, ...normalizers)`
Replays historical market data messages for given replay options and **normalizes messages** using normalizers provided as [rest arguments](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/rest_parameters). Historical market data is fetched efficiently (in parallel) from the [Tardis.dev HTTP API](/api/http-api-reference#data-feeds-exchange) and cached locally. Returns [`async iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of).
```javascript
import { replayNormalized, normalizeTrades, normalizeBookChanges } from 'tardis-dev'
const messages = replayNormalized(
{
exchange: 'binance',
symbols: ['btcusdt'],
from: '2024-03-01',
to: '2024-03-02'
},
normalizeTrades,
normalizeBookChanges
)
for await (const message of messages) {
console.log(message)
}
```
{% hint style="info" %}
[streamNormalized(options, ...normalizers)](https://docs.tardis.dev/node-client/pages/NugzOsZ9SfKsMBMmecqk#streamnormalized-options-...normalizers) is the real-time counterpart of `replayNormalized` function, returning real-time market data in the same format.
{% endhint %}
#### replay normalized options
| name | type | default | description |
| ------------------------------- | ---------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **exchange** | string | - | requested exchange id - one of [allowed values](https://github.com/tardis-dev/tardis-node/blob/master/src/consts.ts#L1) |
| **symbols** | string\[] (optional) | undefined | optional symbols for requested data feed - use [`getExchangeDetails`](/node-client/quickstart#historical-market-data-helpers) function from [Getting Started](/node-client/quickstart#historical-market-data-helpers) to get allowed symbols ids for requested exchange |
| **from** | string | - | replay period start date (UTC) in a format recognized by the [Date.parse()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse), e.g., `2019-04-01` |
| **to** | string | - | replay period end date (UTC) in a format recognized by the [Date.parse()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse) e.g., `2019-04-02` |
| **withDisconnectMessages** | boolean (optional) | undefined | when set to `true` returns [`disconnect`](/node-client/normalization#disconnect-message) messages for events when connection that was recording the historical data got disconnected |
| **apiKey** | string (optional) | undefined | API key for Tardis.dev[ HTTP API](/api/http-api-reference#data-feeds-exchange) - if not provided only first day of each month of historical data is accessible. It can also be set via [`init`](/node-client/quickstart#historical-market-data-helpers) function from [Getting Started](/node-client/quickstart#historical-market-data-helpers) for all `replayNormalized` calls. |
| **autoCleanup** | boolean (optional) | undefined | when set to `true`, automatically removes cached data from disk after it has been processed — useful for large backfills where disk space is a concern. Not safe for concurrent replay — see [replay options](#replay-options) warning. |
| **waitWhenDataNotYetAvailable** | boolean or number (optional) | undefined | when set to `true`, waits for data that is not yet available using a 30-minute offset. When set to a number, specifies the offset in minutes (minimum effective value is 6 minutes) |
#### Built-in normalizers
`replayNormalized` function accepts any number of [normalizers](/node-client/normalization) [as rest parameters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/rest_parameters) that map from [exchange-native format](/faq/data#what-is-a-difference-between-exchange-native-and-normalized-data-format) to normalized data format. `tardis-dev` ships with [built in ones that normalize trades, order book and derivative ticker data](/node-client/normalization) but also allows [adding custom](/node-client/normalization#modifying-built-in-and-adding-custom-normalizers) ones.
#### types of messages provided by `replayNormalized` iterator ([`for await ...of`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of))
Message types and formats depend on specific normalizers provided to `replayNormalized` function and are documented in detail in [Normalization](/node-client/normalization).
#### sample message
Sample message produced by [`normalizeTrades`](/node-client/normalization#normalizetrades)
```javascript
{
type: 'trade',
symbol: 'BTCUSDT',
exchange: 'binance',
id: '3445374963',
price: 61130.98,
amount: 0.00145,
side: 'sell',
timestamp: 2024-02-29T23:59:59.998Z,
localTimestamp: 2024-03-01T00:00:00.001Z
}
```
# Streaming Real-Time Data
Streaming real-time market data from exchanges' WebSocket feeds
Real-time market data streaming connecting directly to exchanges' WebSocket APIs with automatic reconnection.
## `stream(options)`
Streams real-time market data messages for given stream options in [exchange-native format](/faq/data#what-is-a-difference-between-exchange-native-and-normalized-data-format). It connects directly to exchanges WebSocket APIs and transparently restarts closed, broken or stale connections (open connections without data being sent for specified amount of time). Returns [`async iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of).
```javascript
import { stream } from 'tardis-dev'
const messages = stream({
exchange: 'binance',
filters: [
{ channel: 'trade', symbols: ['btcusdt'] },
{ channel: 'depth', symbols: ['btcusdt'] }
]
})
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message)
}
```
{% hint style="info" %}
[replay(options)](/node-client/replaying-historical-data#replay-options) is the historical market data counterpart of `stream` function, returning historical market data in the same format.
{% endhint %}
#### stream options
| name | type | default | description |
| --------------------- | ---------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **exchange** | string | - | requested exchange id - one of [allowed values](https://github.com/tardis-dev/tardis-node/blob/master/src/consts.ts#L1) |
| **filters** | {channel:string, symbols?: string\[]}\[] | \[] | optional filters of requested real-time data feed - use [`getExchangeDetails`](/node-client/quickstart#historical-market-data-helpers) from [Getting Started](/node-client/quickstart#historical-market-data-helpers) to get allowed channels and symbols ids for requested exchange |
| **withDisconnects** | boolean (optional) | undefined | when set to `true` returns message with value `undefined` for real-time stream disconnect events |
| **timeoutIntervalMS** | number | 10000 | specifies time in milliseconds after which connection is restarted if no message has been received from the exchange |
| **onError** | function (optional) | undefined | Optional callback `(err) => void` invoked when real-time WebSocket connection error occurs, useful for custom error logging etc. |
#### type of messages provided by `stream` iterator ([`for await ...of`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of))
```typescript
type Message = {
localTimestamp: Date // local timestamp when message has been received
message: any // message in exchange-native data format
}
// when withDisconnects is set to true whole message can be undefined
Message | undefined
```
#### sample message
```javascript
{
localTimestamp: 2024-03-01T00:00:00.001Z,
message: {
stream: 'btcusdt@trade',
data: {
e: 'trade',
E: 1709251199998,
s: 'BTCUSDT',
t: 3445374963,
p: '61130.98000000',
q: '0.00145000',
b: 25230662315,
a: 25230662808,
T: 1709251199998,
m: true,
M: true
}
}
}
```
## `streamNormalized(options, ...normalizers)`
Streams real-time market data messages for given stream options and **normalizes messages** using provided normalizers provided as [rest arguments](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/rest_parameters). It connects directly to exchanges WebSocket APIs and transparently restarts closed, broken or stale connections (open connections without data being sent for specified amount of time). Returns [`async iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of).
```javascript
import { streamNormalized, normalizeTrades, normalizeBookChanges } from 'tardis-dev'
const messages = streamNormalized(
{
exchange: 'binance',
symbols: ['btcusdt']
},
normalizeTrades,
normalizeBookChanges
)
for await (const message of messages) {
console.log(message)
}
```
{% hint style="info" %}
[replayNormalized(options, ...normalizers)](https://docs.tardis.dev/node-client/pages/gkHZyu4v8WrMNBBiqduR#replaynormalized-options-...normalizers) is the historical counterpart of `streamNormalized` function, returning historical market data in the same format.
{% endhint %}
#### stream normalized options
| name | type | default | description |
| -------------------------- | -------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **exchange** | string | - | requested exchange id - one of [allowed values](https://github.com/tardis-dev/tardis-node/blob/master/src/consts.ts#L1) |
| **symbols** | string\[] (optional) | undefined | instruments symbols for requested data feed |
| **withDisconnectMessages** | boolean (optional) | undefined | when set to `true` returns [`disconnect`](/node-client/normalization#disconnect-message) messages for real-time stream disconnect events |
| **timeoutIntervalMS** | number | 10000 | specifies time in milliseconds after which connection is restarted if no message has been received from the exchange |
| **onError** | function (optional) | undefined | Optional callback `(err) => void` invoked when real-time WebSocket connection or mapping error occurs, useful for custom error logging etc. |
{% hint style="info" %}
For sparse instruments (e.g., illiquid options or niche currency pairs), increase `timeoutIntervalMS` (e.g., `60000`) to prevent unnecessary connection restarts when no messages arrive for extended periods. This is especially important for computed data types like `trade_bar` on low-volume symbols.
{% endhint %}
#### Built-in normalizers
`streamNormalized` function can accept any number of custom normalizers as [rest parameters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/rest_parameters) that map from [exchange-native format](/faq/data#what-is-a-difference-between-exchange-native-and-normalized-data-format) to normalized data format. `tardis-dev` ships with [built in ones that normalize trades, order book and derivative ticker data](/node-client/normalization) but also allows [adding custom ones](/node-client/normalization#modifying-built-in-and-adding-custom-normalizers).
#### types of messages provided by `streamNormalized` iterator ([`for await ...of`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of))
Message types and formats depend on specific normalizers provided to `streamNormalized` function and are documented in detail in [Normalization](/node-client/normalization).
#### sample message
Sample message produced by [`normalizeTrades`](/node-client/normalization#normalizetrades)
```javascript
{
type: 'trade',
symbol: 'BTCUSDT',
exchange: 'binance',
id: '3445374963',
price: 61130.98,
amount: 0.00145,
side: 'sell',
timestamp: 2024-02-29T23:59:59.998Z,
localTimestamp: 2024-03-01T00:00:00.001Z
}
```
# Normalization
Normalizers, order book reconstruction, combine and compute
Data normalization allows consuming market data feeds from various exchanges in consistent format.
`tardis-dev` has following built-in normalizers that can be provided to [`replayNormalized`](https://docs.tardis.dev/node-client/pages/gkHZyu4v8WrMNBBiqduR#replaynormalized-options-...normalizers) or [`streamNormalized`](https://docs.tardis.dev/node-client/pages/NugzOsZ9SfKsMBMmecqk#streamnormalized-options-...normalizers) functions:
* [`normalizeTrades`](#normalizetrades) - provides normalized `trade` data
* [`normalizeBookChanges`](#normalizebookchanges) - provides normalized [`book_change`](#normalizebookchanges) data
* [`normalizeDerivativeTickers`](#normalizederivativetickers) - provides normalized funding, index and mark price data
* [`normalizeBookTickers`](#normalizebooktickers) - provides normalized [`book_ticker`](#normalizebooktickers) (best bid/ask) data from exchange-native BBO feeds
* [`normalizeLiquidations`](#normalizeliquidations) - provides normalized `liquidation` data
* [`normalizeOptionsSummary`](#normalizeoptionssummary) - provides normalized `option_summary` data (greeks, IV, bid/ask for options)
If you're interested in how exactly data is mapped from [exchange-native format](/faq/data#what-is-a-difference-between-exchange-native-and-normalized-data-format) to normalized one, please follow code in [`tardis-dev` GitHub repository](https://github.com/tardis-dev/tardis-node/tree/master/src/mappers) for each exchange and if you determined that mapping should be done differently please read "[modifying built-in and adding custom normalizers](#modifying-built-in-and-adding-custom-normalizers)" section.
```javascript
import { streamNormalized, normalizeTrades, normalizeBookChanges, normalizeDerivativeTickers } from 'tardis-dev'
// or replayNormalized to replay normalized historical data
const messages = streamNormalized(
{
exchange: 'binance-futures',
symbols: ['BTCUSDT']
},
normalizeTrades,
normalizeBookChanges,
normalizeDerivativeTickers
)
for await (const message of messages) {
if (message.type === 'book_change') {
// process normalized book change
}
if (message.type === 'trade') {
// process normalized trade
}
if (message.type === 'derivative_ticker') {
// process normalized derivative_ticker
}
}
```
### `normalizeTrades`
When passed as an arg to [`replayNormalized`](https://docs.tardis.dev/node-client/pages/gkHZyu4v8WrMNBBiqduR#replaynormalized-options-...normalizers) or [`streamNormalized`](https://docs.tardis.dev/node-client/pages/NugzOsZ9SfKsMBMmecqk#streamnormalized-options-...normalizers), it provides normalized `trade` data for all supported exchanges.
{% tabs %}
{% tab title="sample message" %}
```javascript
{
type: 'trade',
symbol: 'BTCUSDT',
exchange: 'binance',
id: '3445374963',
price: 61130.98,
amount: 0.00145,
side: 'sell',
timestamp: 2024-02-29T23:59:59.998Z,
localTimestamp: 2024-03-01T00:00:00.001Z
}
```
{% endtab %}
{% tab title="type definition" %}
```typescript
{
type: 'trade'
symbol: string // instrument symbol as provided by exchange
exchange: string // exchange id
id: string | undefined // trade id if provided by exchange
price: number // trade price as provided by exchange
amount: number // trade amount as provided by exchange
side: 'buy' | 'sell' | 'unknown' // liquidity taker side (aggressor)
timestamp: Date // trade timestamp provided by exchange
localTimestamp: Date // message arrival timestamp
}
```
{% endtab %}
{% endtabs %}
### `normalizeBookChanges`
When passed as an arg to [`replayNormalized`](https://docs.tardis.dev/node-client/pages/gkHZyu4v8WrMNBBiqduR#replaynormalized-options-...normalizers) or [`streamNormalized`](https://docs.tardis.dev/node-client/pages/NugzOsZ9SfKsMBMmecqk#streamnormalized-options-...normalizers), it provides normalized `book_change` data for all supported exchanges.
Provides initial [L2 (market by price)](/faq/order-books#what-l2-order-book-data-can-be-used-for) order book snapshots (`isSnapshot=true`) plus incremental updates for each order book change. Please note that `amount` is the updated amount at that price level, not a delta. An `amount` of `0` indicates the price level can be removed.
{% tabs %}
{% tab title="sample message" %}
```javascript
{
type: 'book_change',
symbol: 'BTCUSDT',
exchange: 'binance',
isSnapshot: false,
bids: [{ price: 61141.09, amount: 2.02515 }],
asks: [{ price: 61141.1, amount: 4.09368 }],
timestamp: 2024-03-01T00:00:01.489Z,
localTimestamp: 2024-03-01T00:00:01.491Z
}
```
{% endtab %}
{% tab title="type definition" %}
```typescript
{
type: 'book_change'
symbol: string // instrument symbol as provided by exchange
exchange: string // exchange id
isSnapshot: boolean // if true marks initial order book snapshot
bids: { price: number; amount: number }[] // updated bids price-amount levels
asks: { price: number; amount: number }[] // updated asks price-amount levels
timestamp: Date // order book update timestamp if provided by exchange,
// otherwise equals to localTimestamp
localTimestamp: Date // message arrival timestamp
}
```
{% endtab %}
{% endtabs %}
When processing `book_change` updates: an `amount` of `0` means remove that price level. If you receive a removal for a price level not in your local book, ignore it. Snapshot levels may include zero-amount entries — these should also be treated as absent levels.
### `normalizeBookTickers`
When passed as an arg to [`replayNormalized`](https://docs.tardis.dev/node-client/pages/gkHZyu4v8WrMNBBiqduR#replaynormalized-options-...normalizers) or [`streamNormalized`](https://docs.tardis.dev/node-client/pages/NugzOsZ9SfKsMBMmecqk#streamnormalized-options-...normalizers), it provides normalized `book_ticker` data — top of the book (best bid/ask) data from exchanges' native best bid/offer channels (e.g., Binance `bookTicker`, Bybit `orderbook.1`). Unlike `quote`, which is derived from L2 order book data via [`computeBookSnapshots`](#computebooksnapshots-options), `book_ticker` is sourced from the native exchange-provided WebSocket best bid/offer feed.
Because it is a standalone feed, `book_ticker` replay can start from any point in time, whereas `quote` requires starting from 00:00 UTC (when the initial L2 order book snapshot is provided).
{% tabs %}
{% tab title="sample message" %}
```javascript
{
type: 'book_ticker',
symbol: 'BTCUSDT',
exchange: 'binance-futures',
askPrice: 63125.5,
askAmount: 2.5,
bidPrice: 63125.4,
bidAmount: 1.8,
timestamp: 2024-01-15T10:30:00.123Z,
localTimestamp: 2024-01-15T10:30:00.234Z
}
```
{% endtab %}
{% tab title="type definition" %}
```typescript
{
type: 'book_ticker'
symbol: string // instrument symbol as provided by exchange
exchange: string // exchange id
askPrice: number | undefined // best ask price, undefined if there aren't any asks
askAmount: number | undefined // best ask amount, undefined if there aren't any asks
bidPrice: number | undefined // best bid price, undefined if there aren't any bids
bidAmount: number | undefined // best bid amount, undefined if there aren't any bids
timestamp: Date // message timestamp provided by exchange
localTimestamp: Date // message arrival timestamp
}
```
{% endtab %}
{% endtabs %}
### `normalizeDerivativeTickers`
When passed as an arg to [`replayNormalized`](https://docs.tardis.dev/node-client/pages/gkHZyu4v8WrMNBBiqduR#replaynormalized-options-...normalizers) or [`streamNormalized`](https://docs.tardis.dev/node-client/pages/NugzOsZ9SfKsMBMmecqk#streamnormalized-options-...normalizers), it provides normalized `derivative_ticker` data for supported exchanges that trade derivative instruments.
Funding fields describe upcoming funding events relative to the message timestamp. `fundingTimestamp` is the next funding event time: the immediately upcoming event, not a previously settled funding time. `fundingRate` is the rate for that next event and can change until the event occurs. `predictedFundingRate`, when present, estimates the following funding event.
{% tabs %}
{% tab title="sample message" %}
```javascript
{
type: 'derivative_ticker',
symbol: 'BTCUSDT',
exchange: 'binance-futures',
lastPrice: 61131.0,
openInterest: 1458236000,
fundingRate: 0.0001,
fundingTimestamp: 2024-03-01T08:00:00.000Z,
predictedFundingRate: 0.00009,
indexPrice: 61130.9,
markPrice: 61131.1,
timestamp: 2024-03-01T00:00:00.250Z,
localTimestamp: 2024-03-01T00:00:00.251Z
}
```
{% endtab %}
{% tab title="type definition" %}
```typescript
{
type: 'derivative_ticker'
symbol: string // instrument symbol as provided by exchange
exchange: string // exchange id
lastPrice: number | undefined // last instrument price if provided by exchange
openInterest: number | undefined // last open interest if provided by exchange
fundingRate: number | undefined // funding rate for the next funding event if provided by exchange
indexPrice: number | undefined // last index price if provided by exchange
markPrice: number | undefined // last mark price if provided by exchange
fundingTimestamp: Date | undefined // next funding event timestamp if provided by exchange
predictedFundingRate: number | undefined // estimated funding rate for the following funding event if provided by exchange
timestamp: Date // message timestamp provided by exchange
localTimestamp: Date // message arrival timestamp
}
```
{% endtab %}
{% endtabs %}
### `normalizeLiquidations`
When passed as an arg to [`replayNormalized`](https://docs.tardis.dev/node-client/pages/gkHZyu4v8WrMNBBiqduR#replaynormalized-options-...normalizers) or [`streamNormalized`](https://docs.tardis.dev/node-client/pages/NugzOsZ9SfKsMBMmecqk#streamnormalized-options-...normalizers), it provides normalized `liquidation` data for exchanges that publish liquidation events. See [which exchanges support liquidations](/faq/data#which-exchanges-support-liquidations-data-type).
{% tabs %}
{% tab title="sample message" %}
```javascript
{
type: 'liquidation',
symbol: 'BTCUSDT',
exchange: 'binance-futures',
id: '2045830192',
price: 61110.5,
amount: 0.25,
side: 'sell',
timestamp: 2024-03-01T00:05:12.123Z,
localTimestamp: 2024-03-01T00:05:12.124Z
}
```
{% endtab %}
{% tab title="type definition" %}
```typescript
{
type: 'liquidation'
symbol: string // instrument symbol as provided by exchange
exchange: string // exchange id
id: string | undefined // liquidation id if provided by exchange
price: number // liquidation price
amount: number // liquidation amount
side: 'buy' | 'sell' | 'unknown' // liquidation side: buy means short liquidation, sell means long liquidation
timestamp: Date // message timestamp provided by exchange; some exchanges do not provide a separate liquidation timestamp, in which case this equals localTimestamp
localTimestamp: Date // message arrival timestamp
}
```
{% endtab %}
{% endtabs %}
### `normalizeOptionsSummary`
When passed as an arg to [`replayNormalized`](https://docs.tardis.dev/node-client/pages/gkHZyu4v8WrMNBBiqduR#replaynormalized-options-...normalizers) or [`streamNormalized`](https://docs.tardis.dev/node-client/pages/NugzOsZ9SfKsMBMmecqk#streamnormalized-options-...normalizers), it provides normalized `option_summary` data for exchanges that provide options data (e.g., Deribit, OKX Options, Binance European Options). Includes greeks, implied volatility, and best bid/ask.
{% tabs %}
{% tab title="sample message" %}
```javascript
{
type: 'option_summary',
symbol: 'BTC-28JUN24-70000-C',
exchange: 'deribit',
optionType: 'call',
strikePrice: 70000,
expirationDate: 2024-06-28T08:00:00.000Z,
bestBidPrice: 0.035,
bestBidAmount: 5,
bestBidIV: 0.55,
bestAskPrice: 0.04,
bestAskAmount: 10,
bestAskIV: 0.58,
lastPrice: 0.0375,
openInterest: 150,
markPrice: 0.0372,
markIV: 0.565,
delta: 0.25,
gamma: 0.00002,
vega: 45.5,
theta: -15.2,
rho: 0.05,
underlyingPrice: 63500,
underlyingIndex: 'BTC-USD',
timestamp: 2024-01-15T10:30:00.123Z,
localTimestamp: 2024-01-15T10:30:00.234Z
}
```
{% endtab %}
{% tab title="type definition" %}
```typescript
{
type: 'option_summary'
symbol: string // instrument symbol as provided by exchange
exchange: string // exchange id
optionType: 'put' | 'call' // option type
strikePrice: number // strike price
expirationDate: Date // option expiration date
bestBidPrice: number | undefined // best bid price
bestBidAmount: number | undefined // best bid amount
bestBidIV: number | undefined // best bid implied volatility
bestAskPrice: number | undefined // best ask price
bestAskAmount: number | undefined // best ask amount
bestAskIV: number | undefined // best ask implied volatility
lastPrice: number | undefined // last trade price
openInterest: number | undefined // open interest
markPrice: number | undefined // mark price
markIV: number | undefined // mark implied volatility
delta: number | undefined // delta greek
gamma: number | undefined // gamma greek
vega: number | undefined // vega greek
theta: number | undefined // theta greek
rho: number | undefined // rho greek
underlyingPrice: number | undefined // underlying asset price
underlyingIndex: string // underlying index name
timestamp: Date // message timestamp provided by exchange
localTimestamp: Date // message arrival timestamp
}
```
{% endtab %}
{% endtabs %}
### `disconnect` message
When [`replayNormalized`](https://docs.tardis.dev/node-client/pages/gkHZyu4v8WrMNBBiqduR#replaynormalized-options-...normalizers) or [`streamNormalized`](https://docs.tardis.dev/node-client/pages/NugzOsZ9SfKsMBMmecqk#streamnormalized-options-...normalizers) have the `withDisconnectMessages` flag set to `true` and a disconnect event occurs (e.g., WebSocket connection close), a `disconnect` message is returned.
{% tabs %}
{% tab title="sample message" %}
```typescript
{
type: 'disconnect',
exchange: 'binance',
localTimestamp: 2024-03-01T00:00:00.001Z
}
```
{% endtab %}
{% tab title="type definition" %}
```typescript
{
type: 'disconnect'
exchange: string // exchange id
localTimestamp: Date // timestamp when disconnect occurred
symbols: string[] | undefined
}
```
{% endtab %}
{% endtabs %}
### Modifying built-in and adding custom normalizers
In `tardis-dev` data normalization is implemented via `normalize` factory functions provided to [`replayNormalized`](https://docs.tardis.dev/node-client/pages/gkHZyu4v8WrMNBBiqduR#replaynormalized-options-...normalizers) and [`streamNormalized`](https://docs.tardis.dev/node-client/pages/NugzOsZ9SfKsMBMmecqk#streamnormalized-options-...normalizers) functions. This design gives lots of flexibility by allowing replacing, extending and modifying built-in normalizers or adding new ones for new normalized data types without the need of forking the whole library.
Any normalize function provided to [`replayNormalized`](https://docs.tardis.dev/node-client/pages/gkHZyu4v8WrMNBBiqduR#replaynormalized-options-...normalizers) and [`streamNormalized`](https://docs.tardis.dev/node-client/pages/NugzOsZ9SfKsMBMmecqk#streamnormalized-options-...normalizers) functions needs to have following signature:
```
(exchange: string, localTimestamp: Date) => Mapper
```
`Exchange` is the exchange id for which a mapper object must be returned, `localTimestamp` is the date for which the mapper is created (recreated after each disconnection). In most cases `localTimestamp` is not necessary for anything, but in certain cases like for example exchange API change it can be used to switch to different mapping logic like using new data channel that wasn't available until certain date.
Returned `Mapper` object has following signature:
```typescript
{
canHandle: (message: any) => boolean
map(message: any, localTimestamp: Date): IterableIterator | undefined
getFilters: (symbols?: string[]) => {channel: string, symbols?: string[]}[]
}
```
On every disconnection event, normalize factory functions are called again to provide new `Mapper` objects with clean state if required (stateful mapping needs to persist metadata such as price level IDs and reset for each new connection). If a mapper object is stateful, it is required to always return a new clean state object from the normalize factory function or reset its state in one way or another.
Normalized data returned by [`iterable iterator`](https://developer.mozilla.org/pl/docs/Web/JavaScript/Guide/Iterators_and_Generators) of `Mapper.map` method is expected to have a shape that has at least fields as described in [normalized data type section](#normalized-data-type) below to play well with other `tardis-dev` functions like [`combine`](#combining-data-streams) or [`compute`](#computing-derived-data-locally).
#### normalized data type
```typescript
{
type: string
symbol: string
exchange: string
timestamp: Date
localTimestamp: Date
name? : string | undefined
}
```
#### Adding custom `normalizeLiquidations` normalizer
Example implementation of a custom `normalizeLiquidations` function that normalizes liquidations data for `deribit` exchange. Implementations for other exchanges are left as an exercise for the reader.
**type of messages provided by `normalizeLiquidations`**
```typescript
{
type: 'liquidation'
symbol: string
exchange: string
side: 'buy' | 'sell'
amount: number
price: number
timestamp: Date
localTimestamp: Date
}
```
implementation of `deribitLiquidations` mapper and `normalizeLiquidations`
```javascript
// object that maps from deribit trades real-time channel to our custom
// liquidations messages if determines that trade was caused by liquidation
const deribitLiquidationsMapper = {
// function that given message in deribit native format
// https://docs.deribit.com/v2/#trades-instrument_name-interval
// determines if such message can be mapped/normalized
canHandle(message) {
const params = message.params
const channel = params !== undefined ? params.channel : undefined
if (channel === undefined) {
return false
}
return (
channel.startsWith('trades') &&
params.data.some(trade => trade.liquidation !== undefined)
)
},
// given symbols returns filters that are provided
// as filters to replay & stream functions options
// in our case we're interested in trades deribit channel
// but it could be multiple channels in certain scenarions as well
getFilters(symbols) {
return [
{
channel: 'trades',
symbols
}
]
},
// map message that was determined that is can be handled via canHandle
// to normalized liquidation message
*map(message, localTimestamp) {
for (const deribitLiquidationTrade of message.params.data) {
if (deribitLiquidationTrade.liquidation === undefined) {
continue
}
yield {
type: 'liquidation',
symbol: deribitLiquidationTrade.instrument_name,
exchange: 'deribit',
price: deribitLiquidationTrade.price,
amount: deribitLiquidationTrade.amount,
side: deribitLiquidationTrade.direction,
timestamp: new Date(deribitLiquidationTrade.timestamp),
localTimestamp: localTimestamp
}
}
}
}
// provides factory function that given exchange returns mapper for it
// if such mapper if implemented
// in our case deribitLiquidationsMapper is stateless so we can return the same
// instance every time
const normalizeLiquidations = (exchange, localTimestamp) => {
if (exchange === 'deribit') {
return deribitLiquidationsMapper
}
throw new Error(`normalizeLiquidations: ${exchange} not supported`)
}
```
**`normalizeLiquidations` usage example**
We could as well provide the same `normalizeLiquidations` function to [`streamNormalized`](https://docs.tardis.dev/node-client/pages/NugzOsZ9SfKsMBMmecqk#streamnormalized-options-...normalizers) function or use it together it with other normalizers (`normalizeTrades` etc.).
```javascript
import { replayNormalized } from 'tardis-dev'
const liquidations = replayNormalized(
{
exchange: 'deribit',
symbols: ['BTC-PERPETUAL'],
from: '2024-03-01',
to: '2024-03-02'
},
normalizeLiquidations
)
for await (const liquidation of liquidations) {
console.log(liquidation)
}
```
#### Changing `normalizeTrades` for Binance exchange
Let's assume that default normalization of Binance exchange trades data doesn't fit our use case and we need to use [`@aggTrade`](https://github.com/binance-exchange/binance-official-api-docs/blob/master/web-socket-streams.md#aggregate-trade-streams) stream as a source of trade data instead of the default [`@trade`](https://github.com/binance-exchange/binance-official-api-docs/blob/master/web-socket-streams.md#trade-streams) stream.
```javascript
// add custom binance trades mapper that used @aggTrade stream as source of
// normalized trades
const customBinanceTradesMapper = {
canHandle(message) {
return message.stream && message.stream.endsWith('@aggTrade')
},
getFilters(symbols) {
if (symbols !== undefined) {
symbols = symbols.map(s => s.toLocaleLowerCase())
}
// binance api expects all symbols to be lower cased
return [
{
channel: 'aggTrade',
symbols
}
]
},
*map(message, localTimestamp) {
const binanceAggTrade = message.data
yield {
type: 'trade',
symbol: binanceAggTrade.s,
exchange: 'binance',
id: String(binanceAggTrade.a),
price: Number(binanceAggTrade.p),
amount: Number(binanceAggTrade.q),
side: binanceAggTrade.m ? 'sell' : 'buy',
timestamp: new Date(binanceAggTrade.T),
localTimestamp: localTimestamp
}
}
}
// add new normalize function that only for binance exchange
// uses custom trades mapper and defaults to default normalizeTrades
// for other exchanges
const normalizeTradesWithBinancePatch = (exchange, localTimestamp) => {
if (exchange === 'binance') {
return customBinanceTradesMapper
}
return normalizeTrades(exchange, localTimestamp)
}
```
**`normalizeTradesWithBinancePatch` usage example**
```javascript
import { streamNormalized } from 'tardis-dev'
const messages = streamNormalized(
{
exchange: 'binance',
symbols: ['btcusdt']
},
normalizeTradesWithBinancePatch
)
for await (const message of messages) {
console.log(message)
}
```
## Limit order book reconstruction
`tardis-dev` exports `OrderBook` class that, when instantiated, can process normalized [`book_change`](#normalizebookchanges) messages with order book snapshots and incremental updates and allows maintaining full local order book (level 2 - aggregated market-by-price) state both for real-time data and for reconstructing historical order book state at any past point in time. It waits for the first `book_change` message that is a snapshot (`isSnapshot = true`) and then applies subsequent updates to it. A single `orderBook` object can maintain order book state only for a single symbol/instrument. It uses a [Red-Black tree](https://github.com/vadimg/js_bintrees) data structure under the hood to efficiently maintain its local state in sorted order.
{% tabs %}
{% tab title="historical order book reconstruction" %}
```javascript
import { replayNormalized, normalizeBookChanges, OrderBook } from 'tardis-dev'
const books = {
BTCUSDT: new OrderBook(),
ETHUSDT: new OrderBook()
}
const messages = replayNormalized(
{
exchange: 'binance-futures',
symbols: ['BTCUSDT', 'ETHUSDT'],
from: '2024-03-01',
to: '2024-03-02'
},
normalizeBookChanges
)
for await (const message of messages) {
const orderBook = books[message.symbol]
if (message.type === 'book_change') {
orderBook.update(message)
}
const timestamp = message.localTimestamp.toISOString()
// print best bid/ask for every exchange tick
console.log(timestamp, orderBook.bestAsk(), orderBook.bestBid())
}
```
{% endtab %}
{% tab title="maintaining order book for real-time stream" %}
```javascript
import { streamNormalized, normalizeBookChanges, OrderBook } from 'tardis-dev'
const books = {
BTCUSDT: new OrderBook(),
ETHUSDT: new OrderBook()
}
const messages = streamNormalized(
{
exchange: 'binance-futures',
symbols: ['BTCUSDT', 'ETHUSDT']
},
normalizeBookChanges
)
for await (const message of messages) {
const orderBook = books[message.symbol]
if (message.type === 'book_change') {
orderBook.update(message)
}
const timestamp = message.localTimestamp.toISOString()
// print best bid/ask for every exchange tick
console.log(timestamp, orderBook.bestAsk(), orderBook.bestBid())
}
```
{% endtab %}
{% endtabs %}
#### OrderBook constructor options
`new OrderBook()` accepts an optional options object:
| name | type | default | description |
| --------------------------- | ------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`removeCrossedLevels`** | boolean (optional) | undefined | when set to `true`, automatically detects and removes crossed levels (where best bid >= best ask) that can occur when exchanges fail to publish delete messages |
| **`onCrossedLevelRemoved`** | function (optional) | undefined | optional callback `(bookChange, bestBidBefore, bestBidAfter, bestAskBefore, bestAskAfter) => void` invoked whenever a crossed level is removed |
### `orderBook.update(bookChange)`
Processes normalized [`book_change`](#normalizebookchanges) messages to update its internal local state that maintains ordered bids and asks sets. It ignores any non-snapshot `book_change` messages before an initial snapshot is received. It should be called for every `book_change` message received for the symbol for which you'd like to reconstruct the order book.
```javascript
orderBook.update({
type: 'book_change',
symbol: 'BTCUSDT',
exchange: 'binance-futures',
isSnapshot: false,
bids: [],
asks: [{ price: 7985, amount: 283318 }],
timestamp: new Date(),
localTimestamp: new Date()
})
```
### `orderBook.bestBid()`
Returns [book price level object](#book-price-level-type) for highest bid order (best bid) in order book or `undefined` if book doesn't have any bids (not initialized yet with initial snapshot).
```javascript
const { price, amount } = orderBook.bestBid()
```
### `orderBook.bestAsk()`
Returns [book price level object](#book-price-level-type) for lowest ask order (best ask) in order book or `undefined` if book doesn't have any asks (not initialized yet with initial snapshot).
```javascript
const { price, amount } = orderBook.bestAsk()
```
### `orderBook.asks()`
Returns [iterable iterator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators) of [book price level](#book-price-level-type) objects for all **asks** available ordered from the lowest to highest ask.
```typescript
for (const ask of orderBook.asks()) {
// process asks levels one by one from lowest to highest without
// creating in memory array for all levels
}
const orderedAsksArray = Array.from(orderBook.asks())
```
### `orderBook.bids()`
Returns [iterable iterator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators) of [book price level](#book-price-level-type) objects for all **bids** available ordered from highest to lowest bid.
```typescript
for (const bid of orderBook.bids()) {
// process bid levels one by one from highest to lowest without
// creating in memory array for all levels
}
const orderedBidsArray = Array.from(orderBook.bids())
```
#### book price level type
```typescript
{
price: number
amount: number
}
```
## Utility functions
### `filter(asyncIterable, fn)`
Filters an async iterable, returning only messages that match the predicate function.
```javascript
import { replayNormalized, normalizeTrades, filter } from 'tardis-dev'
const messages = replayNormalized(
{ exchange: 'binance', from: '2024-03-01', to: '2024-03-02', symbols: ['btcusdt'] },
normalizeTrades
)
const largeTrades = filter(messages, (trade) => trade.amount >= 10000)
for await (const trade of largeTrades) {
console.log(trade)
}
```
### `uniqueTradesOnly(options?)`
Returns a predicate function for use with [`filter()`](#filter-asynciterable-fn) that removes duplicate trades (same trade ID) and optionally skips stale trades.
**Options**
| Name | Type | Default | Description |
| --------------------------- | ------------------------ | ------- | ------------------------------------------------------------------------------------------- |
| `maxWindow` | `number` | `500` | Maximum number of trade IDs to track per symbol for deduplication |
| `skipStaleOlderThanSeconds` | `number` | — | If set, skips trades where `localTimestamp - timestamp` exceeds this threshold (in seconds) |
| `onDuplicateFound` | `(trade: Trade) => void` | — | Optional callback invoked when a duplicate or stale trade is detected |
```javascript
import { replayNormalized, normalizeTrades, filter, uniqueTradesOnly } from 'tardis-dev'
const messages = replayNormalized(
{ exchange: 'binance', from: '2024-03-01', to: '2024-03-02', symbols: ['btcusdt'] },
normalizeTrades
)
const uniqueTrades = filter(messages, uniqueTradesOnly())
for await (const trade of uniqueTrades) {
console.log(trade)
}
```
**With options**
```javascript
const uniqueTrades = filter(messages, uniqueTradesOnly({
maxWindow: 1000,
skipStaleOlderThanSeconds: 30,
onDuplicateFound: (trade) => console.warn('Duplicate trade:', trade.id)
}))
```
## Combining data streams
### `combine(...iterators)`
[`Combine`](#combining-data-streams) function given multiple `async iterators` combines them into single one. That allows synchronized historical market data replay and consolidated streaming of real-time data for multiple exchanges via single [`for await ...of`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of) loop.
Accepts `async iterables` of [normalized messages](/node-client/normalization) as [rest parameters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/rest_parameters) and combines them returning single `async iteratable`.
For historical data replay it combines input `async iterables` messages by sorting them by `localTimestamp` in ascending order, this allows synchronized/ordered market data replay for multiple exchanges.
For real-time market data streaming it combines input `async iterables` messages in FIFO order by writing them into a shared Node.js object-mode stream (`PassThrough`) as they arrive.
{% tabs %}
{% tab title="combining historical market data from multiple exchanges" %}
```javascript
import { replayNormalized, normalizeTrades, combine } from 'tardis-dev'
const binanceMessages = replayNormalized(
{
exchange: 'binance',
symbols: ['btcusdt'],
from: '2024-03-01',
to: '2024-03-02'
},
normalizeTrades
)
const binanceFuturesMessages = replayNormalized(
{
exchange: 'binance-futures',
symbols: ['BTCUSDT'],
from: '2024-03-01',
to: '2024-03-02'
},
normalizeTrades
)
const combinedStream = combine(binanceMessages, binanceFuturesMessages)
// order at which messages have historically arrived is preserved
for await (const message of combinedStream) {
if (message.exchange === 'binance-futures') {
// process binance futures trades
console.log(message)
}
if (message.exchange === 'binance') {
// process binance spot trades
console.log(message)
}
}
```
{% endtab %}
{% tab title="combining real-time stream of market data from multiple exchanges" %}
```javascript
import { streamNormalized, normalizeTrades, combine } from 'tardis-dev'
const binanceMessages = streamNormalized(
{
exchange: 'binance',
symbols: ['btcusdt']
},
normalizeTrades
)
const binanceFuturesMessages = streamNormalized(
{
exchange: 'binance-futures',
symbols: ['BTCUSDT']
},
normalizeTrades
)
const combinedStream = combine(binanceMessages, binanceFuturesMessages)
// messages are provided in FIFO order as they arrive
for await (const message of combinedStream) {
if (message.exchange === 'binance-futures') {
// process binance futures trades
console.log(message)
}
if (message.exchange === 'binance') {
// process binance spot trades
console.log(message)
}
}
```
{% endtab %}
{% endtabs %}
## Computing derived data locally
### `compute(iterator, ...computables)`
[`Compute`](#computing-derived-data-locally) function allows computing various derived data locally via so called [`computables`](#adding-custom-computable) like:
* [`computeTradeBars`](#computetradebars-options) - computes various trade bars (OHLC, volume based bars, tick based bars) based on [normalized trade](#normalizetrades) data
* [`computeBookSnapshots`](#computebooksnapshots-options) - computes various order book snapshots based on normalized [order book data](#normalizebookchanges)
If you're interested in adding custom [`computables`](#adding-custom-computable) like for example order book imbalance, volume imbalance, open interest or funding rate based bars please read ["adding custom computable"](#adding-custom-computable) section.
[`Compute`](#computing-derived-data-locally) function accepts an `async iterable` producing [normalized messages](/node-client/normalization) together with [`computables`](#adding-custom-computable) as [rest parameters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/rest_parameters), and returns an `async iterable` with normalized messages produced by the provided iterable plus all computed messages based on provided [`computable`](#adding-custom-computable) functions. It computes and produces separate normalized computed messages for each symbol and exchange combination. When a [`disconnect message`](#disconnect-message) is returned by the provided `async iterable`, it discards existing pending computables and starts computing them from scratch.
```javascript
import { streamNormalized, normalizeTrades, normalizeBookChanges, compute, computeTradeBars, computeBookSnapshots } from 'tardis-dev'
const binanceFuturesMessages = streamNormalized(
{
exchange: 'binance-futures',
symbols: ['BTCUSDT']
},
normalizeTrades,
normalizeBookChanges
)
const messagesWithComputedTypes = compute(
binanceFuturesMessages,
// 10 seconds time bars
computeTradeBars({ kind: 'time', interval: 10 * 1000 }),
// top 20 levels 50 millisecond order book snapshots
computeBookSnapshots({ depth: 20, interval: 50 }),
// volume based trade bar - 1 million vol buckets
computeTradeBars({ kind: 'volume', interval: 1000 * 1000 })
)
for await (const message of messagesWithComputedTypes) {
if (message.type === 'book_snapshot' || message.type === 'trade_bar') {
console.log(message)
}
}
```
### `computeTradeBars(options)`
When provided to [`compute`](#computing-derived-data-locally) function, it computes normalized [`trade_bar`](#type-of-message-provided-by-computetradebars) messages based on [normalized trade](#normalizetrades) data.
```javascript
import { computeTradeBars } from 'tardis-dev'
computeTradeBars({ kind: 'volume', interval: 1000 })
```
#### compute trade bars options
| name | type | default | description |
| ------------ | --------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **kind** | `'time'`, `'volume'`, or `'tick'` | - | determines the way trades within a bar will be aggregated. `time` creates classic OHLC candles aggregated by time. `volume` creates volume-based trade bars aggregated by the sum of trades `amount`. `tick` creates trade bars aggregated by trades count. |
| **interval** | number | - | determines interval to aggregate by - for time based bars it's number of milliseconds, for volume based bars it's accumulated volume, for tick it's count of trades |
| **name** | string (optional) | undefined | optional custom name of `trade_bar`, if not specified computed name will be provided based on kind and interval options |
#### type of message provided by `computeTradeBars`
```typescript
{
type: 'trade_bar'
symbol: string // instrument symbol as provided by exchange
exchange: string // exchange id
name: string // name with format trade_bar_{interval}{suffix}
interval: number // requested trade bar interval
kind: 'time' | 'volume' | 'tick' // trade bar kind
open: number // open price
high: number // high price
low: number // low price
close: number // close price
volume: number // total volume traded in given interval
buyVolume: number // buy volume traded in given interval
sellVolume: number // sell volume traded in given interval
trades: number // trades count in given interval
vwap: number // volume weighted average price
openTimestamp: Date // timestamp of first trade for given bar
closeTimestamp: Date // timestamp of last trade for given bar
timestamp: Date // end of interval period timestamp
localTimestamp: Date // message arrival timestamp
// that triggered given bar computation
}
```
#### sample normalized `trade_bar` message
```javascript
{
type: 'trade_bar',
symbol: 'BTCUSDT',
exchange: 'binance-futures',
name: 'trade_bar_10000ms',
interval: 10000,
kind: 'time',
open: 61130.98,
high: 61142.3,
low: 61129.75,
close: 61138.12,
volume: 12.845,
buyVolume: 7.421,
sellVolume: 5.424,
trades: 18,
vwap: 61135.84,
openTimestamp: 2024-03-01T00:00:00.112Z,
closeTimestamp: 2024-03-01T00:00:09.881Z,
localTimestamp: 2024-03-01T00:00:10.004Z,
timestamp: 2024-03-01T00:00:10.000Z,
}
```
### `computeBookSnapshots(options)`
When provided to [`compute`](#computing-derived-data-locally) function, computes normalized [`book_snapshot`](#type-of-message-provided-by-computebooksnapshots) messages based on normalized [order book data](#normalizebookchanges). It produces new snapshots only if there is an actual change in order book state for requested `depth`.
```javascript
import { computeBookSnapshots } from 'tardis-dev'
computeBookSnapshots({ depth: 20, interval: 50 })
```
#### compute book snapshots options
| name | type | default | description |
| ------------------------- | ------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **depth** | number | - | number of closest bids and asks levels to provide snapshot for |
| **interval** | number | - | snapshot interval in milliseconds, if `0` is provided it computes snapshots real-time any time there is a change in order book state for requested `depth` |
| **name** | string (optional) | undefined | optional custom name of `book_snapshot`, if not specified computed name will be provided based on depth and interval options |
| **grouping** | number (optional) | undefined | when provided, aggregates order book price levels into groups of the specified price increment (e.g., `10` groups all levels within each $10 range into a single level). Bids are floored and asks are ceiled to the grouping boundary. |
| **removeCrossedLevels** | boolean (optional) | undefined | when set to `true`, automatically detects and removes crossed levels (where best bid >= best ask) that can occur when exchanges fail to publish delete messages |
| **onCrossedLevelRemoved** | function (optional) | undefined | optional callback `(bookChange, bestBidBefore, bestBidAfter, bestAskBefore, bestAskAfter) => void` invoked whenever a crossed level is removed |
#### type of message provided by `computeBookSnapshots`
```typescript
{
type: 'book_snapshot'
symbol: string // instrument symbol as provided by exchange
exchange: string // exchange id
name: string // name with format book_snapshot_{depth}_{interval}{time_unit}
depth: number // requested number of levels (top bids/asks)
interval: number // requested snapshot interval in milliseconds
bids: { price: number | undefined; amount: number | undefined }[] // top "depth" bids price-amount levels
asks: { price: number | undefined; amount: number | undefined }[] // top "depth" asks price-amount levels
grouping: number | undefined // price grouping increment, if grouping was requested
timestamp: Date // snapshot timestamp based on last book_change message
// processed timestamp adjusted to snapshot interval
localTimestamp: Date // message arrival timestamp
// that triggered snapshot
}
```
#### sample normalized `book_snapshot` message
```javascript
{
type: 'book_snapshot',
symbol: 'BTCUSDT',
exchange: 'binance-futures',
name: 'book_snapshot_2_50ms',
depth: 2,
interval: 50,
bids: [
{ price: 61141.09, amount: 2.02515 },
{ price: 61141.08, amount: 0.55321 }
],
asks: [
{ price: 61141.1, amount: 4.09368 },
{ price: 61141.11, amount: 1.20457 }
],
timestamp: 2024-03-01T00:00:01.450Z,
localTimestamp: 2024-03-01T00:00:01.491Z
}
```
### Adding custom `computable`
Any `computables` provided to [`compute function`](#computing-derived-data-locally) need to be factory functions with following signature:
```
() => Computable
```
where returned `Computable` object has following signature:
```typescript
{
sourceDataTypes: string[]
compute(message: NormalizedData): IterableIterator
}
```
`Computable.compute` returned iterator is expected to provide objects that at least have fields as described in [normalized data type section](#normalized-data-type) to play well with other `tardis-dev` functions like [`combine`](#combining-data-streams).
#### `computeOrderBookImbalanceRatio()`
Example implementation of custom `computeOrderBookImbalanceRatio` function that as a source data type uses book snapshots and based on it computes ratio of asks amounts (sell orders) to bids amounts (buy orders) for given [`book_snapshot`](#computebooksnapshots-options) depth. It may be used to determine relative buy or sell pressure.
**type of messages produced by** `computeOrderBookImbalanceRatio`
```typescript
{
type: 'book_imbalance'
symbol: string
exchange: string
asksToBidsRatio: number
timestamp: Date
localTimestamp: Date
}
```
#### implementation of `BookImbalanceRatioComputable` `computable` and `computeOrderBookImbalanceRatio` factory function.
```javascript
class BookImbalanceRatioComputable {
constructor() {
this.sourceDataTypes = ['book_snapshot']
}
*compute(bookSnapshot) {
let bidsAmount = 0
let asksAmount = 0
for (let i = 0; i < bookSnapshot.depth; i++) {
bidsAmount += bookSnapshot.bids[i].amount
asksAmount += bookSnapshot.asks[i].amount
}
const asksToBidsRatio = asksAmount / bidsAmount
yield {
type: 'book_imbalance',
symbol: bookSnapshot.symbol,
exchange: bookSnapshot.exchange,
asksToBidsRatio,
timestamp: bookSnapshot.timestamp,
localTimestamp: bookSnapshot.localTimestamp
}
}
}
const computeOrderBookImbalanceRatio = () => new BookImbalanceRatioComputable()
```
#### `computeOrderBookImbalanceRatio` **usage example**
Given implementation above we can compute book imbalance ratio for Binance Futures real-time `BTCUSDT` message stream. For this example we compute top 5 levels, 2 second book snapshots as a source to our custom computable. We need to have `async iterable` that produces book snapshots as a source to our book imbalance computable, hence two invocations of `compute.`
```javascript
import { streamNormalized, normalizeBookChanges, compute, computeBookSnapshots } from 'tardis-dev'
const binanceFuturesMessages = streamNormalized(
{
exchange: 'binance-futures',
symbols: ['BTCUSDT']
},
normalizeBookChanges
)
const messagesWithBookSnapshots = compute(
binanceFuturesMessages,
computeBookSnapshots({ depth: 5, interval: 2 * 1000 })
)
const messagesWithComputedData = compute(
messagesWithBookSnapshots,
computeOrderBookImbalanceRatio
)
for await (const message of messagesWithComputedData) {
if (message.type === 'book_imbalance') {
console.log(message)
}
}
```
## Examples
### Real-time spread across multiple exchanges
Example showing how to display real-time spread and best bid/ask info across multiple exchanges at once. It can be easily adapted to do the same for historical data ([`replayNormalized`](https://docs.tardis.dev/node-client/pages/gkHZyu4v8WrMNBBiqduR#replaynormalized-options-...normalizers) instead of [`streamNormalized`](https://docs.tardis.dev/node-client/pages/NugzOsZ9SfKsMBMmecqk#streamnormalized-options-...normalizers)).
```javascript
import { streamNormalized, normalizeBookChanges, combine, compute, computeBookSnapshots } from 'tardis-dev'
const exchangesToStream = [
{ exchange: 'binance', symbols: ['btcusdt'] },
{ exchange: 'binance-futures', symbols: ['BTCUSDT'] },
{ exchange: 'bybit', symbols: ['BTCUSDT'] }
]
// for each specified exchange call streamNormalized for it
// so we have multiple real-time streams for all specified exchanges
const realTimeStreams = exchangesToStream.map(e => {
return streamNormalized(e, normalizeBookChanges)
})
// combine all real-time message streams into one
const messages = combine(...realTimeStreams)
// create book snapshots with depth1 that are produced
// every time best bid/ask info is changed
// effectively computing real-time quotes
const realTimeQuoteComputable = computeBookSnapshots({
depth: 1,
interval: 0,
name: 'realtime_quote'
})
// compute real-time quotes for combines real-time messages
const messagesWithQuotes = compute(messages, realTimeQuoteComputable)
const spreads = {}
// print spreads info every 100ms
setInterval(() => {
console.clear()
console.log(spreads)
}, 100)
// update spreads info real-time
for await (const message of messagesWithQuotes) {
if (message.type === 'book_snapshot') {
spreads[message.exchange] = {
spread: message.asks[0].price - message.bids[0].price,
bestBid: message.bids[0],
bestAsk: message.asks[0]
}
}
}
```
### Replay large historical trades across multiple exchanges
Example showing replaying large historical trades across multiple exchanges as those happened.
```javascript
import { replayNormalized, normalizeTrades, combine } from 'tardis-dev'
const from = '2024-03-01'
const to = '2024-03-02'
const exchanges = [
{ exchange: 'binance', symbols: ['btcusdt'] },
{ exchange: 'binance-futures', symbols: ['BTCUSDT'] },
{ exchange: 'bybit', symbols: ['BTCUSDT'] }
]
const historicalTrades = exchanges.map(exchange => {
return replayNormalized({ from, to, ...exchange }, normalizeTrades)
})
const LARGE_TRADE_THRESHOLD = 100 * 1000 // 100k contracts
for await (const trade of combine(...historicalTrades)) {
if (trade.amount >= LARGE_TRADE_THRESHOLD) {
console.log(trade.exchange, trade)
}
}
```
### Seamless switching between real-time streaming and historical market data replay
Example showing a simple pattern of providing an `async iterable` of market data messages to a function that can process them whether it is real-time or historical market data. That effectively enables having the same data pipeline for backtesting and live trading.
```javascript
import { replayNormalized, streamNormalized, normalizeTrades, compute, computeTradeBars } from 'tardis-dev'
const historicalMessages = replayNormalized(
{
exchange: 'binance-futures',
symbols: ['BTCUSDT'],
from: '2024-03-01',
to: '2024-03-02'
},
normalizeTrades
)
const realTimeMessages = streamNormalized(
{
exchange: 'binance-futures',
symbols: ['BTCUSDT']
},
normalizeTrades
)
async function produceVolumeBasedTradeBars(messages) {
const withVolumeTradeBars = compute(
messages,
computeTradeBars({
kind: 'volume',
interval: 100 * 1000 // aggregate by 100k contracts volume
})
)
for await (const message of withVolumeTradeBars) {
if (message.type === 'trade_bar') {
console.log(message.name, message)
}
}
}
produceVolumeBasedTradeBars(historicalMessages)
// or for real time data
// await produceVolumeBasedTradeBars(realTimeMessages)
```
### Real-time funding rate and open interest across multiple exchanges
Example showing how to quickly display real-time funding rate and open interest info across multiple exchanges at once.
```javascript
import { streamNormalized, normalizeDerivativeTickers, combine } from 'tardis-dev'
const exchangesToStream = [
{ exchange: 'binance-futures', symbols: ['BTCUSDT'] },
{ exchange: 'bybit', symbols: ['BTCUSDT'] },
{ exchange: 'okex-swap', symbols: ['BTC-USD-SWAP'] },
{ exchange: 'deribit', symbols: ['BTC-PERPETUAL'] },
{ exchange: 'bitfinex-derivatives', symbols: ['BTCF0:USTF0'] }
]
const realTimeStreams = exchangesToStream.map(e => {
return streamNormalized(e, normalizeDerivativeTickers)
})
// combine all real-time message streams into one
const messages = combine(...realTimeStreams)
const funding = {}
// print funding info every 100ms
setInterval(() => {
console.clear()
console.log(new Date().toISOString(), funding)
}, 100)
// update funding info real-time
for await (const message of messages) {
if (message.type === 'derivative_ticker') {
funding[message.exchange] = {
symbol: message.symbol,
fundingRate: message.fundingRate,
lastPrice: message.lastPrice,
openInterest: message.openInterest,
markPrice: message.markPrice
}
}
}
```
### Saving historical funding, index and open interest data to CSV file
Example showing how to write Deribit exchange historical funding, index and open interest data into CSV.
```javascript
import { replayNormalized, normalizeDerivativeTickers } from 'tardis-dev'
import fs from 'fs'
import csv from 'fast-csv'
import { once } from 'events'
const fileStream = fs.createWriteStream('./deribit_funding.csv')
const csvStream = csv.format({ headers: true })
csvStream.pipe(fileStream)
const messages = replayNormalized(
{
exchange: 'deribit',
from: '2024-03-01',
to: '2024-03-02',
symbols: ['BTC-PERPETUAL']
},
normalizeDerivativeTickers
)
for await (const message of messages) {
if (message.type === 'derivative_ticker') {
const ok = csvStream.write({
fundingRate: message.fundingRate,
lastPrice: message.lastPrice,
openInterest: message.openInterest,
indexPrice: message.indexPrice,
timestamp: message.timestamp.toISOString()
})
if (!ok) {
await once(csvStream, 'drain')
}
}
}
```
### Computing simple moving average of volume based trade bars
Example showing implementation of `SimpleMovingAverageComputable` that calculates average of trade bar closes prices for specified rolling window in incremental way. It uses `CircularBuffer` under the hood.
```javascript
class CircularBuffer {
constructor(_bufferSize) {
this._bufferSize = _bufferSize
this._buffer = []
this._index = 0
}
append(value) {
const isFull = this._buffer.length === this._bufferSize
let poppedValue
if (isFull) {
poppedValue = this._buffer[this._index]
}
this._buffer[this._index] = value
this._index = (this._index + 1) % this._bufferSize
return poppedValue
}
*items() {
for (let i = 0; i < this._buffer.length; i++) {
const index = (this._index + i) % this._buffer.length
yield this._buffer[index]
}
}
get count() {
return this._buffer.length
}
}
class SimpleMovingAverageComputable {
constructor({ periods }) {
this.sourceDataTypes = ['trade_bar']
this._average = 0
this._circularBuffer = new CircularBuffer(periods)
}
*compute(tradeBar) {
const result = this._circularBuffer.append(tradeBar.close)
const poppedVal = result !== undefined ? result : this._average
const increment = (tradeBar.close - poppedVal) / this._circularBuffer.count
this._average = this._average + increment
yield {
type: 'sma',
symbol: tradeBar.symbol,
exchange: tradeBar.exchange,
name: `sma_${tradeBar.name}`,
average: this._average,
interval: tradeBar.interval,
kind: tradeBar.kind,
timestamp: tradeBar.timestamp,
localTimestamp: tradeBar.localTimestamp
}
}
}
const computeSimpleMovingAverages = options => () =>
new SimpleMovingAverageComputable(options)
```
#### Usage
```javascript
import { streamNormalized, normalizeTrades, compute, computeTradeBars } from 'tardis-dev'
const messages = streamNormalized(
{
exchange: 'binance-futures',
symbols: ['BTCUSDT']
},
normalizeTrades
)
const withTradeBars = compute(
messages,
computeTradeBars({
kind: 'volume',
interval: 1000
})
)
const withSimpleMovingAverage = compute(
withTradeBars,
computeSimpleMovingAverages({ periods: 5 })
)
for await (const message of withSimpleMovingAverage) {
if (message.type === 'sma') {
console.log(message)
}
}
```
## Environment variables (advanced)
The following environment variables configure streaming and network behavior. `HTTP_PROXY` applies to both real-time streaming and historical data downloads. Exchange credentials and WebSocket URL overrides apply only to real-time streaming.
#### Network
| Name | Description |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`HTTP_PROXY`** | HTTP/HTTPS proxy URL for all outgoing requests |
| **`WSS_URL_`** | Override the default WebSocket URL for a specific exchange. Exchange name is uppercased with dashes replaced by underscores (e.g., `WSS_URL_BINANCE_US`) |
#### Exchange credentials
Required for exchanges that need authentication to access real-time WebSocket feeds.
| Name | Description |
| ------------------------------------------- | ------------------------------------------------------------------------------------------ |
| **`OKX_API_KEY`** | OKX API key — required for restricted real-time channels such as `books-l2-tbt` (VIP-only) |
| **`OKX_API_SECRET_KEY`** | OKX API secret key |
| **`OKX_API_PASSPHRASE`** | OKX API passphrase |
| **`OKX_API_VIP_5`** | Set to `true` if OKX account has VIP 5+ tier — enables access to `books-l2-tbt` channel |
| **`OKX_API_COLO`** | Set to `true` if using OKX colocation — enables access to `books-l2-tbt` channel |
| **`DERIBIT_API_CLIENT_ID`** | Deribit API client ID — required for authenticated real-time channels |
| **`DERIBIT_API_CLIENT_SECRET`** | Deribit API client secret |
| **`COINBASE_API_KEY`** | Coinbase API key — required for authenticated WebSocket feeds |
| **`COINBASE_API_SECRET`** | Coinbase API secret |
| **`COINBASE_API_PASSPHRASE`** | Coinbase API passphrase |
| **`COINBASE_INTERNATIONAL_API_KEY`** | Coinbase International API key |
| **`COINBASE_INTERNATIONAL_API_SECRET`** | Coinbase International API secret |
| **`COINBASE_INTERNATIONAL_API_PASSPHRASE`** | Coinbase International API passphrase |
#### Binance rate limit tuning
Control rate limiting for Binance depth snapshot requests and `openInterest` REST polling during real-time streaming. Variable names use the exchange name uppercased with dashes replaced by underscores (e.g., `BINANCE_FUTURES_REQUEST_WEIGHT_LIMIT`).
| Name | Default | Applies to | Description |
| -------------------------------------------------- | -------- | -------------- | --------------------------------------------------------------------- |
| **`_REQUEST_WEIGHT_LIMIT`** | from API | depth + OI | Override the request weight limit per minute |
| **`_MIN_AVAILABLE_WEIGHT_BUFFER`** | auto | depth + OI | Minimum request weight buffer before throttling kicks in |
| **`_CONCURRENCY_LIMIT`** | `4` | depth | Number of concurrent depth snapshot requests |
| **`_SNAPSHOTS_DELAY_MS`** | none | depth | Delay in ms between individual depth snapshot requests |
| **`_OPEN_INTEREST_POLLING_INTERVAL_MS`** | `5000` | `openInterest` | Minimum polling interval in ms for generated `openInterest` snapshots |
# Quickstart
Install via Docker or npm and run your first replay
[Tardis-machine](https://github.com/tardis-dev/tardis-machine) is a locally runnable server with built-in data caching that uses Tardis.dev [HTTP API](/api/http-api-reference) under the hood. It provides both tick-level historical and consolidated real-time cryptocurrency market data via its HTTP and WebSocket APIs and is available via [npm](#npm) and [Docker](#docker).
## Features
* efficient data replay API endpoints returning historical market data for whole time periods (in contrast to Tardis.dev [HTTP API](/api/http-api-reference) where single call returns data for single minute time period)
* [exchange-native market data APIs](/tardis-machine/replaying-historical-data#exchange-native-market-data-apis)
* tick-by-tick historical market data replay in [exchange-native format](/faq/data#what-is-a-difference-between-exchange-native-and-normalized-data-format)
* [HTTP](/tardis-machine/replaying-historical-data#http-get-replay-options-options) and [WebSocket](/tardis-machine/replaying-historical-data#websocket-ws-replay-exchange-exchange-and-from-fromdate-and-to-todate) endpoints
* [WebSocket API](/tardis-machine/replaying-historical-data#websocket-ws-replay-exchange-exchange-and-from-fromdate-and-to-todate) providing historical market data replay from any given past point in time with the same data format and 'subscribe' logic as real-time exchanges' APIs - in many cases **existing exchanges' WebSocket clients can be used to connect to this endpoint**
* [normalized market data APIs](/tardis-machine/replaying-historical-data#normalized-market-data-apis)
* consistent format for accessing market data across multiple exchanges
* [HTTP](/tardis-machine/replaying-historical-data#http-get-replay-normalized-options-options) and [WebSocket](/tardis-machine/replaying-historical-data#websocket-ws-replay-normalized-options-options) endpoints
* synchronized [historical market data replay across multiple exchanges](/tardis-machine/replaying-historical-data#http-get-replay-normalized-options-options)
* [consolidated real-time data streaming](/tardis-machine/streaming-real-time-data) connecting directly to exchanges' WebSocket APIs
* customizable [order book snapshots](/tardis-machine/data-types#book_snapshot_-number_of_levels-_-snapshot_interval-time_unit) and [trade bars](/tardis-machine/data-types#trade_bar_-aggregation_interval-suffix) data types
* [seamless switching between real-time data streaming and historical data replay](/tardis-machine/replaying-historical-data#normalized-market-data-apis)
* transparent historical local data caching (cached data is stored on disk in compressed format and decompressed on demand when reading the data)
* support for top cryptocurrency exchanges: [BitMEX](/historical-data-details/bitmex), [Deribit](/historical-data-details/deribit), [Binance Spot](/historical-data-details/binance), [Binance USDS-M Futures](/historical-data-details/binance-futures), [OKX Spot](/historical-data-details/okex), [HTX Spot](/historical-data-details/huobi), [bitFlyer](/historical-data-details/bitflyer), [Bitstamp](/historical-data-details/bitstamp), [Coinbase Exchange](/historical-data-details/coinbase), [Kraken Futures (Crypto Facilities)](/historical-data-details/cryptofacilities), [Gemini](/historical-data-details/gemini), [Kraken](/historical-data-details/kraken), [Bitfinex](/historical-data-details/bitfinex), [Bybit Derivatives](/historical-data-details/bybit) and more
* [Open Source](https://github.com/tardis-dev/tardis-machine)
{% embed url="" %}
Tardis-machine GitHub repository
{% endembed %}
{% hint style="info" %}
Real-time streaming via tardis-machine is available only in [normalized format](/tardis-machine/streaming-real-time-data). Exchange-native (raw) real-time data is not provided. If you need raw real-time feeds, connect directly to exchange WebSocket APIs.
{% endhint %}
## Installation
### **Docker**
Pull and run latest version of [`tardisdev/tardis-machine` image](https://hub.docker.com/r/tardisdev/tardis-machine):
```bash
### running without persistent local cache
docker run -p 8000:8000 -p 8001:8001 -e "TM_API_KEY=YOUR_API_KEY" -d tardisdev/tardis-machine
```
Tardis Machine HTTP endpoints will be available on port `8000` and WebSocket endpoints on port `8001`. Replace `YOUR_API_KEY` with your API key.
The command above does not use persistent volumes for local caching (each Docker restart will result in losing local data cache). To use `./host-cache-dir` as a persistent volume ([bind mount](https://docs.docker.com/storage/bind-mounts/)) cache directory, run:
```bash
docker run -v ./host-cache-dir:/.cache -p 8000:8000 -p 8001:8001 -e "TM_API_KEY=YOUR_API_KEY" -d tardisdev/tardis-machine
```
Docker bind mounts can be slower or harder to configure on some systems, especially Windows. You can run without a volume, but the local cache is lost on container restart.
#### Config environment variables
You can set the following environment variables to configure tardis-machine server:
| name | default | description |
| --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **TM\_API\_KEY** | | API key for [Tardis.dev](https://tardis.dev/) HTTP API - if not provided only first day of each month of historical data is accessible |
| **TM\_PORT** | `8000` | HTTP port on which server will be running, **WebSocket port is always this value + 1** (`8001` with port set to `8000`) |
| **PORT** | | if set, overrides the configured port from `TM_PORT` or `--port`; useful on platforms that inject `PORT` automatically |
| **TM\_CACHE\_DIR** | `/.cache` | path to local dir that will be used as cache location |
| **TM\_CLUSTER\_MODE** | `false` | will launch [cluster of Node.js processes](https://nodejs.org/api/cluster.html) to handle the incoming requests if set to `true`, by default server runs in single process mode |
| **TM\_DEBUG** | `false` | server will print verbose debug logs to stdout if set to `true` |
| **TM\_CLEAR\_CACHE** | `false` | server will clear local cache dir on startup if set to `true` |
{% hint style="info" %}
The local cache grows without limit by default. For large backfills this can consume significant disk space. Use `TM_CLEAR_CACHE=true` to clear the cache on startup, or set `autoCleanup: true` in [replay options](/tardis-machine/replaying-historical-data#replay-options) to remove cached data after each replay completes. See the [replay options](/tardis-machine/replaying-historical-data#replay-options) section for `autoCleanup` concurrency caveats.
{% endhint %}
Tardis-machine also supports exchange-specific environment variables (exchange credentials, proxy, WebSocket URL overrides, Binance rate limit tuning) — see the [Node.js client environment variables](/node-client/normalization#environment-variables-advanced) for the full list.
### **npm**
{% hint style="info" %}
Requires Node.js v24+ and git installed.
{% endhint %}
{% hint style="info" %}
Node.js examples in this section use ES modules and top-level await. Save snippets as `.mjs` or set `"type": "module"` in your `package.json`.
{% endhint %}
Install and run `tardis-machine` via `npx`:
```bash
npx tardis-machine --api-key=YOUR_API_KEY
```
or install globally via `npm`:
```bash
npm install -g tardis-machine
```
and then run:
```bash
tardis-machine --api-key=YOUR_API_KEY
```
Tardis Machine HTTP endpoints will be available on port `8000` and WebSocket endpoints on port `8001`. Replace `YOUR_API_KEY` with your API key.
#### **CLI config flags**
{% hint style="info" %}
You can configure tardis-machine server via [environment variables](#config-environment-variables) as described in Docker section as well.
{% endhint %}
You can set following CLI config flags when starting tardis-machine server installed via `npm`:
| name | default | description |
| ------------------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **--api-key** | | API key for [Tardis.dev](https://tardis.dev/) HTTP API - if not provided only first day of each month of historical data is accessible |
| **--port** | `8000` | HTTP port on which server will be running, **WebSocket port is always this value + 1** (`8001` with port set to `8000`) |
| **--cache-dir** | `/.tardis-cache` | path to local dir that will be used as cache location - if not provided default `temp` dir for given OS will be used |
| **--cluster-mode** | `false` | will launch [cluster of Node.js processes](https://nodejs.org/api/cluster.html) to handle the incoming requests if set to `true`, by default server runs in single process mode |
| **--debug** | `false` | server will print verbose debug logs to stdout if set to `true` |
| **--clear-cache** | `false` | server will clear local cache dir on startup is set to `true` |
| **--help** | | shows CLI help |
| **--version** | | shows tardis-machine version number |
## Examples
### Historical normalized replay
{% tabs %}
{% tab title="Python" %}
```python
import asyncio
import aiohttp
import json
import urllib.parse
async def replay_normalized(options):
encoded_options = urllib.parse.quote_plus(json.dumps(options))
url = f"http://localhost:8000/replay-normalized?options={encoded_options}"
async with aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=0)) as session:
async with session.get(url) as response:
async for line in response.content:
print(json.loads(line))
asyncio.run(
replay_normalized(
{
"exchange": "binance",
"from": "2024-03-01",
"to": "2024-03-02",
"symbols": ["btcusdt"],
"dataTypes": ["trade", "book_change"],
}
)
)
```
{% endtab %}
{% tab title="Node.js" %}
```javascript
import split2 from "split2";
import { Readable } from "stream";
const serialize = (options) => encodeURIComponent(JSON.stringify(options));
async function* replayNormalized(options) {
const url = `http://localhost:8000/replay-normalized?options=${serialize(options)}`;
const response = await fetch(url);
const lines = Readable.fromWeb(response.body).pipe(split2());
for await (const line of lines) {
yield JSON.parse(line);
}
}
const messages = replayNormalized({
exchange: "binance",
from: "2024-03-01",
to: "2024-03-02",
symbols: ["btcusdt"],
dataTypes: ["trade", "book_change"],
});
for await (const message of messages) {
console.log(message);
}
```
{% endtab %}
{% endtabs %}
{% content-ref url="/pages/2BAG1UWBJPCuk9zXug9y" %}
[Replaying Historical Data](/tardis-machine/replaying-historical-data)
{% endcontent-ref %}
### Real-time normalized streaming
{% tabs %}
{% tab title="Python" %}
```python
import asyncio
import aiohttp
import json
import urllib.parse
async def main():
stream_options = {
"exchange": "binance",
"symbols": ["btcusdt"],
"dataTypes": ["trade", "book_change"],
}
options = urllib.parse.quote_plus(json.dumps(stream_options))
url = f"ws://localhost:8001/ws-stream-normalized?options={options}"
async with aiohttp.ClientSession() as session:
async with session.ws_connect(url) as websocket:
async for message in websocket:
print(message.data)
asyncio.run(main())
```
{% endtab %}
{% tab title="Node.js" %}
```javascript
import WebSocket from "ws";
const options = encodeURIComponent(
JSON.stringify({
exchange: "binance",
symbols: ["btcusdt"],
dataTypes: ["trade", "book_change"],
}),
);
const ws = new WebSocket(
`ws://localhost:8001/ws-stream-normalized?options=${options}`,
);
ws.onmessage = (message) => {
console.log(message.data);
};
```
{% endtab %}
{% endtabs %}
{% content-ref url="/pages/IaFlsH1FFOKOxW2QHpgn" %}
[Streaming Real-Time Data](/tardis-machine/streaming-real-time-data)
{% endcontent-ref %}
# Replaying Historical Data
HTTP and WebSocket replay endpoints with options and response formats
HTTP and WebSocket endpoints for tick-by-tick historical market data replay in both exchange-native and normalized formats.
## Exchange-native market data APIs
Exchange-native market data API endpoints provide historical data in [exchange-native format](/faq/data#what-is-a-difference-between-exchange-native-and-normalized-data-format). The main difference between HTTP and WebSocket endpoints is the logic of requesting data:
* [HTTP API](#http-get-replay-options-options) accepts [request options](#replay-options) payload via query string param
* [WebSocket API](#websocket-ws-replay-exchange-exchange-and-from-fromdate-and-to-todate) accepts exchanges' specific 'subscribe' messages that define what data will be then "replayed" and send to WebSocket client
### `HTTP GET` /replay?options={options}
Returns historical market data messages in [exchange-native format](/faq/data#what-is-a-difference-between-exchange-native-and-normalized-data-format) for given replay options query string param. Single streaming HTTP response returns data for the whole requested time period as [NDJSON](http://ndjson.org/).
{% hint style="info" %}
In our preliminary benchmarks on AMD Ryzen 7 3700X, 64GB RAM, [HTTP /replay](#http-get-replay-options-options) API endpoint was returning \~700 000 messages/s (already locally cached data).
{% endhint %}
{% hint style="warning" %}
A single replay request can fan out into many upstream `/data-feeds` requests. Running multiple concurrent replay processes can quickly exceed [API rate limits](/api/rate-limits), causing stalls without visible error messages.
{% endhint %}
{% tabs %}
{% tab title="Python" %}
```python
import asyncio
import aiohttp
import json
import urllib.parse
async def replay_via_tardis_machine(replay_options):
timeout = aiohttp.ClientTimeout(total=0)
async with aiohttp.ClientSession(timeout=timeout) as session:
# url encode as json object options
encoded_options = urllib.parse.quote_plus(json.dumps(replay_options))
# assumes tardis-machine HTTP API running on localhost:8000
url = f"http://localhost:8000/replay?options={encoded_options}"
async with session.get(url) as response:
# otherwise we may get line to long errors
response.content._high_water = 100_000_000
# returned data is in NDJSON format http://ndjson.org/
# each line is separate message JSON encoded
async for line in response.content:
yield line
async def main():
lines = replay_via_tardis_machine(
{
"exchange": "binance",
"from": "2024-03-01",
"to": "2024-03-02",
"filters": [
{"channel": "trade", "symbols": ["btcusdt"]},
{"channel": "depth", "symbols": ["btcusdt"]},
],
}
)
async for line in lines:
message = json.loads(line)
# localTimestamp string marks timestamp when message was received
# message is a message dict as provided by exchange real-time stream
print(message["localTimestamp"], message["message"])
asyncio.run(main())
```
{% hint style="info" %}
See also official Tardis.dev [Python client](/python-client/quickstart) library.
{% endhint %}
{% endtab %}
{% tab title="Node.js" %}
```javascript
import split2 from 'split2'
import { Readable } from 'stream'
const serialize = options => {
return encodeURIComponent(JSON.stringify(options))
}
async function* replayViaTardisMachine(options) {
// assumes tardis-machine HTTP API running on localhost:8000
const url = `http://localhost:8000/replay?options=${serialize(options)}`
const response = await fetch(url)
// returned data is in NDJSON format http://ndjson.org/
// each line is separate message JSON encoded
// split response body stream by new lines
const lines = Readable.fromWeb(response.body).pipe(split2())
for await (const line of lines) {
yield line
}
}
const options = {
exchange: 'binance',
from: '2024-03-01',
to: '2024-03-02',
filters: [
{
channel: 'trade',
symbols: ['btcusdt']
},
{
channel: 'depth',
symbols: ['btcusdt']
}
]
}
const lines = replayViaTardisMachine(options)
for await (const line of lines) {
// localTimestamp string marks timestamp when message was received
// message is a message object as provided by exchange real-time stream
const { message, localTimestamp } = JSON.parse(line)
console.log(message, localTimestamp)
}
```
{% hint style="info" %}
See also official Tardis.dev [Node.js client](/node-client/quickstart) library.
{% endhint %}
{% endtab %}
{% tab title="cURL" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"binance","filters":[{"channel":"trade","symbols":["btcusdt"]},{"channel":"depth","symbols":["btcusdt"]}],"from":"2024-03-01","to":"2024-03-02"}'
```
{% embed url="" %}
Click to see API response in the browser as long as tardis-machine is running on localhost:8000
{% endembed %}
{% endtab %}
{% tab title="Your preferred language" %}
We're working on providing more samples and dedicated client libraries in different languages, but in the meanwhile to consume [HTTP /replay](#http-get-replay-options-options) API responses in your language of choice, you should:
1. Provide url encoded JSON [options object](#replay-options) via options query string param when sending HTTP request
2. Parse HTTP response stream line by line as it's returned - buffering in memory whole response may result in slow performance and memory overflows
3. Parse each response line as JSON containing messages in [exchange-native format](#response-format)
{% endtab %}
{% endtabs %}
#### Replay options
[HTTP /replay](#http-get-replay-options-options) endpoint accepts required options query string param in **url encoded JSON format**.
| name | type | default | description |
| ------------------------------- | ---------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **exchange** | string | - | requested exchange id - use [/exchanges HTTP API](/api/http-api-reference#exchanges) to get list of valid exchanges ids |
| **filters** | {channel:string, symbols?: string\[]}\[] | \[] | optional filters of requested historical data feed - check [historical data details](/historical-data-details/overview) for each exchange and [/exchanges/:exchange HTTP API](/api/http-api-reference#exchanges-exchange) to get allowed channels and symbols for requested exchange |
| **from** | string | - | replay period start date (UTC) in a [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format, e.g., `2019-04-01` |
| **to** | string | - | replay period end date (UTC) in a [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format, e.g., `2019-04-02` |
| **withDisconnects** | boolean (optional) | undefined | when set to `true`, response includes empty lines (`\n`) that mark events when real-time WebSocket connection that was used to collect the historical data got disconnected |
| **waitWhenDataNotYetAvailable** | boolean or number (optional) | undefined | when set to `true`, waits for data that is not yet available — useful when replaying near real-time data. Defaults to a 30-minute offset. When set to a number, specifies the offset in minutes (minimum effective value is 6 minutes). |
| **autoCleanup** | boolean (optional) | undefined | when set to `true`, automatically removes cached data from disk after it has been processed. Not safe for concurrent replay — see [warning](#replay-options) |
| **withMicroseconds** | boolean (optional) | undefined | when set to `true`, `localTimestamp` in response is returned with microsecond precision |
When `symbols` array is empty or omitted in filters, data for all active symbols is returned.
{% hint style="info" %}
**Disconnect markers**: An empty line in raw replay (or a `disconnect` message in normalized replay) indicates that the WebSocket connection used during data collection was interrupted. After a reconnect, exchanges typically re-send initial snapshots, so duplicate snapshot messages are expected following a disconnect marker. Disconnect markers apply to the entire connection, not individual channels.
{% endhint %}
{% hint style="warning" %}
**`autoCleanup` concurrency**: avoid using `autoCleanup` with concurrent replay — the cache path is keyed by exchange, a hash of the filters, and the calendar day, so any concurrent jobs sharing those three components will conflict (even with non-overlapping time windows within the same day) and cause file-not-found errors. Clean the cache manually after all jobs complete instead.
{% endhint %}
#### **Response format**
Streamed HTTP response provides data in NDJSON format (new line delimited JSON) - each response line is a JSON with market data message in [exchange-native format](/faq/data#what-is-a-difference-between-exchange-native-and-normalized-data-format) plus local timestamp:
* `localTimestamp` - date when message has been received in ISO 8601 format
* `message` - JSON with exactly the same format as provided by requested exchange real-time feeds
**Sample response**
```javascript
{"localTimestamp":"2024-03-01T00:00:00.001409Z","message":{"stream":"btcusdt@trade","data":{"e":"trade","E":1709251199998,"s":"BTCUSDT","t":3445374963,"p":"61130.98000000","q":"0.00145000","b":25230662315,"a":25230662808,"T":1709251199998,"m":true,"M":true}}}
{"localTimestamp":"2024-03-01T00:00:00.001417Z","message":{"stream":"btcusdt@trade","data":{"e":"trade","E":1709251199999,"s":"BTCUSDT","t":3445374964,"p":"61130.98000000","q":"0.00182000","b":25230662315,"a":25230662809,"T":1709251199998,"m":true,"M":true}}}
{"localTimestamp":"2024-03-01T00:00:00.001423Z","message":{"stream":"btcusdt@trade","data":{"e":"trade","E":1709251199999,"s":"BTCUSDT","t":3445374965,"p":"61130.98000000","q":"0.00034000","b":25230662315,"a":25230662810,"T":1709251199998,"m":true,"M":true}}}
{"localTimestamp":"2024-03-01T00:00:00.001429Z","message":{"stream":"btcusdt@trade","data":{"e":"trade","E":1709251200000,"s":"BTCUSDT","t":3445374966,"p":"61130.98000000","q":"0.00182000","b":25230662315,"a":25230662811,"T":1709251199999,"m":true,"M":true}}}
{"localTimestamp":"2024-03-01T00:00:00.006791Z","message":{"stream":"btcusdt@trade","data":{"e":"trade","E":1709251200000,"s":"BTCUSDT","t":3445374967,"p":"61130.98000000","q":"0.00038000","b":25230662315,"a":25230662812,"T":1709251199999,"m":true,"M":true}}}
```
### `WebSocket` /ws-replay?exchange={exchange}\&from={fromDate}\&to={toDate}
Exchanges' WebSocket APIs are designed to publish real-time market data feeds, not historical ones. Tardis-machine [WebSocket /ws-replay](#websocket-ws-replay-exchange-exchange-and-from-fromdate-and-to-todate) API fills that gap and allows "replaying" historical market data from any given past point in time with the same data format and 'subscribe' logic as real-time exchanges' APIs. In many cases existing exchanges' WebSocket clients can be used to connect to this endpoint just by changing URL, and receive historical market data in [exchange-native](/faq/data#what-is-a-difference-between-exchange-native-and-normalized-data-format) format for date ranges specified in URL query string params.
After connection is established, client has 2 seconds to send subscriptions payloads and then market data replay starts.
If two clients connect at the same time requesting data for different exchanges and provide the same [session key via query string param](#query-string-params), then data being send to those clients will be synchronized (by local timestamp).
{% hint style="info" %}
In our preliminary benchmarks on AMD Ryzen 7 3700X, 64GB RAM, [WebSocket /ws-replay](#websocket-ws-replay-exchange-exchange-and-from-fromdate-and-to-todate) API endpoint was sending \~500 000 messages/s (already locally cached data).
{% endhint %}
{% tabs %}
{% tab title="Python" %}
```python
import asyncio
import aiohttp
import json
async def main():
WS_REPLAY_URL = "ws://localhost:8001/ws-replay"
URL = f"{WS_REPLAY_URL}?exchange=binance&from=2024-03-01&to=2024-03-02"
async with aiohttp.ClientSession() as session:
async with session.ws_connect(URL) as websocket:
await websocket.send_str(
json.dumps(
{
"method": "SUBSCRIBE",
"params": ["btcusdt@trade", "btcusdt@depth@100ms"],
"id": 1,
}
)
)
async for msg in websocket:
print(msg.data)
asyncio.run(main())
```
{% hint style="info" %}
You can also try using existing WebSocket client by changing URL endpoint to the one shown in the example above.
{% endhint %}
{% endtab %}
{% tab title="Node.js" %}
```javascript
import WebSocket from 'ws'
const WS_REPLAY_URL = 'ws://localhost:8001/ws-replay'
const ws = new WebSocket(
`${WS_REPLAY_URL}?exchange=binance&from=2024-03-01&to=2024-03-02`
)
ws.onmessage = message => {
console.log(message.data)
}
ws.onopen = () => {
ws.send(
JSON.stringify({
method: 'SUBSCRIBE',
params: ['btcusdt@trade', 'btcusdt@depth@100ms'],
id: 1
})
)
}
```
{% hint style="info" %}
You can also use existing WebSocket client by changing URL endpoint to the one shown in the example above.
{% endhint %}
{% endtab %}
{% tab title="Your preferred language" %}
As long as you already use existing WebSocket client that connects to and consumes real-time exchange market data feed, in most cases you can use it to connect to [/ws-replay](#websocket-ws-replay-exchange-exchange-and-from-fromdate-and-to-todate) API as well just by changing URL endpoint.
{% endtab %}
{% endtabs %}
#### **Query string params**
| name | type | default | description |
| ------------ | ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **exchange** | string | - | requested exchange id - use [/exchanges HTTP API](/api/http-api-reference#exchanges) to get list of valid exchanges ids |
| **from** | string | - | replay period start date (UTC) in a [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format, e.g., `2019-04-01` |
| **to** | string | - | replay period end date (UTC) in a [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format, e.g., `2019-04-02` |
| **session** | string (optional) | undefined | optional replay session key. When specified and multiple clients use it when connecting at the same time then data being send to those clients is synchronized (by local timestamp). |
## Normalized market data APIs
Normalized market data API endpoints provide data in [unified format](/tardis-machine/data-types) across all supported exchanges. Both [HTTP /replay-normalized](#http-get-replay-normalized-options-options) and [WebSocket /ws-replay-normalized](#websocket-ws-replay-normalized-options-options) APIs accept the same replay options payload via query string param. It's mostly a matter of preference when choosing which protocol to use, but [WebSocket /ws-replay-normalized API](#websocket-ws-replay-normalized-options-options) also has its real-time counterpart [/ws-stream-normalized](/tardis-machine/streaming-real-time-data#websocket-ws-stream-normalized-options-options), which connects directly to exchanges' real-time WebSocket APIs. This opens the **possibility of seamless switching between real-time streaming and historical normalized market data replay**.
### `HTTP GET` /replay-normalized?options={options}
Returns historical market data for [data types](#replay-normalized-options) specified via query string. Single streaming HTTP response returns data for the whole requested time period as [NDJSON](http://ndjson.org/). See [supported data types](/tardis-machine/data-types) which include normalized [trade](/tardis-machine/data-types#trade), [order book change](/tardis-machine/data-types#book_change), [customizable order book snapshots](/tardis-machine/data-types#book_snapshot_-number_of_levels-_-snapshot_interval-time_unit) etc.
{% hint style="info" %}
In our preliminary benchmarks on AMD Ryzen 7 3700X, 64GB RAM, [HTTP /replay-normalized](#http-get-replay-normalized-options-options) API endpoint was returning \~100 000 messages/s and \~50 000 messages/s when order book snapshots were also requested.
{% endhint %}
{% tabs %}
{% tab title="Python" %}
```python
import asyncio
import aiohttp
import json
import urllib.parse
async def replay_normalized_via_tardis_machine(replay_options):
timeout = aiohttp.ClientTimeout(total=0)
async with aiohttp.ClientSession(timeout=timeout) as session:
# url encode as json object options
encoded_options = urllib.parse.quote_plus(json.dumps(replay_options))
# assumes tardis-machine HTTP API running on localhost:8000
url = f"http://localhost:8000/replay-normalized?options={encoded_options}"
async with session.get(url) as response:
# otherwise we may get line to long errors
response.content._high_water = 100_000_000
# returned data is in NDJSON format http://ndjson.org/ streamed
# each line is separate message JSON encoded
async for line in response.content:
yield line
async def main():
lines = replay_normalized_via_tardis_machine(
{
"exchange": "binance",
"from": "2024-03-01",
"to": "2024-03-02",
"symbols": ["btcusdt"],
"withDisconnectMessages": True,
# other available data types examples:
# 'book_snapshot_10_100ms', 'derivative_ticker', 'quote',
# 'trade_bar_10ms', 'trade_bar_10s'
"dataTypes": ["trade", "book_change", "book_snapshot_10_100ms"],
}
)
async for line in lines:
normalized_message = json.loads(line)
print(normalized_message)
asyncio.run(main())
```
{% endtab %}
{% tab title="Node.js" %}
```javascript
import split2 from 'split2'
import { Readable } from 'stream'
const serialize = options => {
return encodeURIComponent(JSON.stringify(options))
}
async function* replayNormalizedViaTardisMachine(options) {
// assumes tardis-machine HTTP API running on localhost:8000
const url = `http://localhost:8000/replay-normalized?options=${serialize(
options
)}`
const response = await fetch(url)
// returned data is in NDJSON format http://ndjson.org/
// each line is separate message JSON encoded
// split response body stream by new lines
const lines = Readable.fromWeb(response.body).pipe(split2())
for await (const line of lines) {
yield line
}
}
const options = {
exchange: 'binance',
from: '2024-03-01',
to: '2024-03-02',
symbols: ['btcusdt'],
withDisconnectMessages: true,
// other available data types examples:
// 'book_snapshot_10_100ms', 'derivative_ticker', 'quote',
// 'trade_bar_10ms', 'trade_bar_10s'
dataTypes: ['trade', 'book_change', 'book_snapshot_10_100ms']
}
const lines = replayNormalizedViaTardisMachine(options)
for await (const line of lines) {
const normalizedMessage = JSON.parse(line)
console.log(normalizedMessage)
}
```
{% hint style="info" %}
See also official Tardis.dev [Node.js client](/node-client/quickstart) library.
{% endhint %}
{% endtab %}
{% tab title="cURL" %}
```bash
curl -g 'http://localhost:8000/replay-normalized?options={"exchange":"binance","from":"2024-03-01","to":"2024-03-02","symbols":["btcusdt"],"withDisconnectMessages":true,"dataTypes":["trade","book_change","book_snapshot_10_100ms"]}'
```
{% embed url="" %}
Click to see API response in the browser as long as tardis-machine is running on localhost:8000
{% endembed %}
{% endtab %}
{% tab title="Your preferred language" %}
We're working on providing more samples and dedicated client libraries in different languages, but in the meanwhile to consume [HTTP /replay-normalized](#http-get-replay-normalized-options-options) API responses in your language of choice, you should:
1. Provide URL-encoded JSON [options](#replay-normalized-options) via the options query string parameter when sending an HTTP request
2. Parse HTTP response stream line by line as it's returned - buffering in memory whole response may result in slow performance and memory overflows
3. Parse each response line as JSON containing [normalized data messages](/tardis-machine/data-types).
{% endtab %}
{% endtabs %}
#### Replay normalized options
[HTTP /replay-normalized](#http-get-replay-normalized-options-options) endpoint accepts required options query string param in **url encoded JSON format**.
Options JSON needs to be an object or an array of objects with fields as specified below. If array is provided, then data requested for multiple exchanges is returned synchronized (by local timestamp).
**Synchronized multi-exchange example**
The same `options` array format works for both [`HTTP /replay-normalized`](#http-get-replay-normalized-options-options) and [`WebSocket /ws-replay-normalized`](#websocket-ws-replay-normalized-options-options). For example, to replay synchronized normalized trades from Binance and OKX for the same symbol and time range:
```bash
curl -g 'http://localhost:8000/replay-normalized?options=[{"exchange":"binance","from":"2024-03-01","to":"2024-03-02","symbols":["btcusdt"],"dataTypes":["trade"]},{"exchange":"okex","from":"2024-03-01","to":"2024-03-02","symbols":["btcusdt"],"dataTypes":["trade"]}]'
```
Each response line is still a single normalized message, but messages from both exchanges are merged into one stream and ordered by `localTimestamp`.
| name | type | default | description |
| ------------------------------- | ---------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **exchange** | string | - | requested exchange id - use [/exchanges HTTP API](/api/http-api-reference#exchanges) to get list of valid exchanges ids |
| **symbols** | string\[] (optional) | undefined | optional symbols of requested historical data feed - use [/exchanges/:exchange HTTP API](/api/http-api-reference#exchanges-exchange) to get allowed symbols for requested exchange |
| **from** | string | - | replay period start date (UTC) in a [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format, e.g., `2019-04-01` |
| **to** | string | - | replay period end date (UTC) in a [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format, e.g., `2019-04-02` |
| **dataTypes** | string\[] | - | array of normalized [data types](/tardis-machine/data-types) for which historical data will be returned |
| **withDisconnectMessages** | boolean (optional) | undefined | when set to `true`, response includes [disconnect](/tardis-machine/data-types#disconnect) messages that mark events when real-time WebSocket connection that was used to collect the historical data got disconnected |
| **waitWhenDataNotYetAvailable** | boolean or number (optional) | undefined | when set to `true`, waits for data that is not yet available — useful when replaying near real-time data. Defaults to a 30-minute offset. When set to a number, specifies the offset in minutes (minimum effective value is 6 minutes). |
| **autoCleanup** | boolean (optional) | undefined | when set to `true`, automatically removes cached data from disk after it has been processed. Not safe for concurrent replay — see [warning](#replay-options) |
#### **Response format & sample messages**
See [Output Data Types](/tardis-machine/data-types).
### `WebSocket` /ws-replay-normalized?options={options}
Sends [normalized](/tardis-machine/data-types) historical market data for [data types](#replay-normalized-options-1) specified via query string. See [supported data types](/tardis-machine/data-types) which include normalized [trade](/tardis-machine/data-types#trade), [order book change](/tardis-machine/data-types#book_change), [customizable order book snapshots](/tardis-machine/data-types#book_snapshot_-number_of_levels-_-snapshot_interval-time_unit) etc.
{% hint style="info" %}
[WebSocket /ws-stream-normalized](/tardis-machine/streaming-real-time-data#websocket-ws-stream-normalized-options-options) is the real-time counterpart of this API endpoint, providing real-time market data in the same format, but not requiring API key as connects directly to exchanges' real-time WebSocket APIs.
{% endhint %}
{% tabs %}
{% tab title="Python" %}
```python
import asyncio
import aiohttp
import json
import urllib.parse
async def main():
replay_options = {
"exchange": "binance",
"from": "2024-03-01",
"to": "2024-03-02",
"symbols": ["btcusdt"],
"withDisconnectMessages": True,
# other available data types examples:
# 'book_snapshot_10_100ms', 'derivative_ticker', 'quote',
# 'trade_bar_10ms', 'trade_bar_10s'
"dataTypes": ["trade", "book_change", "book_snapshot_10_100ms"],
}
options = urllib.parse.quote_plus(json.dumps(replay_options))
URL = f"ws://localhost:8001/ws-replay-normalized?options={options}"
async with aiohttp.ClientSession() as session:
async with session.ws_connect(URL) as websocket:
async for msg in websocket:
print(msg.data)
asyncio.run(main())
```
{% endtab %}
{% tab title="Node.js" %}
```javascript
import WebSocket from 'ws'
const serialize = options => {
return encodeURIComponent(JSON.stringify(options))
}
const replayOptions = {
exchange: 'binance',
from: '2024-03-01',
to: '2024-03-02',
symbols: ['btcusdt'],
withDisconnectMessages: true,
// other available data types examples:
// 'book_snapshot_10_100ms', 'derivative_ticker', 'quote',
// 'trade_bar_10ms', 'trade_bar_10s'
dataTypes: ['trade', 'book_change', 'book_snapshot_10_100ms']
}
const options = serialize(replayOptions)
const URL = `ws://localhost:8001/ws-replay-normalized?options=${options}`
const ws = new WebSocket(URL)
ws.onmessage = message => {
console.log(message.data)
}
```
{% hint style="info" %}
See also official Tardis.dev [Node.js client](/node-client/quickstart) library.
{% endhint %}
{% endtab %}
{% tab title="Your preferred language" %}
We're working on providing more samples and dedicated client libraries in different languages, but in the meanwhile to consume [WebSocket /ws-replay-normalized](#websocket-ws-replay-normalized-options-options) API responses in your language of choice, you should:
1. Provide url encoded JSON [options](#replay-normalized-options-1) via options query string param when connecting to
[WebSocket /ws-replay-normalized](#websocket-ws-replay-normalized-options-options) endpoint
2. Parse each received WebSocket message as JSON containing [normalized data](/tardis-machine/data-types).
{% endtab %}
{% endtabs %}
#### Replay normalized options
[WebSocket /ws-replay-normalized](#websocket-ws-replay-normalized-options-options) endpoint accepts required options query string param in **url encoded JSON format**.
Options JSON needs to be an object or an array of objects with fields as specified below. If array is provided, then data requested for multiple exchanges is sent synchronized (by local timestamp). See the [multi-exchange example above](#replay-normalized-options).
| name | type | default | description |
| ------------------------------- | ---------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **exchange** | string | - | requested exchange id - use [/exchanges HTTP API](/api/http-api-reference#exchanges) to get list of valid exchanges ids |
| **symbols** | string\[] (optional) | undefined | optional symbols of requested historical data feed - use [/exchanges/:exchange HTTP API](/api/http-api-reference#exchanges-exchange) to get allowed symbols for requested exchange |
| **from** | string | - | replay period start date (UTC) in a [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format, e.g., `2019-04-01` |
| **to** | string | - | replay period end date (UTC) in a [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format, e.g., `2019-04-02` |
| **dataTypes** | string\[] | - | array of normalized [data types](/tardis-machine/data-types) for which historical data will be provided |
| **withDisconnectMessages** | boolean (optional) | undefined | when set to `true`, sends also [disconnect](/tardis-machine/data-types#disconnect) messages that mark events when real-time WebSocket connection that was used to collect the historical data got disconnected |
| **waitWhenDataNotYetAvailable** | boolean or number (optional) | undefined | when set to `true`, waits for data that is not yet available — useful when replaying near real-time data. Defaults to a 30-minute offset. When set to a number, specifies the offset in minutes (minimum effective value is 6 minutes). |
| **autoCleanup** | boolean (optional) | undefined | when set to `true`, automatically removes cached data from disk after it has been processed. Not safe for concurrent replay — see [warning](#replay-options) |
{% hint style="info" %}
In our preliminary benchmarks on AMD Ryzen 7 3700X, 64GB RAM, [WebSocket /ws-replay-normalized](#websocket-ws-replay-normalized-options-options) API endpoint was returning \~70 000 messages/s and \~40 000 messages/s when order book snapshots were also requested.
{% endhint %}
#### **Response format & sample messages**
See [Output Data Types](/tardis-machine/data-types).
# Streaming Real-Time Data
WebSocket endpoint for consolidated real-time normalized market data streaming
## `WebSocket` /ws-stream-normalized?options={options}
Sends [normalized](/tardis-machine/data-types) real-time market data for [data types](#stream-normalized-options) specified via query string. See [supported data types](/tardis-machine/data-types) which include normalized [trade](/tardis-machine/data-types#trade), [order book change](/tardis-machine/data-types#book_change), [customizable order book snapshots](/tardis-machine/data-types#book_snapshot_-number_of_levels-_-snapshot_interval-time_unit) etc.
**Doesn't require an API key, as it connects directly to exchanges' real-time WebSocket APIs** and transparently restarts closed, broken, or stale connections (open connections without data being sent for a specified amount of time).
Provides **consolidated real-time market data streaming** functionality with [options](#stream-normalized-options) as an array - provides single consolidated real-time data stream for all exchanges specified in [options array](#stream-normalized-options).
{% hint style="info" %}
[WebSocket /ws-replay-normalized](/tardis-machine/replaying-historical-data#websocket-ws-replay-normalized-options-options) is the historical counterpart of this API endpoint, providing historical market data in the same format.
{% endhint %}
{% hint style="info" %}
Tardis-machine provides real-time streaming only for [normalized data types](/tardis-machine/data-types). If you need real-time data in exchange-native format, connect directly to the exchange's WebSocket API.
{% endhint %}
{% tabs %}
{% tab title="Python" %}
```python
import asyncio
import aiohttp
import json
import urllib.parse
async def main():
data_types = ["trade", "book_change", "book_snapshot_10_100ms"]
stream_options = [
{
"exchange": "binance",
"symbols": ["btcusdt"],
"dataTypes": data_types,
},
{
"exchange": "binance-futures",
"symbols": ["BTCUSDT"],
"dataTypes": data_types,
},
]
options = urllib.parse.quote_plus(json.dumps(stream_options))
URL = f"ws://localhost:8001/ws-stream-normalized?options={options}"
# real-time normalized data for two exchanges via single connection
async with aiohttp.ClientSession() as session:
async with session.ws_connect(URL) as websocket:
async for msg in websocket:
print(msg.data)
asyncio.run(main())
```
{% endtab %}
{% tab title="Node.js" %}
```javascript
import WebSocket from 'ws'
const serialize = options => {
return encodeURIComponent(JSON.stringify(options))
}
// other available data types examples:
// 'book_snapshot_10_100ms', 'derivative_ticker', 'quote',
// 'trade_bar_10ms', 'trade_bar_10s'
const dataTypes = ['trade', 'book_change', 'book_snapshot_10_100ms']
const streamOptions = [
{
exchange: 'binance',
symbols: ['btcusdt'],
dataTypes
},
{
exchange: 'binance-futures',
symbols: ['BTCUSDT'],
dataTypes
}
]
const options = serialize(streamOptions)
const URL = `ws://localhost:8001/ws-stream-normalized?options=${options}`
const ws = new WebSocket(URL)
// real-time normalized data for two exchanges via single connection
ws.onmessage = message => {
console.log(message.data)
}
```
{% hint style="info" %}
See also official Tardis.dev [Node.js client](/node-client/quickstart) library.
{% endhint %}
{% endtab %}
{% tab title="Your preferred language" %}
We're working on providing more samples and dedicated client libraries in different languages, but in the meanwhile to consume [WebSocket /ws-stream-normalized](#websocket-ws-stream-normalized-options-options) API responses in your language of choice, you should:
1. Provide url encoded JSON [options](#stream-normalized-options) via options query string param when connecting to
[WebSocket /ws-stream-normalized](#websocket-ws-stream-normalized-options-options) endpoint
2. Parse each received WebSocket message as JSON containing [normalized data](/tardis-machine/data-types).
{% endtab %}
{% endtabs %}
#### Stream normalized options
[WebSocket /ws-stream-normalized](#websocket-ws-stream-normalized-options-options) endpoint accepts required options query string param in **url encoded JSON format**.
Options JSON needs to be an object or an array of objects with fields as specified below. If array is specified then API provides single consolidated real-time data stream for all exchanges specified (as in examples above).
| name | type | default | description |
| -------------------------- | -------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **exchange** | string | - | requested exchange id - use [/exchanges HTTP API](/api/http-api-reference#exchanges) to get list of valid exchanges ids |
| **symbols** | string\[] (optional) | undefined | optional symbols of requested real-time data feed |
| **dataTypes** | string\[] | - | array of normalized [data types](/tardis-machine/data-types) for which real-time data will be provided |
| **withDisconnectMessages** | boolean (optional) | undefined | when set to `true`, sends [disconnect](/tardis-machine/data-types#disconnect) messages anytime underlying exchange real-time WebSocket connection(s) gets disconnected |
| **timeoutIntervalMS** | number | 10000 | specifies time in milliseconds after which connection to real-time exchanges' WebSocket API is restarted if no message has been received |
| **withErrorMessages** | boolean (optional) | undefined | when set to `true`, sends `error` messages whenever an underlying exchange WebSocket connection error occurs. Error message format: `{"type":"error","exchange":"...","localTimestamp":"...","details":"...","subSequentErrorsCount":1}` |
{% hint style="info" %}
**Tips:**
* For sparse instruments (e.g., illiquid options), increase `timeoutIntervalMS` (e.g., `60000`) to prevent unnecessary connection restarts when no messages arrive for extended periods. This is especially important for `trade_bar_*` data types on low-volume symbols.
* When providing `options` as an array, each element creates a separate WebSocket connection to the target exchange. This can be used for multi-exchange streaming, but also for the same exchange — for example, to work around per-connection limits on the number of symbols or channels.
{% endhint %}
#### **Response format & sample messages**
See [Output Data Types](/tardis-machine/data-types).
# Data Types
Normalized schemas for trade, book\_change, book\_snapshot and more
Schema reference for normalized data types returned by tardis-machine replay and streaming APIs.
* [trade](#trade)
* [book\_change](#book_change)
* [book\_ticker](#book_ticker)
* [derivative\_ticker](#derivative_ticker)
* [quote\_{snapshot\_interval}{time\_unit}](#book_snapshot_-number_of_levels-_-snapshot_interval-time_unit)
* [book\_snapshot\_{number\_of\_levels}\_{snapshot\_interval}{time\_unit}](#book_snapshot_-number_of_levels-_-snapshot_interval-time_unit)
* [trade\_bar\_{aggregation\_interval}{suffix}](#trade_bar_-aggregation_interval-suffix)
* [liquidation](#liquidation)
* [option\_summary](#option_summary)
* [disconnect](#disconnect)
* [error](#error)
### trade
Individual trade
{% tabs %}
{% tab title="sample message" %}
```javascript
{
"type": "trade",
"symbol": "BTCUSDT",
"exchange": "binance",
"id": "3445374963",
"price": 61130.98,
"amount": 0.00145,
"side": "sell",
"timestamp": "2024-02-29T23:59:59.998Z",
"localTimestamp": "2024-03-01T00:00:00.001Z"
}
```
{% endtab %}
{% tab title="schema" %}
```typescript
{
type: 'trade'
symbol: string // instrument symbol as provided by exchange
exchange: string // exchange id
id: string | undefined // trade id if provided by exchange
price: number // trade price as provided by exchange
amount: number // trade amount as provided by exchange
side: 'buy' | 'sell' | 'unknown' // liquidity taker side (aggressor)
timestamp: string // trade timestamp provided by exchange (ISO 8601 format)
localTimestamp: string // message arrival timestamp (ISO 8601 format)
}
```
{% endtab %}
{% endtabs %}
### book\_change
Initial [L2 (market by price)](/faq/order-books#what-l2-order-book-data-can-be-used-for) order book snapshot (`isSnapshot=true`) plus incremental updates for each order book change. Please note that `amount` is the updated amount at that price level, not a delta. An `amount` of `0` indicates the price level can be removed.
{% tabs %}
{% tab title="sample message" %}
```javascript
{
"type": "book_change",
"symbol": "BTCUSDT",
"exchange": "binance",
"isSnapshot": false,
"bids": [
{
"price": 61141.09,
"amount": 2.02515
}
],
"asks": [
{
"price": 61141.1,
"amount": 4.09368
}
],
"timestamp": "2024-03-01T00:00:01.489Z",
"localTimestamp": "2024-03-01T00:00:01.491Z"
}
```
{% endtab %}
{% tab title="schema" %}
```typescript
{
type: 'book_change'
symbol: string // instrument symbol as provided by exchange
exchange: string // exchange id
isSnapshot: boolean // if true marks initial order book snapshot
bids: { price: number; amount: number }[] // updated bids price-amount levels
asks: { price: number; amount: number }[] // updated asks price-amount levels
timestamp: string // order book update timestamp if provided by exchange,
// otherwise equals to localTimestamp, (ISO 8601 format)
localTimestamp: string // message arrival timestamp (ISO 8601 format)
}
```
{% endtab %}
{% endtabs %}
When processing `book_change` updates: an `amount` of `0` means remove that price level. If you receive a removal for a price level not in your local book, ignore it. Snapshot levels may include zero-amount entries — these should also be treated as absent levels.
### book\_ticker
Top of the book (best bid/ask) data from exchanges' native best bid/offer channels (e.g., Binance `bookTicker`, Bybit `orderbook.1`). Unlike [`quote`](#book_snapshot_-number_of_levels-_-snapshot_interval-time_unit) which is derived from L2 order book data, `book_ticker` is sourced from the native exchange-provided WebSocket best bid/offer feed.
Because it is a standalone feed, `book_ticker` replay can start from any point in time, whereas `quote` requires starting from 00:00 UTC (when the initial L2 order book snapshot is provided).
{% tabs %}
{% tab title="sample message" %}
```javascript
{
"type": "book_ticker",
"symbol": "BTCUSDT",
"exchange": "binance-futures",
"askPrice": 63125.5,
"askAmount": 2.5,
"bidPrice": 63125.4,
"bidAmount": 1.8,
"timestamp": "2024-01-15T10:30:00.123Z",
"localTimestamp": "2024-01-15T10:30:00.234Z"
}
```
{% endtab %}
{% tab title="schema" %}
```typescript
{
type: 'book_ticker'
symbol: string // instrument symbol as provided by exchange
exchange: string // exchange id
askPrice: number | undefined // best ask price, undefined if there aren't any asks
askAmount: number | undefined // best ask amount, undefined if there aren't any asks
bidPrice: number | undefined // best bid price, undefined if there aren't any bids
bidAmount: number | undefined // best bid amount, undefined if there aren't any bids
timestamp: string // message timestamp provided by exchange (ISO 8601 format)
localTimestamp: string // message arrival timestamp (ISO 8601 format)
}
```
{% endtab %}
{% endtabs %}
### derivative\_ticker
Derivative instrument ticker info sourced from real-time ticker & instrument channels.
Funding fields describe upcoming funding events relative to the message timestamp. `fundingTimestamp` is the next funding event time: the immediately upcoming event, not a previously settled funding time. `fundingRate` is the rate for that next event and can change until the event occurs. `predictedFundingRate`, when present, estimates the following funding event.
{% tabs %}
{% tab title="sample message" %}
```javascript
{
"type": "derivative_ticker",
"symbol": "BTCUSDT",
"exchange": "binance-futures",
"lastPrice": 61131.0,
"openInterest": 1458236000,
"fundingRate": 0.0001,
"fundingTimestamp": "2024-03-01T08:00:00.000Z",
"predictedFundingRate": 0.00009,
"indexPrice": 61130.9,
"markPrice": 61131.1,
"timestamp": "2024-03-01T00:00:00.250Z",
"localTimestamp": "2024-03-01T00:00:00.251Z"
}
```
{% endtab %}
{% tab title="schema" %}
```typescript
{
type: 'derivative_ticker'
symbol: string // instrument symbol as provided by exchange
exchange: string // exchange id
lastPrice: number | undefined // last instrument price if provided by exchange
openInterest: number | undefined // last open interest if provided by exchange
fundingRate: number | undefined // funding rate for the next funding event if provided by exchange
indexPrice: number | undefined // last index price if provided by exchange
markPrice: number | undefined // last mark price if provided by exchange
fundingTimestamp: string | undefined // next funding event timestamp if provided by exchange (ISO 8601 format)
predictedFundingRate: number | undefined // estimated funding rate for the following funding event if provided by exchange
timestamp: string // message timestamp provided by exchange (ISO 8601 format)
localTimestamp: string // message arrival timestamp (ISO 8601 format)
}
```
{% endtab %}
{% endtabs %}
### book\_snapshot\_{number\_of\_levels}\_{snapshot\_interval}{time\_unit}
Order book snapshot for selected `number_of_levels` (top bids and asks), `snapshot_interval` and [`time_unit`](#available-time-units). When `snapshot_interval` is set to `0`, snapshots are taken anytime order book state within specified levels has changed, otherwise snapshots are taken anytime `snapshot_interval` time has passed and there was an order book state change within specified levels. Order book snapshots are computed from exchanges' real-time order book streaming [L2 data (market by price)](/faq/order-books#what-l2-order-book-data-can-be-used-for).
#### Examples:
* `book_snapshot_10_0ms` - provides top 10 levels tick-by-tick order book snapshots
* `book_snapshot_50_100ms` - provides top 50 levels order book snapshots taken at 100 millisecond intervals
* `book_snapshot_10_grouped100_100ms` - provides top 10 levels order book snapshots grouped into price buckets of `100` and taken at 100 millisecond intervals
* `book_snapshot_30_10s` - provides top 30 levels order book snapshots taken at 10 second intervals
* `quote` - provides top of the book (best bid/ask) tick-by-tick order book snapshots (equivalent to depth 1, interval 0). Returned messages have `type: "book_snapshot"` and `name: "quote"`
* `quote_10s` - provides top of the book (best bid/ask) order book snapshots taken at 10 second intervals. Returned messages have `type: "book_snapshot"` and `name: "quote_10s"`
When grouped snapshots are requested, use `book_snapshot_{depth}_grouped{grouping}_{interval}{time_unit}`. The `grouping` field in the response then contains the requested grouping value.
#### Available time units:
* `ms` - milliseconds
* `s` - seconds
* `m` - minutes
{% tabs %}
{% tab title="sample message" %}
```javascript
{
"type": "book_snapshot",
"symbol": "BTCUSDT",
"exchange": "binance-futures",
"name": "book_snapshot_2_50ms",
"depth": 2,
"interval": 50,
"bids": [
{
"price": 61141.09,
"amount": 2.02515
},
{
"price": 61141.08,
"amount": 0.55321
}
],
"asks": [
{
"price": 61141.1,
"amount": 4.09368
},
{
"price": 61141.11,
"amount": 1.20457
}
],
"timestamp": "2024-03-01T00:00:01.450Z",
"localTimestamp": "2024-03-01T00:00:01.491Z"
}
```
{% endtab %}
{% tab title="schema" %}
```typescript
{
type: 'book_snapshot'
symbol: string // instrument symbol as provided by exchange
exchange: string // exchange id
name: string // name with format book_snapshot_{depth}_{interval}{time_unit}
// or book_snapshot_{depth}_grouped{grouping}_{interval}{time_unit}
depth: number // requested number of levels (top bids/asks)
interval: number // requested snapshot interval in milliseconds
bids: { price: number | undefined; amount: number | undefined }[] // top "depth" bids price-amount levels
asks: { price: number | undefined; amount: number | undefined }[] // top "depth" asks price-amount levels
grouping: number | undefined // present for grouped snapshots
timestamp: string // snapshot timestamp based on last book_change message
// processed timestamp adjusted to snapshot interval
localTimestamp: string // message arrival timestamp
// that triggered snapshot (ISO 8601 format)
}
```
{% endtab %}
{% endtabs %}
### liquidation
Liquidation events sourced from exchange-native liquidation feeds. Available for exchanges that publish liquidation data (e.g., Binance `forceOrder`, Bybit `allLiquidation`, OKX `liquidation-orders`). See [which exchanges support liquidations](/faq/data#which-exchanges-support-liquidations-data-type).
{% tabs %}
{% tab title="sample message" %}
```javascript
{
"type": "liquidation",
"symbol": "BTCUSDT",
"exchange": "binance-futures",
"id": "1709251200123",
"price": 61120.5,
"amount": 12.5,
"side": "sell",
"timestamp": "2024-03-01T00:00:00.123Z",
"localTimestamp": "2024-03-01T00:00:00.234Z"
}
```
{% endtab %}
{% tab title="schema" %}
```typescript
{
type: 'liquidation'
symbol: string // instrument symbol as provided by exchange
exchange: string // exchange id
id: string | undefined // liquidation id if provided by exchange
price: number // liquidation price
amount: number // liquidation amount
side: 'buy' | 'sell' | 'unknown' // liquidation side: buy means short liquidation, sell means long liquidation
timestamp: string // message timestamp provided by exchange (ISO 8601 format); some exchanges do not provide a separate liquidation timestamp, in which case this equals localTimestamp
localTimestamp: string // message arrival timestamp (ISO 8601 format)
}
```
{% endtab %}
{% endtabs %}
### option\_summary
Options instrument summary sourced from exchange-native options feeds. Available for exchanges that provide options data (e.g., Deribit, OKX Options, Binance European Options). Includes greeks, implied volatility, and best bid/ask for options instruments.
{% tabs %}
{% tab title="sample message" %}
```javascript
{
"type": "option_summary",
"symbol": "BTC-28JUN24-70000-C",
"exchange": "deribit",
"optionType": "call",
"strikePrice": 70000,
"expirationDate": "2024-06-28T08:00:00.000Z",
"bestBidPrice": 0.035,
"bestBidAmount": 5,
"bestBidIV": 0.55,
"bestAskPrice": 0.04,
"bestAskAmount": 10,
"bestAskIV": 0.58,
"lastPrice": 0.0375,
"openInterest": 150,
"markPrice": 0.0372,
"markIV": 0.565,
"delta": 0.25,
"gamma": 0.00002,
"vega": 45.5,
"theta": -15.2,
"rho": 0.05,
"underlyingPrice": 63500,
"underlyingIndex": "BTC-USD",
"timestamp": "2024-01-15T10:30:00.123Z",
"localTimestamp": "2024-01-15T10:30:00.234Z"
}
```
{% endtab %}
{% tab title="schema" %}
```typescript
{
type: 'option_summary'
symbol: string // instrument symbol as provided by exchange
exchange: string // exchange id
optionType: 'put' | 'call' // option type
strikePrice: number // strike price
expirationDate: string // option expiration date (ISO 8601 format)
bestBidPrice: number | undefined // best bid price
bestBidAmount: number | undefined // best bid amount
bestBidIV: number | undefined // best bid implied volatility
bestAskPrice: number | undefined // best ask price
bestAskAmount: number | undefined // best ask amount
bestAskIV: number | undefined // best ask implied volatility
lastPrice: number | undefined // last trade price
openInterest: number | undefined // open interest
markPrice: number | undefined // mark price
markIV: number | undefined // mark implied volatility
delta: number | undefined // delta greek
gamma: number | undefined // gamma greek
vega: number | undefined // vega greek
theta: number | undefined // theta greek
rho: number | undefined // rho greek
underlyingPrice: number | undefined // underlying asset price
underlyingIndex: string // underlying index name
timestamp: string // message timestamp provided by exchange (ISO 8601 format)
localTimestamp: string // message arrival timestamp (ISO 8601 format)
}
```
{% endtab %}
{% endtabs %}
### trade\_bar\_{aggregation\_interval}{suffix}
Trades data in aggregated form, known as OHLC, candlesticks, klines etc. Not only most common time based aggregation is supported, but volume and tick count based as well. Bars are computed from tick-by-tick raw trade data, if in given interval no trades happened, there is no bar produced. For time-based bars, a bar is emitted when the first trade of the next interval arrives — not at the exact interval boundary. The bar's `timestamp` reflects the end of the interval period, while `openTimestamp` and `closeTimestamp` reflect actual trade times within that interval.
#### Examples:
* `trade_bar_10ms` - provides time based trade bars with 10 milliseconds intervals
* `trade_bar_5m` - provides time based trade bars with 5 minute intervals
* `trade_bar_100ticks` - provides ticks based trade bars with 100 ticks (individual trades) intervals
* `trade_bar_100000vol` - provides volume based trade bars with 100 000 volume intervals
Allowed suffixes:
* `ms` - milliseconds
* `s` - seconds
* `m` - minutes
* `ticks` - number of ticks
* `vol` - volume size
{% tabs %}
{% tab title="sample message" %}
```javascript
{
"type": "trade_bar",
"symbol": "BTCUSDT",
"exchange": "binance-futures",
"name": "trade_bar_10000ms",
"interval": 10000,
"kind": "time",
"open": 61130.98,
"high": 61142.3,
"low": 61129.75,
"close": 61138.12,
"volume": 12.845,
"buyVolume": 7.421,
"sellVolume": 5.424,
"trades": 18,
"vwap": 61135.84,
"openTimestamp": "2024-03-01T00:00:00.112Z",
"closeTimestamp": "2024-03-01T00:00:09.881Z",
"localTimestamp": "2024-03-01T00:00:10.004Z",
"timestamp": "2024-03-01T00:00:10.000Z"
}
```
{% endtab %}
{% tab title="schema" %}
```typescript
{
type: 'trade_bar'
symbol: string // instrument symbol as provided by exchange
exchange: string // exchange id
name: string // name with format trade_bar_{interval}{suffix}
interval: number // requested trade bar interval
kind: 'time' | 'volume' | 'tick' // trade bar kind
open: number // open price
high: number // high price
low: number // low price
close: number // close price
volume: number // total volume traded in given interval
buyVolume: number // buy volume traded in given interval
sellVolume: number // sell volume traded in given interval
trades: number // trades count in given interval
vwap: number // volume weighted average price
openTimestamp: string // timestamp of first trade for given bar (ISO 8601 format)
closeTimestamp: string // timestamp of last trade for given bar (ISO 8601 format)
timestamp: string // end of interval period timestamp (ISO 8601 format)
localTimestamp: string // message arrival timestamp
// that triggered given bar computation (ISO 8601 format)
}
```
{% endtab %}
{% endtabs %}
### disconnect
Message that marks events when real-time WebSocket connection that was used to collect the historical data got disconnected.
{% tabs %}
{% tab title="sample message" %}
```javascript
{
"type": "disconnect",
"exchange": "deribit",
"localTimestamp": "2019-10-23T11:34:29.416Z"
}
```
{% endtab %}
{% tab title="schema" %}
```typescript
{
type: 'disconnect'
exchange: string // exchange id
localTimestamp: string // timestamp when disconnect occurred (ISO 8601 format)
symbols: string[] | undefined
}
```
{% endtab %}
{% endtabs %}
### error
Message sent when an underlying exchange WebSocket connection error occurs. Only available for [/ws-stream-normalized](/tardis-machine/streaming-real-time-data#websocket-ws-stream-normalized-options-options) when `withErrorMessages` is set to `true`. The `subSequentErrorsCount` tracks consecutive errors without successful data — if it reaches 50, the connection is closed.
{% tabs %}
{% tab title="sample message" %}
```javascript
{
"type": "error",
"exchange": "binance-futures",
"localTimestamp": "2024-01-15T10:30:00.123Z",
"details": "WebSocket connection error: Connection reset by peer",
"subSequentErrorsCount": 1
}
```
{% endtab %}
{% tab title="schema" %}
```typescript
{
type: 'error'
exchange: string // exchange id
localTimestamp: string // timestamp when error occurred (ISO 8601 format)
details: string // error message
subSequentErrorsCount: number // number of consecutive errors without successful data
}
```
{% endtab %}
{% endtabs %}
# Quickstart
Install, configure and get started with the tardis-dev Python package
Python `tardis-dev` package provides convenient access to tick-level historical cryptocurrency market data in exchange-native format. It focuses on two primary workflows: historical replay and CSV dataset downloads.
## Features
* [historical market data replay](/python-client/replaying-historical-data)
* [CSV dataset downloads](/downloadable-csv-files/overview)
{% hint style="warning" %}
If you're migrating older Python code that used `tardis-client`, `TardisClient` or `from tardis_dev import datasets`, start with [Migration Notice](/python-client/migration-notice).
{% endhint %}
{% embed url="" %}
Python tardis-dev GitHub repository
{% endembed %}
## Installation
Requires Python >=3.9.
```bash
pip install tardis-dev
```
## Historical Replay
```python
import asyncio
from tardis_dev import Channel, replay
async def main():
async for local_timestamp, message in replay(
exchange="binance",
from_date="2024-03-01",
to_date="2024-03-02",
filters=[Channel("trade", ["btcusdt"]), Channel("depth", ["btcusdt"])],
api_key="YOUR_API_KEY",
):
print(local_timestamp, message)
asyncio.run(main())
```
See [Replaying Historical Data](/python-client/replaying-historical-data) for replay arguments, `Channel` filters, disconnect events and cache behavior.
{% content-ref url="/pages/6dztE6gHE7Lm6xalHDjP" %}
[Replaying Historical Data](/python-client/replaying-historical-data)
{% endcontent-ref %}
## CSV Dataset Downloads
```python
from tardis_dev import download_datasets
download_datasets(
exchange="binance",
data_types=["trades", "incremental_book_L2"],
symbols=["BTCUSDT"],
from_date="2024-03-01",
to_date="2024-03-02",
api_key="YOUR_API_KEY",
)
```
{% hint style="info" %}
If you're calling from an existing event loop, use `download_datasets_async()` instead of `download_datasets()`.
{% endhint %}
See also [Downloadable CSV files docs](/downloadable-csv-files/overview).
### `download_datasets(...)`
`download_datasets()` is the synchronous wrapper around `download_datasets_async()`. It raises `RuntimeError` if called inside a running event loop.
| name | type | default | description |
| ---------------- | ------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `exchange` | string | - | exchange id with `supportsDatasets=true`; use [`get_exchange_details()`](#historical-market-data-helpers) to inspect available dataset symbols and data types |
| `data_types` | sequence of strings | - | dataset types to download, e.g. `trades`, `incremental_book_L2`, `quotes`, `book_snapshot_25`, `book_snapshot_5`, `book_ticker`, `derivative_ticker`, `options_chain`, `liquidations` |
| `symbols` | sequence of strings | - | dataset symbols to download, e.g. `BTCUSDT` or grouped symbols such as `OPTIONS` |
| `from_date` | string | - | start date in ISO format, e.g. `2024-03-01` |
| `to_date` | string | - | end date in ISO format (non-inclusive) |
| `api_key` | string (optional) | `""` | API key for premium historical datasets |
| `download_dir` | string (optional) | `"./datasets"` | local directory where downloaded files will be stored |
| `endpoint` | string (optional) | `https://datasets.tardis.dev/v1` | override datasets API endpoint |
| `timeout` | integer (optional) | `1800` | HTTP timeout in seconds |
| `http_proxy` | string (optional) | `None` | HTTP proxy URL passed to `aiohttp` |
| `format` | literal `"csv"` | `"csv"` | dataset file format |
| `concurrency` | integer (optional) | `20` | number of parallel download tasks; must be greater than `0` |
| `get_filename` | callable (optional) | `default_file_name` | function that returns the relative output path for each downloaded file |
| `skip_if_exists` | boolean (optional) | `True` | when `True`, skips files that already exist locally |
### `download_datasets_async(...)`
Use `download_datasets_async()` inside an existing `asyncio` event loop. It accepts the same arguments as `download_datasets()`.
## Historical Market Data Helpers
```python
from tardis_dev import clear_cache, find_instrument_symbols, get_exchange_details
details = get_exchange_details("binance")
print(details["availableSymbols"][0]["id"])
symbols_by_exchange = find_instrument_symbols(
["bitmex", "binance-futures", "okex-swap", "bybit"],
{
"baseCurrency": "BTC",
"quoteCurrency": "USDT",
"contractType": "linear_perpetual",
"active": True,
},
api_key="YOUR_API_KEY",
)
print(symbols_by_exchange)
clear_cache()
```
`get_exchange_details()` is the synchronous wrapper around `get_exchange_details_async()`.
### `get_exchange_details_async(exchange, *, endpoint=..., timeout=60, http_proxy=None)`
Use `get_exchange_details_async()` inside an existing `asyncio` event loop when you need exchange metadata without blocking on the synchronous wrapper.
| name | type | default | description |
| ------------ | ------------------ | --------------------------- | ------------------------------------ |
| `exchange` | string | - | exchange id to query, e.g. `binance` |
| `endpoint` | string (optional) | `https://api.tardis.dev/v1` | override HTTP API endpoint |
| `timeout` | integer (optional) | `60` | HTTP timeout in seconds |
| `http_proxy` | string (optional) | `None` | HTTP proxy URL passed to `aiohttp` |
### `get_instrument_info(...)` and `get_instrument_info_async(...)`
Use `get_instrument_info()` when you need full instrument metadata such as tick sizes, contract multipliers, base/quote currencies, `id`, and `datasetId` after the symbol appears in exported dataset metadata. It can query a single symbol, a single exchange with a filter, or multiple exchanges with the same filter.
```python
from tardis_dev import get_instrument_info
info = get_instrument_info("binance", symbol="btcusdt", api_key="YOUR_API_KEY")
print(info["priceIncrement"])
```
Use `get_instrument_info_async()` inside an existing `asyncio` event loop.
### `find_instrument_symbols(...)` and `find_instrument_symbols_async(...)`
Use this helper when you know the market you want but not each exchange's symbol format. It queries the [Instruments Metadata API](/api/instruments-metadata-api) with normalized criteria and returns the correct exchange-specific `id` for each requested exchange, ready to pass to replay or raw data feeds.
```python
from tardis_dev import find_instrument_symbols
symbols_by_exchange = find_instrument_symbols(
["bitmex", "binance-futures", "okex-swap", "bybit"],
{
"baseCurrency": "BTC",
"quoteCurrency": "USDT",
"contractType": "linear_perpetual",
"active": True,
},
api_key="YOUR_API_KEY",
)
print(symbols_by_exchange)
# [
# {"exchange": "bitmex", "symbols": ["XBTUSDT"]},
# {"exchange": "binance-futures", "symbols": ["btcusdt"]},
# {"exchange": "okex-swap", "symbols": ["BTC-USDT-SWAP"]},
# {"exchange": "bybit", "symbols": ["BTCUSDT"]},
# ]
```
The optional `selector` keyword defaults to `id`. Pass `selector="datasetId"` only when you need symbols for direct CSV dataset file downloads:
```python
csv_symbols_by_exchange = find_instrument_symbols(
["bitmex", "binance-futures", "okex-swap", "bybit"],
{
"baseCurrency": "BTC",
"quoteCurrency": "USDT",
"contractType": "linear_perpetual",
"active": True,
},
selector="datasetId",
api_key="YOUR_API_KEY",
)
```
Returned `id` symbols are exchange-provided IDs and are not normalized by the client. Returned `datasetId` symbols are CSV dataset IDs for instruments whose symbols appear in exported dataset metadata; `download_datasets()` URL-encodes them when constructing dataset URLs. Use `find_instrument_symbols_async()` inside an existing `asyncio` event loop.
## Other Public Exports
```python
from tardis_dev import Response, default_file_name
```
* `Response` is the public `NamedTuple` returned by `replay()`. See [Replaying Historical Data](/python-client/replaying-historical-data#type-of-messages-returned-by-replay) for details.
* `default_file_name(exchange, data_type, date, symbol, format)` is the default helper used by `download_datasets()` and `download_datasets_async()` to build output file names.
# Replaying Historical Data
Replaying historical market data in exchange-native format with the tardis-dev Python package
{% hint style="info" %}
See [historical data details](/historical-data-details/overview) page to get detailed information about historical market data available for each exchange.
{% endhint %}
## `replay(...)`
Replays historical market data messages for given replay arguments in [exchange-native format](/faq/data#what-is-a-difference-between-exchange-native-and-normalized-data-format). Historical market data is fetched in parallel from the [Tardis.dev HTTP API](/api/http-api-reference#data-feeds-exchange), cached locally on disk in compressed format and returned as an async generator.
`from_date` and `to_date` accept either ISO date strings or Python `datetime` values. Naive datetimes are treated as UTC.
{% hint style="info" %}
For filtered historical replay, the client automatically uses the [recommended `sliceSize`](/api/http-api-reference#data-feeds-exchange) to reduce `/data-feeds` request count.
{% endhint %}
```python
import asyncio
from tardis_dev import Channel, replay
async def main():
async for local_timestamp, message in replay(
exchange="binance",
from_date="2024-03-01",
to_date="2024-03-02",
filters=[
Channel("trade", ["btcusdt"]),
Channel("depth", ["btcusdt"]),
],
api_key="YOUR_API_KEY",
):
print(local_timestamp, message)
asyncio.run(main())
```
When `symbols` is omitted or `None` in `Channel`, data for all active symbols for that channel is returned. Use that form when you need the whole channel instead of starting one replay per symbol. If you need selected symbols, pass them together in one `Channel(name, [...])` entry.
{% hint style="info" %}
The replay API fetches data in parallel. Avoid blocking the async loop with slow I/O (for example synchronous file writes) inside the iteration — use async I/O or buffer writes to prevent slowdowns and timeouts.
{% endhint %}
#### replay arguments
| name | type | default | description |
| ------------------ | ------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `exchange` | string | - | requested exchange id - use [`get_exchange_details()`](/python-client/quickstart#historical-market-data-helpers) to inspect available channels and symbols |
| `from_date` | string or `datetime` | - | replay period start date (UTC) as ISO string or Python `datetime`, e.g. `2019-04-01` or `2019-04-01T12:00:00Z`; naive datetimes are treated as UTC |
| `to_date` | string or `datetime` | - | replay period end date (UTC, non-inclusive) as ISO string or Python `datetime`; naive datetimes are treated as UTC |
| `filters` | `Sequence[Channel]` (optional) | `None` | optional filters of requested historical data feed |
| `api_key` | string (optional) | `""` | API key for Tardis.dev [HTTP API](/api/http-api-reference#data-feeds-exchange) - if not provided only first day of each month of historical data is accessible |
| `cache_dir` | string (optional) | `/.tardis-cache` | path to local dir that will be used as cache location |
| `endpoint` | string (optional) | `https://api.tardis.dev/v1` | override HTTP API endpoint |
| `timeout` | integer (optional) | `135` | timeout in seconds for each replay HTTP request attempt |
| `http_proxy` | string (optional) | `None` | HTTP proxy URL passed to `aiohttp` |
| `compression` | `"zstd"` or `"gzip"` (optional) | `"zstd"` | preferred compression for replay requests; set to `"gzip"` when you need gzip-compressed slices |
| `decode_response` | boolean (optional) | `True` | when set to `False`, returns raw bytes instead of decoding JSON |
| `with_disconnects` | boolean (optional) | `False` | when set to `True`, yields `None` for events when the recording connection got disconnected |
| `auto_cleanup` | boolean (optional) | `False` | when set to `True`, automatically removes cached data from disk after it has been processed |
| `json` | module-like object (optional) | `json` | custom JSON module/object with a `loads()` function used when `decode_response=True` |
## `Channel(name, symbols=None)`
Use `Channel` objects to filter replay by exchange-native channel name and symbol list.
| name | type | description |
| --------- | ------------------------------ | ------------------------------------------------------------------------------------- |
| `name` | string | exchange-native channel name, e.g. `trade` or `depth` |
| `symbols` | sequence of strings (optional) | symbols to include; omit or pass `None` to include all active symbols for the channel |
```python
from tardis_dev import Channel
Channel("trade", ["btcusdt", "ethusdt"])
Channel("depth", ["btcusdt"])
Channel("trade")
```
{% hint style="warning" %}
The client can fetch replay data with up to 60 concurrent `/data-feeds` HTTP requests per replay job. Long date ranges, many channel/symbol filters and multiple concurrent replay processes can quickly exceed [API rate limits](/api/rate-limits), causing request failures.
{% endhint %}
{% hint style="warning" %}
Avoid using `auto_cleanup=True` with concurrent replay jobs that share the same exchange, filters and calendar day. Those jobs reuse the same cache path and can remove files that are still needed by another replay task.
{% endhint %}
#### type of messages returned by `replay`
`replay()` yields `Response(local_timestamp, message)` items, where `Response` is the public `NamedTuple` export from `tardis_dev`:
* `local_timestamp` is a Python `datetime` marking when the message was received from the exchange real-time feed
* `message` is a Python dict with parsed JSON in exchange-native format
When `decode_response=False`, both fields are returned as raw bytes instead.
When `with_disconnects=True`, replay can also yield `None` for disconnect events.
#### sample message
```python
{
"stream": "btcusdt@trade",
"data": {
"e": "trade",
"E": 1709251199998,
"s": "BTCUSDT",
"t": 3445374963,
"p": "61130.98000000",
"q": "0.00145000",
"b": 25230662315,
"a": 25230662808,
"T": 1709251199998,
"m": True,
"M": True
}
}
```
{% hint style="info" %}
Python `tardis-dev` currently documents exchange-native replay only. If you need normalized replay or real-time streaming, use the [Node.js client](/node-client/quickstart) or [tardis-machine](/tardis-machine/quickstart).
{% endhint %}
# Migration Notice
Migrate from tardis-client and tardis\_dev.datasets to the unified tardis-dev package
Python client v3 unifies historical replay, CSV dataset downloads and exchange metadata into one package: `tardis-dev`.
{% hint style="warning" %}
This is a hard break. There is no compatibility layer for `tardis-client`, `TardisClient`, `tardis_dev.datasets`, reconstructors or any temporary shim.
{% endhint %}
## Install the new package
```bash
pip uninstall tardis-client
pip install tardis-dev
```
If you were already using the dataset-download package, upgrade it in place:
```bash
pip install --upgrade tardis-dev
```
## API mapping
| Before | After |
| ------------------------------------------------- | -------------------------------------------------------------------- |
| `from tardis_client import TardisClient, Channel` | `from tardis_dev import replay, Channel` |
| `tardis_client = TardisClient(api_key="...")` | pass `api_key="..."` directly to `replay()` or `download_datasets()` |
| `tardis_client.replay(...)` | `replay(...)` |
| `from tardis_dev import datasets` | `from tardis_dev import download_datasets` |
| `datasets.download(...)` | `download_datasets(...)` |
| `tardis_client.clear_cache()` | `clear_cache()` |
| `get_exchange_details(exchange)` | `get_exchange_details(exchange)` |
## Replay migration
### Before
```python
import asyncio
from tardis_client import TardisClient, Channel
async def main():
tardis_client = TardisClient(api_key="YOUR_API_KEY")
async for local_timestamp, message in tardis_client.replay(
exchange="bitmex",
from_date="2019-06-01",
to_date="2019-06-02",
filters=[Channel("trade", ["XBTUSD"])],
):
print(local_timestamp, message)
asyncio.run(main())
```
### After
```python
import asyncio
from tardis_dev import Channel, replay
async def main():
async for local_timestamp, message in replay(
exchange="bitmex",
from_date="2019-06-01",
to_date="2019-06-02",
filters=[Channel("trade", ["XBTUSD"])],
api_key="YOUR_API_KEY",
):
print(local_timestamp, message)
asyncio.run(main())
```
What changed:
* `TardisClient` is gone; `replay()` is now a top-level async generator
* configuration stays explicit at the call site via keyword arguments
* `Channel.symbols=None` or omitting `symbols` means all symbols for that channel
## Dataset download migration
### Before
```python
from tardis_dev import datasets
datasets.download(
exchange="deribit",
data_types=["trades", "incremental_book_L2"],
symbols=["BTC-PERPETUAL"],
from_date="2019-11-01",
to_date="2019-11-02",
api_key="YOUR_API_KEY",
)
```
### After
```python
from tardis_dev import download_datasets
download_datasets(
exchange="deribit",
data_types=["trades", "incremental_book_L2"],
symbols=["BTC-PERPETUAL"],
from_date="2019-11-01",
to_date="2019-11-02",
api_key="YOUR_API_KEY",
)
```
What changed:
* `datasets` subpackage was removed
* `download()` was renamed to `download_datasets()`
* `download_datasets()` is the synchronous wrapper; use `download_datasets_async()` inside an existing event loop
## Cache cleanup migration
### Before
```python
from tardis_client import TardisClient
tardis_client = TardisClient()
tardis_client.clear_cache()
```
### After
```python
from tardis_dev import clear_cache
clear_cache()
clear_cache(cache_dir="./cache")
```
## Removed APIs
The following public APIs are intentionally removed in v3:
* `TardisClient`
* `reconstruct_market()`
* `tardis_client.reconstructors`
* `tardis_dev.datasets`
## Related docs
* [Quickstart](/python-client/quickstart)
* [Replaying Historical Data](/python-client/replaying-historical-data)
* [Downloadable CSV Files Quickstart](/downloadable-csv-files/overview)
* [Downloadable CSV Files API Reference](/downloadable-csv-files/api)
# Overview
Historical market data details for each supported exchange — available symbols, channels, date ranges...
{% hint style="info" %}
Historical data details describes data collection specifics for each supported exchange and what's available via Tardis.dev [HTTP API](/api/http-api-reference). If you'd like to work with [normalized market data](/faq/data#what-is-a-difference-between-exchange-native-and-normalized-data-format) see [official libraries](/api/quickstart) and [downloadable CSV files](/downloadable-csv-files/overview).
{% endhint %}
You'll find here per-exchange details about:
* historical data availability date ranges — since when the historical data has been collected and is available
* captured real-time market data channels also described as streams, subscription topics, tables etc in exchanges' docs — available historical raw market data is being sourced from WebSocket real-time APIs provided by the exchanges and can be filtered by channels, e.g.: to get historical trades for BitMEX, channel `trade` needs to be provided alongside requested instruments symbols (via [HTTP API](/api/http-api-reference#data-feeds-exchange) or [client libs](/api/quickstart) function args).
* symbols of recorded instruments/currency pairs
* incidents - known Tardis.dev market data collection issues where data may be missing or affected for a given exchange
Some exchanges encode requested symbol in channel name, e.g.: Deribit `trades.BTC-PERPETUAL.100ms` channel. This is not the case with our API as we always consider channel name and symbol to be separate inputs. In case of Deribit example channel name would be `trades` and symbol `BTC-PERPETUAL`. If channel provides option of frequency of updates (e.g.: 100ms vs raw tick by tick) always higher frequency one is being chosen and recorded.
{% hint style="info" %}
[What is the channel field used in the HTTP API and client libs replay functions?](/faq/data#what-is-the-channel-field-used-in-the-http-api-and-client-libs-replay-functions)
{% endhint %}
## Market data collection overview
* All market data collection is being performed on one of the highly available [Google Cloud Platform Kubernetes Clusters](https://cloud.google.com/kubernetes-engine/) - London, UK (europe-west2 region) or Tokyo, Japan (asia-northeast1 region) - information which data center location is used for particular exchange is described on exchange historical data details page.
* When exchange provides choice of real-time data frequency for specific data types (e.g. order book data ) always most granular, non aggregated data feed is being collected.
* Choice if single or multiple WebSocket connections are being used to record full real-time data feed is made on case by case basis - we take into account exchange API limits and latency which may be higher or lower if single connection is being used - detailed information which strategy is used for particular exchange is described on exchange historical data details page.
* WebSocket connection is dynamically re-subscribed (or restarted for some exchanges) at 00:00 UTC every day in order to receive [initial order book snapshots](#collected-order-book-data-details).
* Each received message is timestamped with 100ns precision using [synchronized clock](https://developers.google.com/time) at arrival time and stored in ISO 8601 format.
* Messages provided by exchanges' WebSocket feeds are being stored without any modifications.
* Checks for new instruments available on a given exchange are performed every minute.
* Market data collection services are being constantly monitored both manually and via automated tools (monitoring, alert notifications) and have built-in self-healing capabilities. We also constantly monitor for upcoming exchanges' API changes and adapt to those beforehand.
* There are multiple built-in checks that detect whether a connection to an exchange is healthy during the data collection process, such as:
* validating subscription responses - if an exchange does not confirm subscriptions within 20 seconds, the connection is restarted
* [Heartbeat pings](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#Pings_and_Pongs_The_Heartbeat_of_WebSockets)
* order book sequence number validation for exchanges that provide those
* validating JSON format as in some unusual circumstances exchanges return data that is invalid JSON
* stale connection detection - if there are no responses received within a certain period (adjusted per exchange), it's most likely a stale connection that is automatically restarted
* detection of an unusually low message count from an exchange in a given time period, which likely means the connection is not healthy, e.g. receiving only 'pings' without data messages
* and many more
* Any incident that is caused by us (bugs, network errors etc.) is being logged and available [via API](/api/http-api-reference#exchanges-exchange).
* New market data delay is 6 minutes in relation to real-time (`T - 6min`).
## Collected order book data details
Historical market data available via [HTTP API](/api/http-api-reference#data-feeds-exchange) provides order book snapshots at the beginning of each day (00:00 UTC) and every time a WebSocket connection has been closed while recording real-time data feeds (the connection is restarted and a new snapshot is provided via a fresh connection). This means that to be sure to receive initial order book snapshots, one must replay historical data from 00:00 UTC of that day. It also means there is a tiny **gap in historical data** (around `300-3000ms`, depending on the exchange) during re-subscription to real-time WebSocket feeds (every 24 hours) to receive order book snapshots.
Some exchanges do not provide initial order book snapshots when subscribing to WebSocket real-time feeds (like Binance, Bitstamp or Coinbase Exchange full order book), hence for those there is a 'generated' snapshot available instead (based on REST API call) - details are specific for each exchange and are described in per-exchange historical details pages.
## Per-exchange historical data details
{% hint style="info" %}
Click any exchange below to see its historical data details - available instruments, captured [real-time channels](/faq/data#what-is-the-channel-field-used-in-the-http-api-and-client-libs-replay-functions), API access details and market data collection specifics.
{% endhint %}
* [Binance USDS-M Futures](/historical-data-details/binance-futures)
* [Binance COIN Futures](/historical-data-details/binance-delivery)
* [Binance European Options](/historical-data-details/binance-european-options)
* [Binance Spot](/historical-data-details/binance)
* [Binance US](/historical-data-details/binance-us)
* [OKX Futures](/historical-data-details/okex-futures)
* [OKX Swap](/historical-data-details/okex-swap)
* [OKX Options](/historical-data-details/okex-options)
* [OKX Spot](/historical-data-details/okex)
* [OKX Nitro Spreads](/historical-data-details/okex-spreads)
* [Coinbase Exchange](/historical-data-details/coinbase)
* [Coinbase International](/historical-data-details/coinbase-international)
* [BitMEX](/historical-data-details/bitmex)
* [Deribit](/historical-data-details/deribit)
* [Bybit Derivatives](/historical-data-details/bybit)
* [Bybit Spot](/historical-data-details/bybit-spot)
* [Bybit Options](/historical-data-details/bybit-options)
* [Kraken Futures](/historical-data-details/cryptofacilities)
* [Kraken](/historical-data-details/kraken)
* [Bitfinex Derivatives](/historical-data-details/bitfinex-derivatives)
* [Bitfinex](/historical-data-details/bitfinex)
* [KuCoin Futures](/historical-data-details/kucoin-futures)
* [KuCoin Spot](/historical-data-details/kucoin)
* [Aster Futures](/historical-data-details/aster-futures)
* [Aster Spot](/historical-data-details/aster)
* [MEXC Spot](/historical-data-details/mexc)
* [MEXC Futures](/historical-data-details/mexc-futures)
* [Crypto.com](/historical-data-details/crypto-com)
* [Bitstamp](/historical-data-details/bitstamp)
* [Bitget Futures](/historical-data-details/bitget-futures)
* [Bitget Spot](/historical-data-details/bitget)
* [Gate.io Futures](/historical-data-details/gate-io-futures)
* [Gate.io](/historical-data-details/gate-io)
* [HTX Coin-M Futures](/historical-data-details/huobi-dm)
* [HTX Coin-M Perpetual](/historical-data-details/huobi-dm-swap)
* [HTX USDT-M Contracts](/historical-data-details/huobi-dm-linear-swap)
* [HTX Spot](/historical-data-details/huobi)
* [Gemini](/historical-data-details/gemini)
* [WOO X](/historical-data-details/woo-x)
* [Upbit](/historical-data-details/upbit)
* [Phemex](/historical-data-details/phemex)
* [Delta Exchange](/historical-data-details/delta)
* [Blockchain.com](/historical-data-details/blockchain-com)
* [Bitnomial](/historical-data-details/bitnomial)
* [bitFlyer](/historical-data-details/bitflyer)
* [HitBTC](/historical-data-details/hitbtc)
* [Poloniex](/historical-data-details/poloniex)
* [Hyperliquid](/historical-data-details/hyperliquid)
* [Lighter](/historical-data-details/lighter)
* [Polymarket](/historical-data-details/polymarket)
* [Bullish](/historical-data-details/bullish)
* [dYdX v4](/historical-data-details/dydx-v4)
### Delisted exchanges
* [FTX](/historical-data-details/ftx)
* [FTX US](/historical-data-details/ftx-us)
* [OKCoin](/historical-data-details/okcoin)
* [AscendEX (BitMax)](/historical-data-details/ascendex)
* [CoinFLEX](/historical-data-details/coinflex)
* [Binance Jersey](/historical-data-details/binance-jersey)
* [Binance DEX](/historical-data-details/binance-dex)
* [HTX Options](/historical-data-details/huobi-dm-options)
* [dYdX](/historical-data-details/dydx)
* [Serum DEX](/historical-data-details/serum)
* [Mango Markets DEX](/historical-data-details/mango)
* [Star Atlas DEX](/historical-data-details/star-atlas)
# Binance USDS-M Futures
Binance USDS-M Futures historical market data details - instruments, data coverage and data collection specifics
Binance USDS-M Futures historical data for **all its instruments** is available since **2019-11-17**.
{% embed url="" %}
See Binance USDS-M Futures historical data coverage: available symbols, channels, date ranges and incidents
{% endembed %}
{% hint style="info" %}
Data collection before 2020-05-14 suffered some issues (missing data, latency spikes) during market volatility periods. It has been circumvented by switching to [Tokyo DC](#market-data-collection-details) and using multiple WS connections for real-time market data collection.
{% endhint %}
### 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](/downloadable-csv-files/overview).
`derivative_ticker` **open interest data is available since 2020-05-13** - date since we've started collecting that info via Binance USDS-M Futures REST API (open interest channel).
| data type | symbol | date | |
| --------------------- | ------- | ---------- | --------------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTCUSDT | 2020-02-01 | [Download sample](https://datasets.tardis.dev/v1/binance-futures/incremental_book_L2/2020/02/01/BTCUSDT.csv.gz) |
| trades | BTCUSDT | 2020-02-01 | [Download sample](https://datasets.tardis.dev/v1/binance-futures/trades/2020/02/01/BTCUSDT.csv.gz) |
| derivative\_ticker | BTCUSDT | 2020-02-01 | [Download sample](https://datasets.tardis.dev/v1/binance-futures/derivative_ticker/2020/02/01/BTCUSDT.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time Binance USDS-M Futures WebSocket API with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/api/quickstart) that 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="binance-futures",
from_date="2023-03-01",
to_date="2023-03-02",
filters=[Channel(name="depth", symbols=["btcusdt"])],
api_key="YOUR_API_KEY",
):
# messages as provided by Binance USDS-M Futures real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'binance-futures',
from: '2023-03-01',
to: '2023-03-02',
filters: [{ channel: 'depth', symbols: ['btcusdt'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Binance USDS-M Futures real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/binance-futures?from=2023-03-01&filters=[{"channel":"depth","symbols":["btcusdt"]}]&offset=0'
```
{% embed url="" %}
Example API response for Binance USDS-M Futures historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"binance-futures","filters":[{"channel":"depth","symbols":["btcusdt"]}],"from":"2023-03-01","to":"2023-03-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See Binance USDS-M Futures WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [trade](https://api.tardis.dev/v1/data-feeds/binance-futures?from=2024-01-01\&filters=\[{%22channel%22:%22trade%22}]) Public futures trade executions stream
* [depth](https://api.tardis.dev/v1/data-feeds/binance-futures?from=2024-01-01\&filters=\[{%22channel%22:%22depth%22,%22symbols%22:\[%22btcusdt%22]}]) Incremental futures order book updates stream. Recorded with the fastest API cadence available at the time: until 2020-01-07 it was subscribed as `depth@100ms` (100ms updates), after that as `depth@0ms` (real-time dynamically adjusted update speed).
* [depthSnapshot](https://api.tardis.dev/v1/data-feeds/binance-futures?from=2024-01-01\&filters=\[{%22channel%22:%22depthSnapshot%22,%22symbols%22:\[%22btcusdt%22]}]) — generated channel Binance USDS-M Futures real-time WebSocket API **does not provide initial order book snapshots**. To overcome this issue we fetch initial order book snapshots from REST API and store them together with the rest of the WebSocket messages — top 1000 levels. Such snapshot messages are marked with `"stream":"@depthSnapshot"` and `"generated":true` fields.
During data collection integrity of order book incremental updates is being validated using [sequence numbers](https://binance-docs.github.io/apidocs/futures/en/#how-to-manage-a-local-order-book-correctly) provided by real-time feed (`pu` and `u` fields) — in case of detecting missed message WebSocket connection is being restarted. We also validate if initial book snapshot fetched from REST API overlaps with received `depth` messages.
* [bookTicker](https://api.tardis.dev/v1/data-feeds/binance-futures?from=2024-01-01\&filters=\[{%22channel%22:%22bookTicker%22,%22symbols%22:\[%22btcusdt%22]}]) Best bid and best ask updates stream
* [forceOrder](https://api.tardis.dev/v1/data-feeds/binance-futures?from=2024-01-01\&filters=\[{%22channel%22:%22forceOrder%22}]) — available since **2020-01-07** Liquidation order stream publishing only the latest liquidation per symbol in each 1000ms window
* [ticker](https://api.tardis.dev/v1/data-feeds/binance-futures?from=2024-01-01\&filters=\[{%22channel%22:%22ticker%22,%22symbols%22:\[%22btcusdt%22]}]) 24h futures ticker updates stream
* [markPrice](https://api.tardis.dev/v1/data-feeds/binance-futures?from=2024-01-01\&filters=\[{%22channel%22:%22markPrice%22,%22symbols%22:\[%22btcusdt%22]}]) Mark price and funding metrics stream. Subscribed as `@markPrice@1s`. The 1s update speed has been available since 2020-02-13; before that the default (3s) speed was used.
* [premiumIndex](https://api.tardis.dev/v1/data-feeds/binance-futures?from=2026-05-01\&filters=\[{%22channel%22:%22premiumIndex%22,%22symbols%22:\[%22btcusdt%22]}]) — generated channel, available since **2026-04-11**
Snapshots are fetched from the REST [mark price endpoint](https://developers.binance.com/docs/derivatives/usds-margined-futures/market-data/rest-api/Mark-Price) about every 6 seconds for all instruments. The recorder splits the REST response into one generated message per instrument, marked with `"stream":"@premiumIndex"` and `"generated":true` fields. This channel includes the `interestRate` field that is not present on the WebSocket `markPrice` stream.
* [indexConstituents](https://api.tardis.dev/v1/data-feeds/binance-futures?from=2026-05-01\&filters=\[{%22channel%22:%22indexConstituents%22,%22symbols%22:\[%22btcusdt%22]}]) — generated channel, available since **2026-04-23**
Snapshots are fetched from the REST [index price constituents endpoint](https://developers.binance.com/docs/derivatives/usds-margined-futures/market-data/rest-api/Index-Constituents) every minute per instrument. Messages are marked with `"stream":"@indexConstituents"` and `"generated":true` fields with REST response format.
* [openInterest](https://api.tardis.dev/v1/data-feeds/binance-futures?from=2024-01-01\&filters=\[{%22channel%22:%22openInterest%22,%22symbols%22:\[%22btcusdt%22]}]) — generated channel, available since **2020-05-12**
Snapshots are fetched from the REST [open interest endpoint](https://binance-docs.github.io/apidocs/futures/en/#open-interest) about every 6 seconds per instrument. Messages are marked with `"stream":"@openInterest"` and `"generated":true` fields with REST response format.
* [fundingInfo](https://api.tardis.dev/v1/data-feeds/binance-futures?from=2026-03-17\&filters=\[{%22channel%22:%22fundingInfo%22}]) — generated channel, available since **2026-03-17**
Snapshots are fetched from the REST [funding info endpoint](https://developers.binance.com/docs/derivatives/usds-margined-futures/market-data/rest-api/Get-Funding-Rate-Info) every minute. Binance returns only symbols with adjusted funding cap, floor, or interval. Messages are marked with `"stream":"@fundingInfo"` and `"generated":true` fields with REST response format.
* [insuranceBalance](https://api.tardis.dev/v1/data-feeds/binance-futures?from=2026-03-17\&filters=\[{%22channel%22:%22insuranceBalance%22}]) — generated channel, available since **2026-03-17**
Snapshots are fetched from the REST [insurance fund balance endpoint](https://developers.binance.com/docs/derivatives/usds-margined-futures/market-data/rest-api/Insurance-Fund-Balance) every minute. Messages are marked with `"stream":"insuranceBalance"` and `"generated":true` fields with REST response format.
* [aggTrade](https://api.tardis.dev/v1/data-feeds/binance-futures?from=2024-01-01\&filters=\[{%22channel%22:%22aggTrade%22}]) Aggregated futures trade executions stream
* [compositeIndex](https://api.tardis.dev/v1/data-feeds/binance-futures?from=2024-01-01\&filters=\[{%22channel%22:%22compositeIndex%22,%22symbols%22:\[%22defiusdt%22]}]) — available since **2020-10-28** Composite index updates stream for multi-asset index symbols
* [assetIndex](https://api.tardis.dev/v1/data-feeds/binance-futures?from=2024-01-01\&filters=\[{%22channel%22:%22assetIndex%22}]) — available since **2023-06-16** Asset index updates stream
* [topLongShortAccountRatio](https://api.tardis.dev/v1/data-feeds/binance-futures?from=2024-01-01\&filters=\[{%22channel%22:%22topLongShortAccountRatio%22,%22symbols%22:\[%22btcusdt%22]}]\&offset=3) — generated channel, available since **2020-10-28**
Top trader long/short ratio (accounts), sourced by querying [REST endpoint](https://binance-docs.github.io/apidocs/futures/en/#top-trader-long-short-ratio-accounts) every minute
* [topLongShortPositionRatio](https://api.tardis.dev/v1/data-feeds/binance-futures?from=2024-01-01\&filters=\[{%22channel%22:%22topLongShortPositionRatio%22,%22symbols%22:\[%22btcusdt%22]}]\&offset=3) — generated channel, available since **2020-10-28**
Top trader long/short ratio (positions), sourced by querying [REST endpoint](https://binance-docs.github.io/apidocs/futures/en/#top-trader-long-short-ratio-positions) every minute
* [globalLongShortAccountRatio](https://api.tardis.dev/v1/data-feeds/binance-futures?from=2024-01-01\&filters=\[{%22channel%22:%22globalLongShortAccountRatio%22,%22symbols%22:\[%22btcusdt%22]}]\&offset=3) — generated channel, available since **2020-10-28**
Global long/short ratio, sourced by querying [REST endpoint](https://binance-docs.github.io/apidocs/futures/en/#long-short-ratio) every minute
* [takerlongshortRatio](https://api.tardis.dev/v1/data-feeds/binance-futures?from=2024-01-01\&filters=\[{%22channel%22:%22takerlongshortRatio%22,%22symbols%22:\[%22btcusdt%22]}]\&offset=3) — generated channel, available since **2021-12-01**
Taker buy/sell volume ratio, sourced by querying [REST endpoint](https://binance-docs.github.io/apidocs/futures/en/#taker-buy-sell-volume) every minute
* `!contractInfo` — available since **2023-07-24** Contract metadata updates stream pushed when listing, settlement, or bracket information changes
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for Binance USDS-M Futures **since 2020-05-14** is located in GCP asia-northeast1 region (Tokyo, Japan), before that it was located in GCP europe-west2 region (London, UK).
Real-time market data is captured via **multiple WebSocket connections** to `wss://fstream.binance.com/stream`.
{% hint style="info" %}
Binance servers are located in AWS ap-northeast-1 region (Tokyo, Japan).
{% endhint %}
# Binance COIN Futures
Binance COIN Margined Futures historical market data details - instruments, data coverage and data collection specifics
Binance COIN Futures historical data for **all its instruments** is available since **2020-06-16**.
{% embed url="" %}
See Binance COIN Futures 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | -------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTCUSD\_200925 | 2020-07-01 | [Download sample](https://datasets.tardis.dev/v1/binance-delivery/incremental_book_L2/2020/07/01/BTCUSD_200925.csv.gz) |
| trades | BTCUSD\_200925 | 2020-07-01 | [Download sample](https://datasets.tardis.dev/v1/binance-delivery/trades/2020/07/01/BTCUSD_200925.csv.gz) |
| derivative\_ticker | BTCUSD\_200925 | 2020-07-01 | [Download sample](https://datasets.tardis.dev/v1/binance-delivery/derivative_ticker/2020/07/01/BTCUSD_200925.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time Binance COIN Futures WebSocket API with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/api/quickstart) that 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="binance-delivery",
from_date="2023-03-01",
to_date="2023-03-02",
filters=[Channel(name="depth", symbols=["btcusd_perp"])],
api_key="YOUR_API_KEY",
):
# messages as provided by Binance COIN Futures real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'binance-delivery',
from: '2023-03-01',
to: '2023-03-02',
filters: [{ channel: 'depth', symbols: ['btcusd_perp'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Binance COIN Futures real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/binance-delivery?from=2023-03-01&filters=[{"channel":"depth","symbols":["btcusd_perp"]}]&offset=0'
```
{% embed url="" %}
Example API response for Binance COIN Futures historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"binance-delivery","filters":[{"channel":"depth","symbols":["btcusd_perp"]}],"from":"2023-03-01","to":"2023-03-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See Binance COIN Futures WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [trade](https://api.tardis.dev/v1/data-feeds/binance-delivery?from=2024-01-01\&filters=\[{%22channel%22:%22trade%22}]) Public COIN futures trade executions stream
* [depth](https://api.tardis.dev/v1/data-feeds/binance-delivery?from=2024-01-01\&filters=\[{%22channel%22:%22depth%22,%22symbols%22:\[%22btcusd_perp%22]}]) Incremental COIN futures order book updates stream. Subscribed as `depth@0ms` with real-time dynamically adjusted update speed.
* [depthSnapshot](https://api.tardis.dev/v1/data-feeds/binance-delivery?from=2024-01-01\&filters=\[{%22channel%22:%22depthSnapshot%22,%22symbols%22:\[%22btcusd_perp%22]}]) — generated channel Binance COIN Futures real-time WebSocket API **does not provide initial order book snapshots**. To overcome this issue we fetch initial order book snapshots from REST API and store them together with the rest of the WebSocket messages — top 1000 levels. Such snapshot messages are marked with `"stream":"@depthSnapshot"` and `"generated":true` fields.
During data collection integrity of order book incremental updates is being validated using [sequence numbers](https://binance-docs.github.io/apidocs/delivery/en/#diff-book-depth-streams) provided by real-time feed (`U` and `u` fields) — in case of detecting missed message WebSocket connection is being restarted. We also validate if initial book snapshot fetched from REST API overlaps with received `depth` messages.
* [bookTicker](https://api.tardis.dev/v1/data-feeds/binance-delivery?from=2024-01-01\&filters=\[{%22channel%22:%22bookTicker%22}]) Best bid and best ask updates stream
* [forceOrder](https://api.tardis.dev/v1/data-feeds/binance-delivery?from=2024-01-01\&filters=\[{%22channel%22:%22forceOrder%22}]) — available since **2020-07-08** Liquidation order stream publishing only the latest liquidation per symbol in each 1000ms window
* [markPrice](https://api.tardis.dev/v1/data-feeds/binance-delivery?from=2024-01-01\&filters=\[{%22channel%22:%22markPrice%22}]) Mark price and funding metrics stream subscribed as `@markPrice@1s`
* [indexPrice](https://api.tardis.dev/v1/data-feeds/binance-delivery?from=2024-01-01\&filters=\[{%22channel%22:%22indexPrice%22}]) Index price updates stream subscribed as `@indexPrice@1s`
* [openInterest](https://api.tardis.dev/v1/data-feeds/binance-delivery?from=2024-01-01\&filters=\[{%22channel%22:%22openInterest%22,%22symbols%22:\[%22btcusd_perp%22]}]) — generated channel
Snapshots are fetched from the REST [open interest endpoint](https://binance-docs.github.io/apidocs/delivery/en/#open-interest) about every 6 seconds per instrument. Messages are marked with `"stream":"@openInterest"` and `"generated":true` fields with REST response format.
* [fundingInfo](https://api.tardis.dev/v1/data-feeds/binance-delivery?from=2026-03-17\&filters=\[{%22channel%22:%22fundingInfo%22}]) — generated channel, available since **2026-03-17**
Snapshots are fetched from the REST [funding info endpoint](https://developers.binance.com/docs/derivatives/coin-margined-futures/market-data/rest-api/Get-Funding-Info) every minute. Binance returns only symbols with adjusted funding cap, floor, or interval. Messages are marked with `"stream":"@fundingInfo"` and `"generated":true` fields with REST response format.
* [aggTrade](https://api.tardis.dev/v1/data-feeds/binance-delivery?from=2024-01-01\&filters=\[{%22channel%22:%22aggTrade%22}]) Aggregated COIN futures trade executions stream
* [ticker](https://api.tardis.dev/v1/data-feeds/binance-delivery?from=2024-01-01\&filters=\[{%22channel%22:%22ticker%22}]) 24h COIN futures ticker updates stream
* [topLongShortAccountRatio](https://api.tardis.dev/v1/data-feeds/binance-delivery?from=2024-02-01\&filters=\[{%22channel%22:%22topLongShortAccountRatio%22,%22symbols%22:\[]}]\&offset=4) — generated channel, available since **2020-10-28**
Top trader long/short ratio (accounts), sourced by querying REST endpoint every minute
* [topLongShortPositionRatio](https://api.tardis.dev/v1/data-feeds/binance-delivery?from=2024-02-01\&filters=\[{%22channel%22:%22topLongShortPositionRatio%22,%22symbols%22:\[]}]\&offset=4) — generated channel, available since **2020-10-28**
Top trader long/short ratio (positions), sourced by querying REST endpoint every minute
* [globalLongShortAccountRatio](https://api.tardis.dev/v1/data-feeds/binance-delivery?from=2024-02-01\&filters=\[{%22channel%22:%22globalLongShortAccountRatio%22,%22symbols%22:\[]}]\&offset=4) — generated channel, available since **2020-10-28**
Global long/short ratio, sourced by querying REST endpoint every minute
* [takerBuySellVol](https://api.tardis.dev/v1/data-feeds/binance-delivery?from=2024-02-01\&filters=\[{%22channel%22:%22takerBuySellVol%22,%22symbols%22:\[]}]\&offset=4) — generated channel, available since **2021-12-01**
Taker buy/sell volume ratio, sourced by querying REST endpoint every minute
* `!contractInfo` — available since **2023-04-01** Contract metadata updates stream pushed when listing, settlement, or bracket information changes
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for Binance COIN Futures is located in GCP asia-northeast1 region (Tokyo, Japan).
Real-time market data is captured via **multiple WebSocket connections** to `wss://dstream.binance.com/stream`.
{% hint style="info" %}
Binance servers are located in AWS ap-northeast-1 region (Tokyo, Japan).
{% endhint %}
# Binance European Options
Binance European Options historical market data details - instruments, data coverage and data collection specifics
Binance European Options historical data for **all its instruments** is available since **2023-06-15**.
{% embed url="" %}
See Binance European Options 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | ------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTC-250328-50000-C | 2024-08-01 | [Download sample](https://datasets.tardis.dev/v1/binance-european-options/incremental_book_L2/2024/08/01/BTC-250328-50000-C.csv.gz) |
| trades | BTC-250328-50000-C | 2024-08-01 | [Download sample](https://datasets.tardis.dev/v1/binance-european-options/trades/2024/08/01/BTC-250328-50000-C.csv.gz) |
| options\_chain | OPTIONS | 2024-01-01 | [Download sample](https://datasets.tardis.dev/v1/binance-european-options/options_chain/2024/01/01/OPTIONS.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time Binance European Options WebSocket API with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/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="binance-european-options",
from_date="2026-01-01",
to_date="2026-01-02",
filters=[Channel(name="depth20")],
api_key="YOUR_API_KEY",
):
# messages as provided by Binance European Options real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'binance-european-options',
from: '2026-01-01',
to: '2026-01-02',
filters: [{ channel: 'depth20' }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Binance European Options real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/binance-european-options?from=2026-01-01&filters=[{"channel":"depth20"}]&offset=0'
```
{% embed url="" %}
Example API response for Binance European Options historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"binance-european-options","filters":[{"channel":"depth20"}],"from":"2026-01-01","to":"2026-01-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See Binance European Options WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
**Current channels (since 2025-12-17):**
* [optionTrade](https://api.tardis.dev/v1/data-feeds/binance-european-options?from=2026-01-01\&filters=\[{%22channel%22:%22optionTrade%22}]) — available since **2025-12-17** Public option trade executions stream
* [depth20](https://api.tardis.dev/v1/data-feeds/binance-european-options?from=2026-01-01\&filters=\[{%22channel%22:%22depth20%22}]) — available since **2025-12-17** Options order book updates stream with top 20 levels subscribed as @depth20\@100ms
* [bookTicker](https://api.tardis.dev/v1/data-feeds/binance-european-options?from=2026-01-01\&filters=\[{%22channel%22:%22bookTicker%22}]) — available since **2025-12-17** Best bid and best ask updates stream
* [optionTicker](https://api.tardis.dev/v1/data-feeds/binance-european-options?from=2026-01-01\&filters=\[{%22channel%22:%22optionTicker%22}]) — available since **2025-12-17** Options ticker updates stream
* [optionMarkPrice](https://api.tardis.dev/v1/data-feeds/binance-european-options?from=2026-01-01\&filters=\[{%22channel%22:%22optionMarkPrice%22}]) — available since **2025-12-17** Option mark price updates stream
* [optionOpenInterest](https://api.tardis.dev/v1/data-feeds/binance-european-options?from=2026-01-01\&filters=\[{%22channel%22:%22optionOpenInterest%22}]) — available since **2025-12-17** Option open interest updates stream
* [optionIndexPrice](https://api.tardis.dev/v1/data-feeds/binance-european-options?from=2026-01-01\&filters=\[{%22channel%22:%22optionIndexPrice%22}]) — available since **2025-12-17** Option index price updates stream
**Legacy channels (eapi v1, until 2025-12-17):**
* [trade](https://api.tardis.dev/v1/data-feeds/binance-european-options?from=2024-06-01\&filters=\[{%22channel%22:%22trade%22}]) — available until **2025-12-17** Public options trade executions stream
* [depth100](https://api.tardis.dev/v1/data-feeds/binance-european-options?from=2024-01-01\&filters=\[{%22channel%22:%22depth100%22}]) — available until **2025-12-17** Options order book updates stream with top 100 levels
* [index](https://api.tardis.dev/v1/data-feeds/binance-european-options?from=2024-06-01\&filters=\[{%22channel%22:%22index%22}]) — available until **2025-12-17** Options index price updates stream
* [ticker](https://api.tardis.dev/v1/data-feeds/binance-european-options?from=2024-01-01\&filters=\[{%22channel%22:%22ticker%22}]) — available until **2025-12-17** Options ticker updates stream
* [openInterest](https://api.tardis.dev/v1/data-feeds/binance-european-options?from=2024-06-01\&filters=\[{%22channel%22:%22openInterest%22}]) — available until **2025-12-17** Options open interest updates stream
* [markPrice](https://api.tardis.dev/v1/data-feeds/binance-european-options?from=2024-06-01\&filters=\[{%22channel%22:%22markPrice%22}]) — available until **2025-12-17** Options mark price updates stream
* [!optionSymbol](https://api.tardis.dev/v1/data-feeds/binance-european-options?from=2026-03-01\&filters=\[{%22channel%22:%22!optionSymbol%22}]\&offset=0) — available since **2025-12-17** Option contract metadata and status updates stream
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for Binance European Options is located in GCP asia-northeast1 region (Tokyo, Japan).
Real-time market data is captured via **multiple WebSocket connections** to `wss://fstream.binance.com/public/stream`.
{% hint style="info" %}
Binance servers are located in AWS ap-northeast-1 region (Tokyo, Japan).
{% endhint %}
# Binance Spot
Binance historical market data details - currency pairs, data coverage and data collection specifics
Binance historical data for **high caps currency pairs** is available since **2019-03-30**, data for all currency pairs is available since **2021-03-05**.
{% embed url="" %}
See Binance 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | ------- | ---------- | ------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTCUSDT | 2019-12-01 | [Download sample](https://datasets.tardis.dev/v1/binance/incremental_book_L2/2019/12/01/BTCUSDT.csv.gz) |
| trades | BTCUSDT | 2019-12-01 | [Download sample](https://datasets.tardis.dev/v1/binance/trades/2019/12/01/BTCUSDT.csv.gz) |
| quotes | BTCUSDT | 2019-12-01 | [Download sample](https://datasets.tardis.dev/v1/binance/quotes/2019/12/01/BTCUSDT.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time Binance WebSocket API with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/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="binance",
from_date="2023-03-01",
to_date="2023-03-02",
filters=[Channel(name="depth", symbols=["btcusdt"])],
api_key="YOUR_API_KEY",
):
# messages as provided by Binance real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'binance',
from: '2023-03-01',
to: '2023-03-02',
filters: [{ channel: 'depth', symbols: ['btcusdt'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Binance real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/binance?from=2023-03-01&filters=[{"channel":"depth","symbols":["btcusdt"]}]&offset=0'
```
{% embed url="" %}
Example API response for Binance historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"binance","filters":[{"channel":"depth","symbols":["btcusdt"]}],"from":"2023-03-01","to":"2023-03-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See Binance WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [trade](https://api.tardis.dev/v1/data-feeds/binance?from=2024-01-01\&filters=\[{%22channel%22:%22trade%22}]) Public spot trade executions stream
* [depth](https://api.tardis.dev/v1/data-feeds/binance?from=2024-01-01\&filters=\[{%22channel%22:%22depth%22,%22symbols%22:\[%22btcusdt%22]}]) Incremental order book updates stream. Recorded with the fastest API cadence available at the time: until 2019-08-30 it was subscribed as `depth` (1000ms updates), after that as `depth@100ms` (100ms updates).
* [depthSnapshot](https://api.tardis.dev/v1/data-feeds/binance?from=2024-01-01\&filters=\[{%22channel%22:%22depthSnapshot%22,%22symbols%22:\[%22btcusdt%22]}]) — generated channel Binance real-time WebSocket API **does not provide initial order book snapshots**. To overcome this issue we fetch initial order book snapshots from REST API and store them together with the rest of the WebSocket messages — top 1000 levels. Such snapshot messages are marked with `"stream":"@depthSnapshot"` and `"generated":true` fields.
During data collection integrity of order book incremental updates is being **validated** using [sequence numbers](https://binance-docs.github.io/apidocs/spot/en/#how-to-manage-a-local-order-book-correctly) provided by real-time feed (`U` and `u` fields) — in case of detecting missed message WebSocket connection is being restarted. We also validate if initial book snapshot fetched from REST API overlaps with received `depth` messages.
* [bookTicker](https://api.tardis.dev/v1/data-feeds/binance?from=2024-01-01\&filters=\[{%22channel%22:%22bookTicker%22,%22symbols%22:\[%22btcusdt%22]}]) — available since **2019-09-21** Best bid and best ask updates stream
* [aggTrade](https://api.tardis.dev/v1/data-feeds/binance?from=2024-01-01\&filters=\[{%22channel%22:%22aggTrade%22}]) — available since **2019-11-19** Aggregated spot trade executions stream
* [ticker](https://api.tardis.dev/v1/data-feeds/binance?from=2024-01-01\&filters=\[{%22channel%22:%22ticker%22,%22symbols%22:\[%22btcusdt%22]}]) 24h spot ticker updates stream
* [borrowInterest](https://api.tardis.dev/v1/data-feeds/binance?from=2024-01-01\&filters=\[{%22channel%22:%22borrowInterest%22}]) — generated channel, available since **2021-02-23** Margin borrow interest snapshots stream. Polled from Binance margin REST endpoint about every minute. Messages are marked as `"stream":"@borrowInterest"` and `"generated":true`.
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for Binance **since 2020-05-18** is located in GCP asia-northeast1 region (Tokyo, Japan), before that it was located in GCP europe-west2 region (London, UK).
Real-time market data is captured via **multiple WebSocket connections** to `wss://stream.binance.com/stream?timeUnit=microsecond`.
{% hint style="info" %}
Binance servers are located in AWS ap-northeast-1 region (Tokyo, Japan).
{% endhint %}
# Binance US
Binance US historical market data details - currency pairs, data coverage and data collection specifics
Binance US exchange historical data for **all its currency pairs** is available since **2019-09-25**.
{% embed url="" %}
See Binance US 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | ------ | ---------- | --------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTCUSD | 2019-12-01 | [Download sample](https://datasets.tardis.dev/v1/binance-us/incremental_book_L2/2019/12/01/BTCUSD.csv.gz) |
| trades | BTCUSD | 2019-12-01 | [Download sample](https://datasets.tardis.dev/v1/binance-us/trades/2019/12/01/BTCUSD.csv.gz) |
| quotes | BTCUSD | 2019-12-01 | [Download sample](https://datasets.tardis.dev/v1/binance-us/quotes/2019/12/01/BTCUSD.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time Binance US WebSocket API with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/api/quickstart) that 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="binance-us",
from_date="2023-03-01",
to_date="2023-03-02",
filters=[Channel(name="depth", symbols=["btcusd"])],
api_key="YOUR_API_KEY",
):
# messages as provided by Binance US real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'binance-us',
from: '2023-03-01',
to: '2023-03-02',
filters: [{ channel: 'depth', symbols: ['btcusd'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Binance US real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/binance-us?from=2023-03-01&filters=[{"channel":"depth","symbols":["btcusd"]}]&offset=0'
```
{% embed url="" %}
Example API response for Binance US historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"binance-us","filters":[{"channel":"depth","symbols":["btcusd"]}],"from":"2023-03-01","to":"2023-03-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See Binance US WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [trade](https://api.tardis.dev/v1/data-feeds/binance-us?from=2024-01-01\&filters=\[{%22channel%22:%22trade%22,%22symbols%22:\[%22btcusdt%22]}]) Public spot trade executions stream
* [depth](https://api.tardis.dev/v1/data-feeds/binance-us?from=2024-01-01\&filters=\[{%22channel%22:%22depth%22,%22symbols%22:\[%22btcusdt%22]}]) Incremental order book updates stream subscribed as @depth\@100ms
* [depthSnapshot](https://api.tardis.dev/v1/data-feeds/binance-us?from=2024-01-01\&filters=\[{%22channel%22:%22depthSnapshot%22,%22symbols%22:\[%22btcusdt%22]}]) — generated Generated full order book snapshots stream. Binance.US real-time WebSocket API does not provide initial order book snapshots. To overcome this issue we fetch initial order book snapshots from REST API and store them together with the rest of the WebSocket messages (top 1000 levels). Snapshot messages are marked with `"stream":"@depthSnapshot"` and `"generated":true`.
During data collection, integrity of incremental order book updates is validated using sequence numbers from the real-time feed (U and u fields). If a missed message is detected, the WebSocket connection is restarted. Initial book snapshots fetched from REST API are also validated for overlap with received depth messages.
* [bookTicker](https://api.tardis.dev/v1/data-feeds/binance-us?from=2024-01-01\&filters=\[{%22channel%22:%22bookTicker%22,%22symbols%22:\[%22btcusdt%22]}]) Best bid and best ask updates stream
* [aggTrade](https://api.tardis.dev/v1/data-feeds/binance-us?from=2024-01-01\&filters=\[{%22channel%22:%22aggTrade%22,%22symbols%22:\[%22btcusdt%22]}]) — available since **2019-11-19** Aggregated spot trade executions stream
* [ticker](https://api.tardis.dev/v1/data-feeds/binance-us?from=2024-01-01\&filters=\[{%22channel%22:%22ticker%22,%22symbols%22:\[%22btcusdt%22]}]) 24h spot ticker updates stream
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for Binance US is located in GCP europe-west2 region (London, UK).
Real-time market data is captured via **multiple WebSocket connections** to `wss://stream.binance.us:9443/stream`.
{% hint style="info" %}
Binance.US servers are located in AWS us-east-1 region (N. Virginia, USA).
{% endhint %}
# OKX Futures
OKX Futures historical market data details - instruments, data coverage and data collection specifics
OKX historical data for **all its futures instruments** is available since **2019-03-30**.
{% embed url="" %}
See OKX Futures 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](/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-200103 | 2020-01-01 | [Download sample](https://datasets.tardis.dev/v1/okex-futures/incremental_book_L2/2020/01/01/BTC-USD-200103.csv.gz) |
| trades | BTC-USD-200103 | 2020-01-01 | [Download sample](https://datasets.tardis.dev/v1/okex-futures/trades/2020/01/01/BTC-USD-200103.csv.gz) |
| derivative\_ticker | BTC-USD-200103 | 2020-01-01 | [Download sample](https://datasets.tardis.dev/v1/okex-futures/derivative_ticker/2020/01/01/BTC-USD-200103.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](/downloadable-csv-files/overview) or official [client libs](/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-futures",
from_date="2024-01-01",
to_date="2024-01-02",
filters=[Channel(name="books", symbols=["BTC-USD-240329"])],
api_key="YOUR_API_KEY",
):
# messages as provided by OKX real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'okex-futures',
from: '2024-01-01',
to: '2024-01-02',
filters: [{ channel: 'books', symbols: ['BTC-USD-240329'] }],
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](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/okex-futures?from=2024-01-01&filters=[{"channel":"books","symbols":["BTC-USD-240329"]}]&offset=0'
```
{% embed url="" %}
Example API response for OKX Futures historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"okex-futures","filters":[{"channel":"books","symbols":["BTC-USD-240329"]}],"from":"2024-01-01","to":"2024-01-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See OKX Futures WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/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-futures?from=2024-01-01\&filters=\[{%22channel%22:%22trades%22}]) Public futures trade executions stream
* [trades-all](https://api.tardis.dev/v1/data-feeds/okex-futures?from=2024-01-01\&filters=\[{%22channel%22:%22trades-all%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-futures?from=2024-01-01\&filters=\[{%22channel%22:%22books-l2-tbt%22}]) — available until **2026-05-21** Tick-by-tick L2 futures order book updates
* [books](https://api.tardis.dev/v1/data-feeds/okex-futures?from=2024-01-01\&filters=\[{%22channel%22:%22books%22}]) — available from **2023-02-24** to **2024-07-19**, and from **2026-05-21** onward Incremental futures order book depth updates
* [bbo-tbt](https://api.tardis.dev/v1/data-feeds/okex-futures?from=2024-01-01\&filters=\[{%22channel%22:%22bbo-tbt%22}]) — available since **2022-05-05** Tick-by-tick best bid and offer updates
* [tickers](https://api.tardis.dev/v1/data-feeds/okex-futures?from=2024-01-01\&filters=\[{%22channel%22:%22tickers%22}]) 24h futures ticker updates
* [liquidations](https://api.tardis.dev/v1/data-feeds/okex-futures?from=2024-01-01\&filters=\[{%22channel%22:%22liquidations%22}]) Liquidation events with at most one update per second per contract
* [liquidation-orders](https://api.tardis.dev/v1/data-feeds/okex-futures?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-futures?from=2024-01-01\&filters=\[{%22channel%22:%22open-interest%22}]) Open interest updates
* [mark-price](https://api.tardis.dev/v1/data-feeds/okex-futures?from=2024-01-01\&filters=\[{%22channel%22:%22mark-price%22}]) Mark price updates with keepalive up to 10s when unchanged
* [index-tickers](https://api.tardis.dev/v1/data-feeds/okex-futures?from=2024-01-01\&filters=\[{%22channel%22:%22index-tickers%22}]) Index ticker updates with keepalive up to 1m when unchanged
* [funding-rate](https://api.tardis.dev/v1/data-feeds/okex-futures?from=2026-09-01\&filters=\[{%22channel%22:%22funding-rate%22}]) — available since **2026-08-05** for X-Perp futures Funding rate updates for X-Perp futures with upcoming funding time (30s to 90s cadence); source for normalized `derivative_ticker` messages
* [price-limit](https://api.tardis.dev/v1/data-feeds/okex-futures?from=2024-01-01\&filters=\[{%22channel%22:%22price-limit%22}]) Price limit updates
* [status](https://api.tardis.dev/v1/data-feeds/okex-futures?from=2024-01-01\&filters=\[{%22channel%22:%22status%22}]) Exchange status and maintenance notifications
* [instruments](https://api.tardis.dev/v1/data-feeds/okex-futures?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-futures?from=2024-01-01\&filters=\[{%22channel%22:%22long-short-account-ratio%22}]) — generated channel Long/short account ratio snapshots from REST statistics endpoint (1m). From **2023-06-09 15:30 UTC** to **2026-08-04 11:16 UTC**, updates occurred at varying intervals longer than the documented 1m.
* [taker-volume](https://api.tardis.dev/v1/data-feeds/okex-futures?from=2024-01-01\&filters=\[{%22channel%22:%22taker-volume%22}]) — generated channel Taker buy/sell volume snapshots from REST statistics endpoint (1m). From **2023-06-09 15:30 UTC** to **2026-08-04 11:16 UTC**, updates occurred at varying intervals longer than the documented 1m.
* [estimated-price](https://api.tardis.dev/v1/data-feeds/okex-futures?from=2024-01-01\&filters=\[{%22channel%22:%22estimated-price%22}]) Estimated delivery/settlement price updates
* [public-block-trades](https://api.tardis.dev/v1/data-feeds/okex-futures?from=2024-01-01\&filters=\[{%22channel%22:%22public-block-trades%22}]) — available since **2023-01-01** Public block trades stream
* [public-struc-block-trades](https://api.tardis.dev/v1/data-feeds/okex-futures?from=2024-01-01\&filters=\[{%22channel%22:%22public-struc-block-trades%22}]) — available since **2023-01-01** Public structured block trades stream
* [taker-volume-contract](https://api.tardis.dev/v1/data-feeds/okex-futures?from=2024-09-01\&filters=\[{%22channel%22:%22taker-volume-contract%22}]) — generated channel, available since **2024-08-08** Contract-level taker buy/sell volume snapshots from REST statistics endpoint
* [long-short-account-ratio-contract-top-trader](https://api.tardis.dev/v1/data-feeds/okex-futures?from=2024-09-01\&filters=\[{%22channel%22:%22long-short-account-ratio-contract-top-trader%22}]) — generated channel, available since **2024-08-08** Contract-level top-trader long/short account ratio snapshots from REST statistics endpoint
* [long-short-position-ratio-contract-top-trader](https://api.tardis.dev/v1/data-feeds/okex-futures?from=2024-09-01\&filters=\[{%22channel%22:%22long-short-position-ratio-contract-top-trader%22}]) — generated channel, available since **2024-08-08** Contract-level top-trader long/short position ratio snapshots from REST statistics endpoint
* [long-short-account-ratio-contract](https://api.tardis.dev/v1/data-feeds/okex-futures?from=2024-09-01\&filters=\[{%22channel%22:%22long-short-account-ratio-contract%22}]) — generated channel, available since **2024-08-08** Contract-level long/short account ratio snapshots from REST statistics endpoint
**Legacy channels (API v3, until 2021-12-23):**
* [futures/trade](https://api.tardis.dev/v1/data-feeds/okex-futures?from=2019-12-01\&filters=\[{%22channel%22:%22futures/trade%22}]) Public futures trade executions stream
* [futures/depth](https://api.tardis.dev/v1/data-feeds/okex-futures?from=2019-12-01\&filters=\[{%22channel%22:%22futures/depth%22}]) — available **until 2020-01-29** Incremental futures order book updates (legacy depth channel)
* [futures/depth\_l2\_tbt](https://api.tardis.dev/v1/data-feeds/okex-futures?from=2020-01-01\&filters=\[{%22channel%22:%22futures/depth_l2_tbt%22,%22symbols%22:\[%22BTC-USD-200103%22]}]) — available since **2019-12-03** Tick-by-tick L2 futures order book updates with sequencing
* [futures/ticker](https://api.tardis.dev/v1/data-feeds/okex-futures?from=2020-01-01\&filters=\[{%22channel%22:%22futures/ticker%22,%22symbols%22:\[%22BTC-USD-200103%22]}]) 24h futures ticker updates
* [futures/liquidation](https://api.tardis.dev/v1/data-feeds/okex-futures?from=2021-01-01\&filters=\[{%22channel%22:%22futures/liquidation%22}]) — available since **2020-12-17** Futures liquidation events
* [futures/mark\_price](https://api.tardis.dev/v1/data-feeds/okex-futures?from=2020-01-01\&filters=\[{%22channel%22:%22futures/mark_price%22,%22symbols%22:\[%22BTC-USD-200103%22]}]) Mark price with keepalive up to 10s when unchanged
* [index/ticker](https://api.tardis.dev/v1/data-feeds/okex-futures?from=2020-01-01\&filters=\[{%22channel%22:%22index/ticker%22}]) — available since **2019-09-20** Index ticker for futures contracts with keepalive up to 1m when unchanged
* [system/status](https://api.tardis.dev/v1/data-feeds/okex-futures?from=2020-08-01\&filters=\[{%22channel%22:%22system/status%22}]) — available since **2020-07-01** Exchange status and maintenance notifications
* [information/sentiment](https://api.tardis.dev/v1/data-feeds/okex-futures?from=2021-01-01\&filters=\[{%22channel%22:%22information/sentiment%22}]) — generated channel, available since **2020-10-28** Market sentiment ratio metrics
* [information/long\_short\_ratio](https://api.tardis.dev/v1/data-feeds/okex-futures?from=2021-01-01\&filters=\[{%22channel%22:%22information/long_short_ratio%22}]) — generated channel, available since **2020-10-28** Long/short account ratio metrics
* [information/margin](https://api.tardis.dev/v1/data-feeds/okex-futures?from=2021-01-01\&filters=\[{%22channel%22:%22information/margin%22}]) — generated channel, available since **2020-10-28** Margin ratio metrics
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for OKX Futures is located in GCP asia-northeast1 region (Tokyo, Japan) since **2026-05-21**. Before that, from **2022-05-04**, it was located in AWS HK region (Hong Kong, China, VPC colo setup), before that, since **2020-05-15** it was located in GCP asia-northeast1 region (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://ws.okx.com:8443/ws/v5/public`. Before **2026-05-21**, data was captured from the OKX colocation endpoint at `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 %}
# OKX Swap
OKX Swap historical market data details - instruments, data coverage and data collection specifics
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](/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](/downloadable-csv-files/overview) or official [client libs](/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", 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](/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', 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](/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","symbols":["BTC-USD-SWAP"]}]&offset=0'
```
{% embed url="" %}
Example API response for OKX Swap historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"okex-swap","filters":[{"channel":"books","symbols":["BTC-USD-SWAP"]}],"from":"2024-01-01","to":"2024-01-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/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](/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]}]) — available until **2026-05-21** 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 from **2023-02-24** to **2024-07-19**, and from **2026-05-21** onward 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). From **2023-06-09 15:30 UTC** to **2026-08-04 11:16 UTC**, updates occurred at varying intervals longer than the documented 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). From **2023-06-09 15:30 UTC** to **2026-08-04 11:16 UTC**, updates occurred at varying intervals longer than the documented 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](/faq/general#what-is-your-infrastructure-setup) for OKX Swap is located in GCP asia-northeast1 region (Tokyo, Japan) since **2026-05-21**. Before that, from **2022-05-04**T16:45, it was 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://ws.okx.com:8443/ws/v5/public`. Before **2026-05-21**, data was captured from the OKX colocation endpoint at `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 %}
# OKX Options
OKX Options historical market data details - instruments, data coverage and data collection specifics
OKX historical data for **all its options instruments** is available since **2020-02-01**.
{% embed url="" %}
See OKX Options 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | --------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTC-USD-200327-8500-P | 2020-03-01 | [Download sample](https://datasets.tardis.dev/v1/okex-options/incremental_book_L2/2020/03/01/BTC-USD-200327-8500-P.csv.gz) |
| trades | BTC-USD-200327-8500-P | 2020-03-01 | [Download sample](https://datasets.tardis.dev/v1/okex-options/trades/2020/03/01/BTC-USD-200327-8500-P.csv.gz) |
| options\_chain | OPTIONS | 2020-03-01 | [Download sample](https://datasets.tardis.dev/v1/okex-options/options_chain/2020/03/01/OPTIONS.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](/downloadable-csv-files/overview) or official [client libs](/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-options",
from_date="2024-01-01",
to_date="2024-01-02",
filters=[Channel(name="books", symbols=[])],
api_key="YOUR_API_KEY",
):
# messages as provided by OKX real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'okex-options',
from: '2024-01-01',
to: '2024-01-02',
filters: [{ channel: 'books', symbols: [] }],
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](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/okex-options?from=2024-01-01&filters=[{"channel":"books","symbols":[]}]&offset=0'
```
{% embed url="" %}
Example API response for OKX Options historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"okex-options","filters":[{"channel":"books","symbols":[]}],"from":"2024-01-01","to":"2024-01-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See OKX Options WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/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-options?from=2024-01-01\&filters=\[{%22channel%22:%22trades%22}]) Public options trade executions stream
* [trades-all](https://api.tardis.dev/v1/data-feeds/okex-options?from=2024-01-01\&filters=\[{%22channel%22:%22trades-all%22}]) — available since **2023-10-19** All trades stream including non-aggregated trade messages
* [option-trades](https://api.tardis.dev/v1/data-feeds/okex-options?from=2024-01-01\&filters=\[{%22channel%22:%22option-trades%22}]) — available since **2023-03-30** Option trades stream
* [books-l2-tbt](https://api.tardis.dev/v1/data-feeds/okex-options?from=2024-01-01\&filters=\[{%22channel%22:%22books-l2-tbt%22}]) — available until **2026-05-21** Tick-by-tick L2 options order book updates
* [books](https://api.tardis.dev/v1/data-feeds/okex-options?from=2024-01-01\&filters=\[{%22channel%22:%22books%22}]) — available from **2023-02-24** to **2024-07-19**, and from **2026-05-21** onward Incremental options order book depth updates
* [bbo-tbt](https://api.tardis.dev/v1/data-feeds/okex-options?from=2024-01-01\&filters=\[{%22channel%22:%22bbo-tbt%22}]) — available since **2022-05-05** Tick-by-tick best bid and offer updates
* [tickers](https://api.tardis.dev/v1/data-feeds/okex-options?from=2024-01-01\&filters=\[{%22channel%22:%22tickers%22}]) 24h options ticker updates
* [opt-summary](https://api.tardis.dev/v1/data-feeds/okex-options?from=2024-01-01\&filters=\[{%22channel%22:%22opt-summary%22}]) Option summary with greeks, implied volatility and contract statistics
* [index-tickers](https://api.tardis.dev/v1/data-feeds/okex-options?from=2024-01-01\&filters=\[{%22channel%22:%22index-tickers%22}]) Index ticker updates with keepalive up to 1m when unchanged
* [open-interest](https://api.tardis.dev/v1/data-feeds/okex-options?from=2024-01-01\&filters=\[{%22channel%22:%22open-interest%22}]) Open interest updates
* [mark-price](https://api.tardis.dev/v1/data-feeds/okex-options?from=2024-01-01\&filters=\[{%22channel%22:%22mark-price%22}]) Mark price updates with keepalive up to 10s when unchanged
* [status](https://api.tardis.dev/v1/data-feeds/okex-options?from=2024-01-01\&filters=\[{%22channel%22:%22status%22}]) Exchange status and maintenance notifications
* [instruments](https://api.tardis.dev/v1/data-feeds/okex-options?from=2024-01-01\&filters=\[{%22channel%22:%22instruments%22}]) Instrument state updates (listing, suspension, parameter changes)
* [price-limit](https://api.tardis.dev/v1/data-feeds/okex-options?from=2024-01-01\&filters=\[{%22channel%22:%22price-limit%22}]) Price limit updates
* [estimated-price](https://api.tardis.dev/v1/data-feeds/okex-options?from=2024-01-01\&filters=\[{%22channel%22:%22estimated-price%22}]) Estimated delivery/settlement price updates
* [public-block-trades](https://api.tardis.dev/v1/data-feeds/okex-options?from=2024-01-01\&filters=\[{%22channel%22:%22public-block-trades%22}]) — available since **2023-01-01** Public block trades stream
* [public-struc-block-trades](https://api.tardis.dev/v1/data-feeds/okex-options?from=2024-01-01\&filters=\[{%22channel%22:%22public-struc-block-trades%22}]) — available since **2023-01-01** Public structured block trades stream
**Legacy channels (API v3, until 2021-12-23):**
* [option/trade](https://api.tardis.dev/v1/data-feeds/okex-options?from=2021-01-01\&filters=\[{%22channel%22:%22option/trade%22}]) — available until **2021-12-23** Public options trade executions stream
* [option/trades](https://api.tardis.dev/v1/data-feeds/okex-options?from=2021-01-01\&filters=\[{%22channel%22:%22option/trades%22}]) — available since **2020-07-30**, until **2021-12-23** Public options trade executions stream
* [option/depth](https://api.tardis.dev/v1/data-feeds/okex-options?from=2020-02-01\&filters=\[{%22channel%22:%22option/depth%22}]) — available until **2020-02-13** Incremental options order book updates (legacy depth channel)
* [option/depth\_l2\_tbt](https://api.tardis.dev/v1/data-feeds/okex-options?from=2021-01-01\&filters=\[{%22channel%22:%22option/depth_l2_tbt%22}]) — available since **2020-02-07**, until **2021-12-23** Tick-by-tick L2 options order book updates with sequencing
* [option/ticker](https://api.tardis.dev/v1/data-feeds/okex-options?from=2021-01-01\&filters=\[{%22channel%22:%22option/ticker%22}]) — available until **2021-12-23** 24h options ticker updates
* [option/summary](https://api.tardis.dev/v1/data-feeds/okex-options?from=2021-01-01\&filters=\[{%22channel%22:%22option/summary%22}]) — available until **2021-12-23** Option summary with greeks, implied volatility and contract statistics
* [index/ticker](https://api.tardis.dev/v1/data-feeds/okex-options?from=2021-01-01\&filters=\[{%22channel%22:%22index/ticker%22}]) — available since **2020-06-08**, until **2021-12-23** Index ticker for options contracts with keepalive up to 1m when unchanged
* [option/instruments](https://api.tardis.dev/v1/data-feeds/okex-options?from=2021-01-01\&filters=\[{%22channel%22:%22option/instruments%22}]) — available until **2021-12-23** Option instruments metadata updates (listing, expiry, contract parameter changes)
* [system/status](https://api.tardis.dev/v1/data-feeds/okex-options?from=2021-01-01\&filters=\[{%22channel%22:%22system/status%22}]) — available since **2020-07-01**, until **2021-12-23** Exchange status and maintenance notifications
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for OKX Options is located in GCP asia-northeast1 region (Tokyo, Japan) since **2026-05-21**. Before that, from **2022-05-04**, it was located in AWS HK region (Hong Kong, China, VPC colo setup), before that, since **2020-05-15** it was located in GCP asia-northeast1 region (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://ws.okx.com:8443/ws/v5/public`. Before **2026-05-21**, data was captured from the OKX colocation endpoint at `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 %}
# OKX Spot
OKX Spot historical market data details - currency pairs, data coverage and data collection specifics
OKX historical data for **spot high caps currency pairs** is available since **2019-03-30**, data for all spot currency pairs is available since **2021-03-11**.
{% embed url="" %}
See OKX Spot 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | -------- | ---------- | ----------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTC-USDT | 2020-01-01 | [Download sample](https://datasets.tardis.dev/v1/okex/incremental_book_L2/2020/01/01/BTC-USDT.csv.gz) |
| trades | BTC-USDT | 2020-01-01 | [Download sample](https://datasets.tardis.dev/v1/okex/trades/2020/01/01/BTC-USDT.csv.gz) |
| quotes | BTC-USDT | 2020-01-01 | [Download sample](https://datasets.tardis.dev/v1/okex/quotes/2020/01/01/BTC-USDT.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](/downloadable-csv-files/overview) or official [client libs](/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",
from_date="2024-01-01",
to_date="2024-01-02",
filters=[Channel(name="books", symbols=["BTC-USDT"])],
api_key="YOUR_API_KEY",
):
# messages as provided by OKX real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'okex',
from: '2024-01-01',
to: '2024-01-02',
filters: [{ channel: 'books', symbols: ['BTC-USDT'] }],
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](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/okex?from=2024-01-01&filters=[{"channel":"books","symbols":["BTC-USDT"]}]&offset=0'
```
{% embed url="" %}
Example API response for OKX Spot historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"okex","filters":[{"channel":"books","symbols":["BTC-USDT"]}],"from":"2024-01-01","to":"2024-01-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See OKX Spot WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/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?from=2024-01-01\&filters=\[{%22channel%22:%22trades%22}]) Public spot trade executions stream
* [trades-all](https://api.tardis.dev/v1/data-feeds/okex?from=2024-01-01\&filters=\[{%22channel%22:%22trades-all%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?from=2024-01-01\&filters=\[{%22channel%22:%22books-l2-tbt%22}]) — available until **2026-05-21** Tick-by-tick L2 spot order book updates
* [books](https://api.tardis.dev/v1/data-feeds/okex?from=2024-01-01\&filters=\[{%22channel%22:%22books%22}]) — available from **2023-02-24** to **2024-07-19**, and from **2026-05-21** onward Incremental spot order book depth updates
* [bbo-tbt](https://api.tardis.dev/v1/data-feeds/okex?from=2024-01-01\&filters=\[{%22channel%22:%22bbo-tbt%22}]) — available since **2022-05-05** Tick-by-tick best bid and offer updates
* [tickers](https://api.tardis.dev/v1/data-feeds/okex?from=2024-01-01\&filters=\[{%22channel%22:%22tickers%22}]) 24h spot ticker updates
* [interest-rate-loan-quota](https://api.tardis.dev/v1/data-feeds/okex?from=2024-01-01\&filters=\[{%22channel%22:%22interest-rate-loan-quota%22}]) — generated channel Public interest rate and loan quota snapshots from REST endpoint
* [vip-interest-rate-loan-quota](https://api.tardis.dev/v1/data-feeds/okex?from=2024-01-01\&filters=\[{%22channel%22:%22vip-interest-rate-loan-quota%22}]) — generated channel VIP interest rate and loan quota snapshots from REST endpoint
* [status](https://api.tardis.dev/v1/data-feeds/okex?from=2024-01-01\&filters=\[{%22channel%22:%22status%22}]) Exchange status and maintenance notifications
* [instruments](https://api.tardis.dev/v1/data-feeds/okex?from=2024-01-01\&filters=\[{%22channel%22:%22instruments%22}]) Instrument state updates (listing, suspension, parameter changes)
* [taker-volume](https://api.tardis.dev/v1/data-feeds/okex?from=2024-01-01\&filters=\[{%22channel%22:%22taker-volume%22}]) — generated channel Taker buy/sell volume snapshots from REST statistics endpoint (1m). From **2023-06-09 15:30 UTC** to **2026-08-04 11:16 UTC**, updates occurred at varying intervals longer than the documented 1m.
* [liquidations](https://api.tardis.dev/v1/data-feeds/okex?from=2024-01-01\&filters=\[{%22channel%22:%22liquidations%22}]) — generated channel Margin liquidation events from REST liquidation orders endpoint
* [public-block-trades](https://api.tardis.dev/v1/data-feeds/okex?from=2024-01-01\&filters=\[{%22channel%22:%22public-block-trades%22}]) — available since **2023-01-01** Public block trades stream
* [public-struc-block-trades](https://api.tardis.dev/v1/data-feeds/okex?from=2024-01-01\&filters=\[{%22channel%22:%22public-struc-block-trades%22}]) — available since **2023-01-01** Public structured block trades stream
* [loan-ratio](https://api.tardis.dev/v1/data-feeds/okex?from=2024-01-01\&filters=\[{%22channel%22:%22loan-ratio%22}]) — generated channel Margin loan ratio snapshots from REST statistics endpoint (1m). From **2023-06-09 15:30 UTC** to **2026-08-04 11:16 UTC**, updates occurred at varying intervals longer than the documented 1m.
**Legacy channels (API v3, until 2021-12-23):**
* [spot/trade](https://api.tardis.dev/v1/data-feeds/okex?from=2021-01-01\&filters=\[{%22channel%22:%22spot/trade%22}]) Public spot trade executions stream
* [spot/depth](https://api.tardis.dev/v1/data-feeds/okex?from=2020-01-01\&filters=\[{%22channel%22:%22spot/depth%22}]) — available until **2020-04-11** Incremental spot order book updates (legacy depth channel)
* [spot/depth\_l2\_tbt](https://api.tardis.dev/v1/data-feeds/okex?from=2021-01-01\&filters=\[{%22channel%22:%22spot/depth_l2_tbt%22}]) — available since **2020-04-09** Tick-by-tick L2 spot order book updates with sequencing
* [spot/ticker](https://api.tardis.dev/v1/data-feeds/okex?from=2021-01-01\&filters=\[{%22channel%22:%22spot/ticker%22}]) 24h spot ticker updates
* [system/status](https://api.tardis.dev/v1/data-feeds/okex?from=2021-01-01\&filters=\[{%22channel%22:%22system/status%22}]) — available since **2020-07-01** Exchange status and maintenance notifications
* [margin/interest\_rate](https://api.tardis.dev/v1/data-feeds/okex?from=2021-06-01\&filters=\[{%22channel%22:%22margin/interest_rate%22}]) — available since **2021-02-24** Margin interest rate updates
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for OKX Spot is located in GCP asia-northeast1 region (Tokyo, Japan) since **2026-05-21**. Before that, from **2022-05-04**, it was located in AWS HK region (Hong Kong, China, VPC colo setup), before that, since **2020-05-15** it was located in GCP asia-northeast1 region (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://ws.okx.com:8443/ws/v5/public`. Before **2026-05-21**, data was captured from the OKX colocation endpoint at `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 %}
# OKX Nitro Spreads
OKX Nitro Spreads historical market data details - instruments, data coverage and data collection specifics
OKX Nitro Spreads historical data for **all its instruments** is available since **2023-12-22**.
{% embed url="" %}
See OKX Nitro Spreads 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | ----------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTC-USDT\_BTC-USDT-SWAP | 2024-01-01 | [Download sample](https://datasets.tardis.dev/v1/okex-spreads/incremental_book_L2/2024/01/01/BTC-USDT_BTC-USDT-SWAP.csv.gz) |
| trades | BTC-USDT\_BTC-USDT-SWAP | 2024-01-01 | [Download sample](https://datasets.tardis.dev/v1/okex-spreads/trades/2024/01/01/BTC-USDT_BTC-USDT-SWAP.csv.gz) |
| quotes | BTC-USDT\_BTC-USDT-SWAP | 2024-01-01 | [Download sample](https://datasets.tardis.dev/v1/okex-spreads/quotes/2024/01/01/BTC-USDT_BTC-USDT-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. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/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-spreads",
from_date="2024-01-01",
to_date="2024-01-02",
filters=[Channel(name="sprd-books5", symbols=[])],
api_key="YOUR_API_KEY",
):
# messages as provided by OKX real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'okex-spreads',
from: '2024-01-01',
to: '2024-01-02',
filters: [{ channel: 'sprd-books5', symbols: [] }],
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](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/okex-spreads?from=2024-01-01&filters=[{"channel":"sprd-books5","symbols":[]}]&offset=0'
```
{% embed url="" %}
Example API response for OKX Nitro Spreads historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"okex-spreads","filters":[{"channel":"sprd-books5","symbols":[]}],"from":"2024-01-01","to":"2024-01-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See OKX Nitro Spreads WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [sprd-public-trades](https://api.tardis.dev/v1/data-feeds/okex-spreads?from=2024-01-01\&filters=\[{%22channel%22:%22sprd-public-trades%22}]) Public spread trade executions stream
* [sprd-books5](https://api.tardis.dev/v1/data-feeds/okex-spreads?from=2024-01-01\&filters=\[{%22channel%22:%22sprd-books5%22}]) Spread order book depth updates
* [sprd-bbo-tbt](https://api.tardis.dev/v1/data-feeds/okex-spreads?from=2024-01-01\&filters=\[{%22channel%22:%22sprd-bbo-tbt%22}]) Tick-by-tick best bid and offer updates
* [sprd-tickers](https://api.tardis.dev/v1/data-feeds/okex-spreads?from=2024-01-01\&filters=\[{%22channel%22:%22sprd-tickers%22}]) 24h spread ticker updates
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for OKX Nitro Spreads is located in GCP asia-northeast1 region (Tokyo, Japan) since **2026-05-21**. Before that, it was located in AWS ap-east-1 region (Hong Kong, China, VPC colo setup).
Real-time market data is captured via **multiple WebSocket connections** to `wss://ws.okx.com:8443/ws/v5/business`. Before **2026-05-21**, data was captured from the OKX colocation endpoint at `wss://awscolows1.okx.com:8443/ws/v5/business`.
{% hint style="info" %}
OKX servers are located in Alibaba Cloud cn-hongkong region (Hong Kong, China).
{% endhint %}
# Coinbase Exchange
Coinbase Exchange historical market data details - currency pairs, data coverage and data collection specifics
{% hint style="info" %}
Coinbase Exchange market data is subject to Coinbase market data license restrictions.
See the applicable [Coinbase market data license restrictions](https://docs.tardis.dev/historical-data-details/pages/-LkYDB4Q2h9uctu9Kq7Y#id-23.-coinbase-market-data-license-restrictions).
{% endhint %}
Coinbase Exchange historical data for **all its currency pairs** is available since **2019-03-30**.
{% embed url="" %}
See Coinbase Exchange 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | ------- | ---------- | -------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTC-USD | 2019-07-01 | [Download sample](https://datasets.tardis.dev/v1/coinbase/incremental_book_L2/2019/07/01/BTC-USD.csv.gz) |
| trades | BTC-USD | 2019-07-01 | [Download sample](https://datasets.tardis.dev/v1/coinbase/trades/2019/07/01/BTC-USD.csv.gz) |
| quotes | BTC-USD | 2019-07-01 | [Download sample](https://datasets.tardis.dev/v1/coinbase/quotes/2019/07/01/BTC-USD.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time Coinbase Exchange WebSocket API with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/api/quickstart) that 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="coinbase",
from_date="2024-01-01",
to_date="2024-01-02",
filters=[Channel(name="l2update", symbols=["BTC-USD"])],
api_key="YOUR_API_KEY",
):
# messages as provided by Coinbase Exchange real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'coinbase',
from: '2024-01-01',
to: '2024-01-02',
filters: [{ channel: 'l2update', symbols: ['BTC-USD'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Coinbase Exchange real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/coinbase?from=2024-01-01&filters=[{"channel":"l2update","symbols":["BTC-USD"]}]&offset=0'
```
{% embed url="" %}
Example API response for Coinbase Exchange historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"coinbase","filters":[{"channel":"l2update","symbols":["BTC-USD"]}],"from":"2024-01-01","to":"2024-01-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See Coinbase Exchange WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [match](https://api.tardis.dev/v1/data-feeds/coinbase?from=2024-01-01\&filters=\[{%22channel%22:%22match%22}]) Trade match events from the matches channel
* [l2update](https://api.tardis.dev/v1/data-feeds/coinbase?from=2024-01-01\&filters=\[{%22channel%22:%22l2update%22}]) Level 2 order book updates
* [snapshot](https://api.tardis.dev/v1/data-feeds/coinbase?from=2024-01-01\&filters=\[{%22channel%22:%22snapshot%22}]) Level 2 order book snapshots
* [ticker](https://api.tardis.dev/v1/data-feeds/coinbase?from=2024-01-01\&filters=\[{%22channel%22:%22ticker%22}]) Ticker updates with last trade and best bid and ask
* [subscriptions](https://api.tardis.dev/v1/data-feeds/coinbase?from=2024-01-01\&filters=\[{%22channel%22:%22subscriptions%22}]) Subscription acknowledgements stream
* [received](https://api.tardis.dev/v1/data-feeds/coinbase?from=2024-01-01\&filters=\[{%22channel%22:%22received%22}]) Order received events from the full channel
* [open](https://api.tardis.dev/v1/data-feeds/coinbase?from=2024-01-01\&filters=\[{%22channel%22:%22open%22}]) Order open events from the full channel
* [done](https://api.tardis.dev/v1/data-feeds/coinbase?from=2024-01-01\&filters=\[{%22channel%22:%22done%22}]) Order done and cancel events from the full channel
* [change](https://api.tardis.dev/v1/data-feeds/coinbase?from=2024-01-01\&filters=\[{%22channel%22:%22change%22}]) Order change events from the full channel
* [last\_match](https://api.tardis.dev/v1/data-feeds/coinbase?from=2024-01-01\&filters=\[{%22channel%22:%22last_match%22}]) Most recent trade included with ticker updates
* [full\_snapshot](https://api.tardis.dev/v1/data-feeds/coinbase?from=2024-01-01\&filters=\[{%22channel%22:%22full_snapshot%22,%22symbols%22:\[%22BTC-USD%22]}]) — generated channel Generated full order book L3 snapshots stream. Coinbase full channel does not provide initial snapshots, so snapshots are fetched from REST API and emitted as `"type":"full_snapshot"` with `"generated":true`. This enables historical full (L3) order book reconstruction and sequence-overlap validation against websocket full updates (enabled since 2020-06-11).
* [rfq\_matches](https://api.tardis.dev/v1/data-feeds/coinbase?from=2024-01-01\&filters=\[{%22channel%22:%22rfq_matches%22}]) RFQ match events stream
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for Coinbase Exchange is located in GCP europe-west2 region (London, UK).
Real-time market data is captured via **multiple WebSocket connections** to `wss://ws-direct.exchange.coinbase.com`.
{% hint style="info" %}
Coinbase Exchange servers are located in AWS us-east-1 region (N. Virginia, USA).
{% endhint %}
# Coinbase International
Coinbase International historical market data details - instruments, data coverage and data collection specifics
{% hint style="info" %}
Coinbase International market data is subject to Coinbase market data license restrictions.
See the applicable [Coinbase market data license restrictions](https://docs.tardis.dev/historical-data-details/pages/-LkYDB4Q2h9uctu9Kq7Y#id-23.-coinbase-market-data-license-restrictions).
{% endhint %}
Coinbase International historical data for **all its instruments** is available since **2024-10-31**.
{% embed url="" %}
See Coinbase International 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTC-PERP | 2025-01-01 | [Download sample](https://datasets.tardis.dev/v1/coinbase-international/incremental_book_L2/2025/01/01/BTC-PERP.csv.gz) |
| trades | BTC-PERP | 2025-01-01 | [Download sample](https://datasets.tardis.dev/v1/coinbase-international/trades/2025/01/01/BTC-PERP.csv.gz) |
| derivative\_ticker | BTC-PERP | 2025-01-01 | [Download sample](https://datasets.tardis.dev/v1/coinbase-international/derivative_ticker/2025/01/01/BTC-PERP.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time Coinbase International WebSocket API with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/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="coinbase-international",
from_date="2024-11-01",
to_date="2024-11-02",
filters=[Channel(name="LEVEL2", symbols=["BTC-PERP"])],
api_key="YOUR_API_KEY",
):
# messages as provided by Coinbase International real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'coinbase-international',
from: '2024-11-01',
to: '2024-11-02',
filters: [{ channel: 'LEVEL2', symbols: ['BTC-PERP'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Coinbase International real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/coinbase-international?from=2024-11-01&filters=[{"channel":"LEVEL2","symbols":["BTC-PERP"]}]&offset=0'
```
{% embed url="" %}
Example API response for Coinbase International historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"coinbase-international","filters":[{"channel":"LEVEL2","symbols":["BTC-PERP"]}],"from":"2024-11-01","to":"2024-11-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See Coinbase International WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [MATCH](https://api.tardis.dev/v1/data-feeds/coinbase-international?from=2025-01-01\&filters=\[{%22channel%22:%22MATCH%22}]) Trade match events stream
* [LEVEL2](https://api.tardis.dev/v1/data-feeds/coinbase-international?from=2025-01-01\&filters=\[{%22channel%22:%22LEVEL2%22,%22symbols%22:\[%22BTC-PERP%22]}]) Order book snapshots and deltas
* [LEVEL1](https://api.tardis.dev/v1/data-feeds/coinbase-international?from=2025-01-01\&filters=\[{%22channel%22:%22LEVEL1%22,%22symbols%22:\[%22BTC-PERP%22]}]) Top of book bid and ask updates
* [FUNDING](https://api.tardis.dev/v1/data-feeds/coinbase-international?from=2025-01-01\&filters=\[{%22channel%22:%22FUNDING%22}]) Funding rate and next funding time updates
* [RISK](https://api.tardis.dev/v1/data-feeds/coinbase-international?from=2025-01-01\&filters=\[{%22channel%22:%22RISK%22}]) Risk parameter updates
* [INSTRUMENTS](https://api.tardis.dev/v1/data-feeds/coinbase-international?from=2025-01-01\&filters=\[{%22channel%22:%22INSTRUMENTS%22}]) Instrument metadata and trading state updates
* [CANDLES\_ONE\_MINUTE](https://api.tardis.dev/v1/data-feeds/coinbase-international?from=2025-01-01\&filters=\[{%22channel%22:%22CANDLES_ONE_MINUTE%22}]) One minute candle updates
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for Coinbase International is located in GCP asia-northeast1 region (Tokyo, Japan).
Real-time market data is captured via **multiple WebSocket connections** to `wss://ws-md.international.coinbase.com`.
{% hint style="info" %}
Coinbase International servers are located in AWS ap-northeast-1 region (Tokyo, Japan).
{% endhint %}
# BitMEX
BitMEX historical market data details - available data, coverage and data collection specifics
BitMEX historical data for **all its instruments** is available since **2019-03-30**.
{% embed url="" %}
See BitMEX 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | ------ | ---------- | ----------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | XBTUSD | 2019-07-01 | [Download sample](https://datasets.tardis.dev/v1/bitmex/incremental_book_L2/2019/07/01/XBTUSD.csv.gz) |
| trades | XBTUSD | 2019-07-01 | [Download sample](https://datasets.tardis.dev/v1/bitmex/trades/2019/07/01/XBTUSD.csv.gz) |
| derivative\_ticker | XBTUSD | 2019-07-01 | [Download sample](https://datasets.tardis.dev/v1/bitmex/derivative_ticker/2019/07/01/XBTUSD.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time BitMEX WebSocket API with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/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="bitmex",
from_date="2023-03-01",
to_date="2023-03-02",
filters=[Channel(name="orderBookL2_25", symbols=["XBTUSD"])],
api_key="YOUR_API_KEY",
):
# messages as provided by BitMEX real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'bitmex',
from: '2023-03-01',
to: '2023-03-02',
filters: [{ channel: 'orderBookL2_25', symbols: ['XBTUSD'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by BitMEX real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/bitmex?from=2023-03-01&filters=[{"channel":"orderBookL2_25","symbols":["XBTUSD"]}]&offset=0'
```
{% embed url="" %}
Example API response for BitMEX historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"bitmex","filters":[{"channel":"orderBookL2_25","symbols":["XBTUSD"]}],"from":"2023-03-01","to":"2023-03-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See BitMEX WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [trade](https://api.tardis.dev/v1/data-feeds/bitmex?from=2024-01-01\&filters=\[{%22channel%22:%22trade%22,%22symbols%22:\[%22XBTUSD%22]}]) Public trade executions stream
* [orderBookL2](https://api.tardis.dev/v1/data-feeds/bitmex?from=2024-01-01\&filters=\[{%22channel%22:%22orderBookL2%22,%22symbols%22:\[%22XBTUSD%22]}]\&offset=1) Order book snapshots and deltas by price level
* [quote](https://api.tardis.dev/v1/data-feeds/bitmex?from=2024-01-01\&filters=\[{%22channel%22:%22quote%22}]\&offset=0) Best bid and ask quote updates
* [liquidation](https://api.tardis.dev/v1/data-feeds/bitmex?from=2024-01-01\&filters=\[{%22channel%22:%22liquidation%22}]\&offset=0) Liquidation events stream
* [instrument](https://api.tardis.dev/v1/data-feeds/bitmex?from=2024-01-01\&filters=\[{%22channel%22:%22instrument%22}]) Instrument state snapshots and deltas with bidPrice/askPrice/midPrice on 5s timer. `partial` messages returned via HTTP API may contain data for all BitMEX instruments and require filtering client-side if only selected symbols were requested
* [connected](https://api.tardis.dev/v1/data-feeds/bitmex?from=2024-01-01\&filters=\[{%22channel%22:%22connected%22}]) Connection heartbeat and system status events
* [announcement](https://api.tardis.dev/v1/data-feeds/bitmex?from=2024-01-01\&filters=\[{%22channel%22:%22announcement%22}]) Exchange announcements stream
* [chat](https://api.tardis.dev/v1/data-feeds/bitmex?from=2024-01-01\&filters=\[{%22channel%22:%22chat%22}]) Public chat messages stream
* [publicNotifications](https://api.tardis.dev/v1/data-feeds/bitmex?from=2024-01-01\&filters=\[{%22channel%22:%22publicNotifications%22}]) Public notification messages stream
* [settlement](https://api.tardis.dev/v1/data-feeds/bitmex?from=2024-01-01\&filters=\[{%22channel%22:%22settlement%22}]) Contract settlement events stream
* [funding](https://api.tardis.dev/v1/data-feeds/bitmex?from=2024-01-01\&filters=\[{%22channel%22:%22funding%22}]\&offset=1200) Funding rate updates stream
* [insurance](https://api.tardis.dev/v1/data-feeds/bitmex?from=2024-01-01\&filters=\[{%22channel%22:%22insurance%22}]) Daily insurance fund balance updates
* [orderBookL2\_25](https://api.tardis.dev/v1/data-feeds/bitmex?from=2024-01-01\&filters=\[{%22channel%22:%22orderBookL2_25%22}]) Order book snapshots and deltas with up to 25 levels
* [orderBook10](https://api.tardis.dev/v1/data-feeds/bitmex?from=2024-01-01\&filters=\[{%22channel%22:%22orderBook10%22}]) — available since **2021-02-20** Top 10 level order book snapshots, throttled to 50ms since 2023-09-19
* [quoteBin1m](https://api.tardis.dev/v1/data-feeds/bitmex?from=2024-01-01\&filters=\[{%22channel%22:%22quoteBin1m%22}]\&offset=0) Quote bins at 1 minute interval
* [quoteBin5m](https://api.tardis.dev/v1/data-feeds/bitmex?from=2024-01-01\&filters=\[{%22channel%22:%22quoteBin5m%22}]) Quote bins at 5 minute interval
* [quoteBin1h](https://api.tardis.dev/v1/data-feeds/bitmex?from=2024-01-01\&filters=\[{%22channel%22:%22quoteBin1h%22}]) Quote bins at 1 hour interval
* [quoteBin1d](https://api.tardis.dev/v1/data-feeds/bitmex?from=2024-01-01\&filters=\[{%22channel%22:%22quoteBin1d%22}]) Quote bins at 1 day interval
* [tradeBin1m](https://api.tardis.dev/v1/data-feeds/bitmex?from=2024-01-01\&filters=\[{%22channel%22:%22tradeBin1m%22}]) Trade bins at 1 minute interval
* [tradeBin5m](https://api.tardis.dev/v1/data-feeds/bitmex?from=2024-01-01\&filters=\[{%22channel%22:%22tradeBin5m%22}]) Trade bins at 5 minute interval
* [tradeBin1h](https://api.tardis.dev/v1/data-feeds/bitmex?from=2024-01-01\&filters=\[{%22channel%22:%22tradeBin1h%22}]) Trade bins at 1 hour interval
* [tradeBin1d](https://api.tardis.dev/v1/data-feeds/bitmex?from=2024-01-01\&filters=\[{%22channel%22:%22tradeBin1d%22}]) Trade bins at 1 day interval
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for BitMEX is located in GCP asia-northeast1 region (Tokyo, Japan). Before **2025-08-23** it was located in GCP europe-west2 region (London, UK).
Real-time market data is captured via **single WebSocket connection** to `wss://direct.bitmex.com:443/realtimePublic`.
{% hint style="info" %}
BitMEX servers are located in AWS ap-northeast-1 region (Tokyo, Japan).
{% endhint %}
# Deribit
Deribit historical market data details - available data, coverage and data collection specifics
Deribit historical data for **all its instruments (including all options)** is available since **2019-03-30**.
{% embed url="" %}
See Deribit 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | ------------- | ---------- | ------------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTC-PERPETUAL | 2019-07-01 | [Download sample](https://datasets.tardis.dev/v1/deribit/incremental_book_L2/2019/07/01/BTC-PERPETUAL.csv.gz) |
| trades | BTC-PERPETUAL | 2019-07-01 | [Download sample](https://datasets.tardis.dev/v1/deribit/trades/2019/07/01/BTC-PERPETUAL.csv.gz) |
| options\_chain | OPTIONS | 2020-03-01 | [Download sample](https://datasets.tardis.dev/v1/deribit/options_chain/2020/03/01/OPTIONS.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time Deribit WebSocket **v2** API with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/api/quickstart) that 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="deribit",
from_date="2024-01-01",
to_date="2024-01-02",
filters=[Channel(name="book", symbols=["BTC-PERPETUAL"])],
api_key="YOUR_API_KEY",
):
# messages as provided by Deribit real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'deribit',
from: '2024-01-01',
to: '2024-01-02',
filters: [{ channel: 'book', symbols: ['BTC-PERPETUAL'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Deribit real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/deribit?from=2024-01-01&filters=[{"channel":"book","symbols":["BTC-PERPETUAL"]}]&offset=0'
```
{% embed url="" %}
Example API response for Deribit historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"deribit","filters":[{"channel":"book","symbols":["BTC-PERPETUAL"]}],"from":"2024-01-01","to":"2024-01-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See Deribit WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [trades](https://api.tardis.dev/v1/data-feeds/deribit?from=2024-01-01\&filters=\[{%22channel%22:%22trades%22}]) Trade executions stream. Collected with raw interval (no aggregation). Until 2023-10-03 included real-time liquidation info — Deribit removed the liquidation field from public trade subscriptions to avoid sharing price-sensitive data.
* [book](https://api.tardis.dev/v1/data-feeds/deribit?from=2024-01-01\&filters=\[{%22channel%22:%22book%22,%22symbols%22:\[%22BTC-PERPETUAL%22]}]) Order book incremental updates stream with sequence number validation. Collected with raw interval (no aggregation). During data collection integrity of order book incremental updates is being **validated** using [sequence numbers](https://docs.deribit.com/v2/#book-instrument_name-interval) provided by Deribit's real-time feed (`prev_change_id`) - in case of detecting missed message WebSocket connection is being restarted.
* [ticker](https://api.tardis.dev/v1/data-feeds/deribit?from=2024-01-01\&filters=\[{%22channel%22:%22ticker%22,%22symbols%22:\[%22BTC-PERPETUAL%22]}]) — available since **2019-10-01** Instrument ticker updates stream including price, volume, open interest, funding rate and Greeks for options. Collected with raw interval (no aggregation).
* [deribit\_price\_index](https://api.tardis.dev/v1/data-feeds/deribit?from=2024-01-01\&filters=\[{%22channel%22:%22deribit_price_index%22}]) Real-time index price updates stream used across pricing, margining and settlement
* [deribit\_price\_ranking](https://api.tardis.dev/v1/data-feeds/deribit?from=2024-01-01\&filters=\[{%22channel%22:%22deribit_price_ranking%22}]) Price ranking updates for the component exchanges used to calculate the Deribit index
* [deribit\_volatility\_index](https://api.tardis.dev/v1/data-feeds/deribit?from=2024-01-01\&filters=\[{%22channel%22:%22deribit_volatility_index%22}]) — available since **2021-04-01** Volatility index (DVOL) updates stream
* [estimated\_expiration\_price](https://api.tardis.dev/v1/data-feeds/deribit?from=2024-01-01\&filters=\[{%22channel%22:%22estimated_expiration_price%22}]) Estimated expiration (delivery) price updates stream
* [markprice.options](https://api.tardis.dev/v1/data-feeds/deribit?from=2024-01-01\&filters=\[{%22channel%22:%22markprice.options%22}]) — available since **2019-10-01** Options mark price and implied volatility updates stream for all options under a given index
* [perpetual](https://api.tardis.dev/v1/data-feeds/deribit?from=2024-01-01\&filters=\[{%22channel%22:%22perpetual%22,%22symbols%22:\[%22BTC-PERPETUAL%22]}]) — available since **2019-10-01** Perpetual instrument interest rate and index price updates stream. Collected with raw interval (no aggregation).
* [quote](https://api.tardis.dev/v1/data-feeds/deribit?from=2024-01-01\&filters=\[{%22channel%22:%22quote%22,%22symbols%22:\[%22BTC-PERPETUAL%22]}]) — available since **2019-10-01** Best bid and ask price and size updates stream
* [platform\_state](https://api.tardis.dev/v1/data-feeds/deribit?from=2024-01-01\&filters=\[{%22channel%22:%22platform_state%22}]) — available since **2019-12-31** Platform state, maintenance and price index lock notifications stream
* [instrument.state.any](https://api.tardis.dev/v1/data-feeds/deribit?from=2024-01-01\&filters=\[{%22channel%22:%22instrument.state.any%22}]) Instrument lifecycle state updates stream (new listings, expirations, settlements)
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for Deribit is located in GCP europe-west2 region (London, UK).
Real-time market data is captured via **multiple WebSocket connections** to `wss://www.deribit.com/ws/api/v2` (proxied via Cloudflare).
{% hint style="info" %}
Deribit servers are located in Equinix LD4 (Slough, UK).
{% endhint %}
# Bybit Derivatives
Bybit Derivatives historical market data details - available instruments, data coverage and data collection specifics
Bybit Derivatives historical data for **all its inverse contracts** is available since **2019-11-07** (for linear contracts since 2020-05-28).
{% embed url="" %}
See Bybit Derivatives 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](/downloadable-csv-files/overview).
{% hint style="info" %}
Liquidations datasets are available since 2020-12-18.
{% endhint %}
| data type | symbol | date | |
| --------------------- | ---------- | ---------- | ---------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTCUSD | 2020-01-01 | [Download sample](https://datasets.tardis.dev/v1/bybit/incremental_book_L2/2020/01/01/BTCUSD.csv.gz) |
| trades | BTCUSD | 2020-01-01 | [Download sample](https://datasets.tardis.dev/v1/bybit/trades/2020/01/01/BTCUSD.csv.gz) |
| quotes | BTCUSD | 2020-01-01 | [Download sample](https://datasets.tardis.dev/v1/bybit/quotes/2020/01/01/BTCUSD.csv.gz) |
| derivative\_ticker | BTCUSD | 2020-01-01 | [Download sample](https://datasets.tardis.dev/v1/bybit/derivative_ticker/2020/01/01/BTCUSD.csv.gz) |
| trades | ETHUSD | 2020-03-01 | [Download sample](https://datasets.tardis.dev/v1/bybit/trades/2020/03/01/ETHUSD.csv.gz) |
| incremental\_book\_L2 | ETHUSD | 2020-03-01 | [Download sample](https://datasets.tardis.dev/v1/bybit/incremental_book_L2/2020/03/01/ETHUSD.csv.gz) |
| liquidations | PERPETUALS | 2021-09-01 | [Download sample](https://datasets.tardis.dev/v1/bybit/liquidations/2021/09/01/PERPETUALS.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time Bybit Derivatives WebSocket API with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/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="bybit",
from_date="2024-01-01",
to_date="2024-01-02",
filters=[Channel(name="orderbook.50", symbols=["BTCUSD"])],
api_key="YOUR_API_KEY",
):
# messages as provided by Bybit Derivatives real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'bybit',
from: '2024-01-01',
to: '2024-01-02',
filters: [{ channel: 'orderbook.50', symbols: ['BTCUSD'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Bybit Derivatives real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/bybit?from=2024-01-01&filters=[{"channel":"orderbook.50","symbols":["BTCUSD"]}]&offset=0'
```
{% embed url="" %}
Example API response for Bybit Derivatives historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"bybit","filters":[{"channel":"orderbook.50","symbols":["BTCUSD"]}],"from":"2024-01-01","to":"2024-01-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See Bybit Derivatives WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [publicTrade](https://api.tardis.dev/v1/data-feeds/bybit?from=2024-01-01\&filters=\[{%22channel%22:%22publicTrade%22}]) — available since **2023-04-05** Real-time public trade executions stream
* [orderbook.50](https://api.tardis.dev/v1/data-feeds/bybit?from=2024-01-01\&filters=\[{%22channel%22:%22orderbook.50%22}]) — available since **2023-04-05** Order book snapshots and deltas at depth 50
* [orderbook.rpi](https://api.tardis.dev/v1/data-feeds/bybit?from=2026-09-01\&filters=\[{%22channel%22:%22orderbook.rpi%22,%22symbols%22:\[%22BTCUSDT%22]}]) — available since **2026-08-19** Order book snapshots and deltas at depth 50. Each level contains price, non-RPI quantity, and RPI quantity.
* [orderbook.full](https://api.tardis.dev/v1/data-feeds/bybit?from=2026-09-01\&filters=\[{%22channel%22:%22orderbook.full%22,%22symbols%22:\[%22BTCUSDT%22]}]) — available since **2026-08-19** Full-depth incremental order book updates with generated initial snapshots. The WebSocket feed is delta-only and excludes RPI orders. Tardis fetches initial snapshots with up to 10,000 levels per side from Bybit's full order book REST endpoint. Generated snapshots are marked with `"generated":true` and synchronized with buffered WebSocket updates using `u` and `seq`.
* [orderbook.500](https://api.tardis.dev/v1/data-feeds/bybit?from=2024-01-01\&filters=\[{%22channel%22:%22orderbook.500%22}]) — available since **2023-04-05** — available until **2025-09-05** Order book snapshots and deltas at depth 500
* [orderbook.1000](https://api.tardis.dev/v1/data-feeds/bybit?from=2025-10-01\&filters=\[{%22channel%22:%22orderbook.1000%22,%22symbols%22:\[%22BTCUSDT%22]}]) — available since **2025-09-04** — available until **2026-08-19** Order book snapshots and deltas at depth 1000
* [orderbook.1](https://api.tardis.dev/v1/data-feeds/bybit?from=2024-01-01\&filters=\[{%22channel%22:%22orderbook.1%22}]) — available since **2023-04-05** Order book snapshots and deltas at depth 1
* [allLiquidation](https://api.tardis.dev/v1/data-feeds/bybit?from=2025-03-01\&filters=\[{%22channel%22:%22allLiquidation%22}]) — available since **2025-02-25** All liquidation events stream with 500ms push frequency
* [tickers](https://api.tardis.dev/v1/data-feeds/bybit?from=2024-01-01\&filters=\[{%22channel%22:%22tickers%22}]) — available since **2023-04-05** Ticker snapshots and deltas with 24h stats and reference prices
* [trade](https://api.tardis.dev/v1/data-feeds/bybit?from=2023-03-01\&filters=\[{%22channel%22:%22trade%22,%22symbols%22:\[%22BTCUSDT%22]}]) — available until **2023-04-05** Public trade executions stream
* [orderBookL2\_25](https://api.tardis.dev/v1/data-feeds/bybit?from=2023-03-01\&filters=\[{%22channel%22:%22orderBookL2_25%22,%22symbols%22:\[%22BTCUSDT%22]}]) — available until **2023-04-05** Order book snapshots and deltas at depth 25
* [orderBook\_200](https://api.tardis.dev/v1/data-feeds/bybit?from=2023-03-01\&filters=\[{%22channel%22:%22orderBook_200%22,%22symbols%22:\[%22BTCUSDT%22]}]) — available since **2019-12-23** — available until **2023-04-05** Order book snapshots and deltas at depth 200
* [liquidation](https://api.tardis.dev/v1/data-feeds/bybit?from=2023-03-01\&filters=\[{%22channel%22:%22liquidation%22,%22symbols%22:\[%22BTCUSDT%22]}]\&offset=50) — available since **2020-11-03** — available until **2023-04-05** Liquidation stream for each symbol, up to one message per second
* [instrument\_info](https://api.tardis.dev/v1/data-feeds/bybit?from=2023-03-01\&filters=\[{%22channel%22:%22instrument_info%22,%22symbols%22:\[%22BTCUSDT%22]}]) — available until **2023-04-05** Instrument ticker and contract state updates
* [insurance](https://api.tardis.dev/v1/data-feeds/bybit?from=2022-11-01\&filters=\[{%22channel%22:%22insurance%22}]\&offset=49) — available until **2023-04-05** Insurance fund balance updates
* [long\_short\_ratio](https://api.tardis.dev/v1/data-feeds/bybit?from=2023-03-01\&filters=\[{%22channel%22:%22long_short_ratio%22}]) — available since **2022-03-20** — available until **2023-04-05** — generated channel Generated global long/short account ratio snapshots from REST account-ratio endpoint using 5min period buckets
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for Bybit Derivatives **since 2020-05-28** is located in GCP asia-northeast1 (Tokyo, Japan), before that it was located in GCP europe-west2 region (London, UK).
Real-time market data is captured via **multiple WebSocket connections** to `wss://stream.bybit.com/v5/public`.
{% hint style="info" %}
Bybit servers are located in AWS ap-southeast-1 region (Singapore, Asia Pacific).
{% endhint %}
# Bybit Spot
Bybit Spot historical market data details - available instruments, data coverage and data collection specifics
Bybit Spot historical data for **all its currency pairs** is available since **2021-12-04.**
{% embed url="" %}
See Bybit Spot 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | ------- | ---------- | ---------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTCUSDT | 2023-03-01 | [Download sample](https://datasets.tardis.dev/v1/bybit-spot/incremental_book_L2/2023/03/01/BTCUSDT.csv.gz) |
| trades | BTCUSDT | 2023-03-01 | [Download sample](https://datasets.tardis.dev/v1/bybit-spot/trades/2023/03/01/BTCUSDT.csv.gz) |
| quotes | BTCUSDT | 2023-03-01 | [Download sample](https://datasets.tardis.dev/v1/bybit-spot/quotes/2023/03/01/BTCUSDT.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time **Bybit Spot WebSocket API** with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/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="bybit-spot",
from_date="2024-01-01",
to_date="2024-01-02",
filters=[Channel(name="orderbook.50", symbols=["BTCUSDT"])],
api_key="YOUR_API_KEY",
):
# messages as provided by Bybit Spot real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'bybit-spot',
from: '2024-01-01',
to: '2024-01-02',
filters: [{ channel: 'orderbook.50', symbols: ['BTCUSDT'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Bybit Spot real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/bybit-spot?from=2024-01-01&filters=[{"channel":"orderbook.50","symbols":["BTCUSDT"]}]&offset=0'
```
{% embed url="" %}
Example API response for Bybit Spot historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"bybit-spot","filters":[{"channel":"orderbook.50","symbols":["BTCUSDT"]}],"from":"2024-01-01","to":"2024-01-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See Bybit Spot WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
**v5 API channels** (since 2023-04-05):
* [publicTrade](https://api.tardis.dev/v1/data-feeds/bybit-spot?from=2024-01-01\&filters=\[{%22channel%22:%22publicTrade%22}]) — available since **2023-04-05** Real-time public trade executions stream
* [orderbook.50](https://api.tardis.dev/v1/data-feeds/bybit-spot?from=2024-01-01\&filters=\[{%22channel%22:%22orderbook.50%22}]) — available since **2023-04-05** Order book snapshots and deltas at depth 50
* [orderbook.200](https://api.tardis.dev/v1/data-feeds/bybit-spot?from=2025-03-01\&filters=\[{%22channel%22:%22orderbook.200%22}]) — available since **2025-02-24** Order book snapshots and deltas at depth 200
* [orderbook.1](https://api.tardis.dev/v1/data-feeds/bybit-spot?from=2024-01-01\&filters=\[{%22channel%22:%22orderbook.1%22}]) — available since **2023-04-05** Order book snapshots and deltas at depth 1
* [tickers](https://api.tardis.dev/v1/data-feeds/bybit-spot?from=2024-01-01\&filters=\[{%22channel%22:%22tickers%22}]) — available since **2023-04-05** Ticker snapshots and deltas with 24h stats
* [lt](https://api.tardis.dev/v1/data-feeds/bybit-spot?from=2024-01-01\&filters=\[{%22channel%22:%22lt%22}]) — available since **2023-04-05** Leveraged token NAV and basket updates
**v2 API channels** (before 2023-04-05):
* [trade](https://api.tardis.dev/v1/data-feeds/bybit-spot?from=2022-01-01\&filters=\[{%22channel%22:%22trade%22}]) Public trade executions stream
* [depth](https://api.tardis.dev/v1/data-feeds/bybit-spot?from=2022-01-01\&filters=\[{%22channel%22:%22depth%22}]) Order book snapshots and deltas
* [bookTicker](https://api.tardis.dev/v1/data-feeds/bybit-spot?from=2022-01-01\&filters=\[{%22channel%22:%22bookTicker%22}]) Best bid and best ask updates
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for Bybit Spot is located in GCP asia-northeast1 (Tokyo, Japan).
Real-time market data is captured via **multiple WebSocket connections** to `wss://stream.bybit.com/v5/public/spot`.
{% hint style="info" %}
Bybit servers are located in AWS ap-southeast-1 region (Singapore, Asia Pacific).
{% endhint %}
# Bybit Options
Bybit Options historical market data details - instruments, data coverage and data collection specifics
Bybit Options historical data for **all its instruments** is available since **2023-04-05**.
{% embed url="" %}
See Bybit Options 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | ------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTC-29DEC23-25000-C | 2023-12-01 | [Download sample](https://datasets.tardis.dev/v1/bybit-options/incremental_book_L2/2023/12/01/BTC-29DEC23-25000-C.csv.gz) |
| trades | BTC-29DEC23-25000-C | 2023-12-01 | [Download sample](https://datasets.tardis.dev/v1/bybit-options/trades/2023/12/01/BTC-29DEC23-25000-C.csv.gz) |
| options\_chain | OPTIONS | 2024-01-01 | [Download sample](https://datasets.tardis.dev/v1/bybit-options/options_chain/2024/01/01/OPTIONS.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time Bybit Options WebSocket **v5** API with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/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="bybit-options",
from_date="2024-01-01",
to_date="2024-01-02",
filters=[Channel(name="orderbook.25", symbols=[])],
api_key="YOUR_API_KEY",
):
# messages as provided by Bybit Options real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'bybit-options',
from: '2024-01-01',
to: '2024-01-02',
filters: [{ channel: 'orderbook.25', symbols: [] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Bybit Options real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/bybit-options?from=2024-01-01&filters=[{"channel":"orderbook.25","symbols":[]}]&offset=0'
```
{% embed url="" %}
Example API response for Bybit Options historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"bybit-options","filters":[{"channel":"orderbook.25","symbols":[]}],"from":"2024-01-01","to":"2024-01-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See Bybit Options WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [publicTrade](https://api.tardis.dev/v1/data-feeds/bybit-options?from=2024-01-01\&filters=\[{%22channel%22:%22publicTrade%22}]) Real-time public trade executions stream
* [orderbook.25](https://api.tardis.dev/v1/data-feeds/bybit-options?from=2024-01-01\&filters=\[{%22channel%22:%22orderbook.25%22}]) Order book snapshots and deltas at depth 25
* [orderbook.100](https://api.tardis.dev/v1/data-feeds/bybit-options?from=2024-01-01\&filters=\[{%22channel%22:%22orderbook.100%22}]) Order book snapshots and deltas at depth 100
* [tickers](https://api.tardis.dev/v1/data-feeds/bybit-options?from=2024-01-01\&filters=\[{%22channel%22:%22tickers%22}]) Ticker snapshots and deltas with greeks and IV
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for Bybit Options is located in GCP asia-northeast1 region (Tokyo, Japan).
Real-time market data is captured via **multiple WebSocket connections** to `wss://stream.bybit.com/v5/public/option`.
{% hint style="info" %}
Bybit servers are located in AWS ap-southeast-1 region (Singapore, Asia Pacific).
{% endhint %}
# Kraken Futures
Kraken Futures historical market data details - available instruments, data coverage and data collection specifics
Kraken Futures historical data for **all its instruments** is available since **2019-03-30**.
{% embed url="" %}
See Kraken Futures 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | ---------- | ---------- | ------------------------------------------------------------------------------------------------------------------ |
| incremental\_book\_L2 | PI\_XBTUSD | 2019-07-01 | [Download sample](https://datasets.tardis.dev/v1/cryptofacilities/incremental_book_L2/2019/07/01/PI_XBTUSD.csv.gz) |
| trades | PI\_XBTUSD | 2019-07-01 | [Download sample](https://datasets.tardis.dev/v1/cryptofacilities/trades/2019/07/01/PI_XBTUSD.csv.gz) |
| derivative\_ticker | PI\_XBTUSD | 2019-07-01 | [Download sample](https://datasets.tardis.dev/v1/cryptofacilities/derivative_ticker/2019/07/01/PI_XBTUSD.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time Kraken Futures WebSocket API with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/api/quickstart) that 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="cryptofacilities",
from_date="2024-01-01",
to_date="2024-01-02",
filters=[Channel(name="book", symbols=["PI_XBTUSD"])],
api_key="YOUR_API_KEY",
):
# messages as provided by Kraken Futures real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'cryptofacilities',
from: '2024-01-01',
to: '2024-01-02',
filters: [{ channel: 'book', symbols: ['PI_XBTUSD'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Kraken Futures real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/cryptofacilities?from=2024-01-01&filters=[{"channel":"book","symbols":["PI_XBTUSD"]}]&offset=0'
```
{% embed url="" %}
Example API response for Kraken Futures historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"cryptofacilities","filters":[{"channel":"book","symbols":["PI_XBTUSD"]}],"from":"2024-01-01","to":"2024-01-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See Kraken Futures WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [trade](https://api.tardis.dev/v1/data-feeds/cryptofacilities?from=2024-01-01\&filters=\[{%22channel%22:%22trade%22}]) Trade executions stream
* [book](https://api.tardis.dev/v1/data-feeds/cryptofacilities?from=2024-01-01\&filters=\[{%22channel%22:%22book%22}]) Order book incremental updates stream validated with sequence numbers
* [book\_snapshot](https://api.tardis.dev/v1/data-feeds/cryptofacilities?from=2024-01-01\&filters=\[{%22channel%22:%22book_snapshot%22}]) Order book snapshot stream
* [ticker](https://api.tardis.dev/v1/data-feeds/cryptofacilities?from=2024-01-01\&filters=\[{%22channel%22:%22ticker%22}]) Derivative ticker updates stream
* [trade\_snapshot](https://api.tardis.dev/v1/data-feeds/cryptofacilities?from=2024-01-01\&filters=\[{%22channel%22:%22trade_snapshot%22}]) Trade snapshot on subscription
* [heartbeat](https://api.tardis.dev/v1/data-feeds/cryptofacilities?from=2024-01-01\&filters=\[{%22channel%22:%22heartbeat%22}]) Heartbeat keepalive events stream
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for Kraken Futures is located in GCP europe-west2 region (London, UK).
Real-time market data is captured via **multiple WebSocket connections** to `wss://futures.kraken.com/ws/v1`.
{% hint style="info" %}
Kraken Futures servers are located in AWS eu-west-1 region (Dublin, Ireland).
{% endhint %}
# Kraken
Kraken historical market data details - currency pairs, data coverage and data collection specifics
Kraken historical data for **all its currency pairs** is available since **2019-06-04**.
{% embed url="" %}
See Kraken historical data coverage: available symbols, channels, date ranges and incidents
{% endembed %}
### Symbol changes
Kraken WebSocket v2 uses `BTC` and `DOGE` in exchange-native symbol IDs. WebSocket v1 used `XBT` and `XDG`. Use v1 symbols before **2026-07-10** and v2 symbols from that date onward. This applies to both base and quote currencies, for example:
* `XBT/USD` → `BTC/USD`
* `XDG/USD` → `DOGE/USD`
* `ETH/XBT` → `ETH/BTC`
To resolve symbol IDs programmatically, query the [Instruments Metadata API](/api/instruments-metadata-api) using normalized `baseCurrency` and `quoteCurrency` values:
```json
{
"baseCurrency": "BTC",
"quoteCurrency": "USD",
"type": "spot"
}
```
The response includes both exchange-native symbol IDs:
| id | active | availableSince | availableTo |
| --------- | ------- | -------------------------- | -------------------------- |
| `XBT/USD` | `false` | `2019-06-04T00:00:00.000Z` | `2026-07-10T00:00:00.000Z` |
| `BTC/USD` | `true` | `2026-07-10T00:00:00.000Z` | |
### 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | ------- | ---------- | ------------------------------------------------------------------------------------------------------ |
| incremental\_book\_L2 | XBT-USD | 2019-07-01 | [Download sample](https://datasets.tardis.dev/v1/kraken/incremental_book_L2/2019/07/01/XBT-USD.csv.gz) |
| trades | XBT-USD | 2019-07-01 | [Download sample](https://datasets.tardis.dev/v1/kraken/trades/2019/07/01/XBT-USD.csv.gz) |
| quotes | XBT-USD | 2019-07-01 | [Download sample](https://datasets.tardis.dev/v1/kraken/quotes/2019/07/01/XBT-USD.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time Kraken WebSocket **v2** API from **2026-07-10** onward, with addition of local timestamps. Data before **2026-07-10** uses Kraken WebSocket **v1** format. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/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="kraken",
from_date="2026-08-01",
to_date="2026-08-02",
filters=[Channel(name="book", symbols=["BTC/USD"])],
api_key="YOUR_API_KEY",
):
# messages as provided by Kraken real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'kraken',
from: '2026-08-01',
to: '2026-08-02',
filters: [{ channel: 'book', symbols: ['BTC/USD'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Kraken real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/kraken?from=2026-08-01&filters=[{"channel":"book","symbols":["BTC/USD"]}]&offset=0'
```
{% embed url="" %}
Example API response for Kraken historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"kraken","filters":[{"channel":"book","symbols":["BTC/USD"]}],"from":"2026-08-01","to":"2026-08-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See Kraken WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
**Current channels (API v2, since 2026-07-10):**
* [trade](https://api.tardis.dev/v1/data-feeds/kraken?from=2026-08-01\&filters=\[{%22channel%22:%22trade%22}]) Public trade executions stream
* [book](https://api.tardis.dev/v1/data-feeds/kraken?from=2026-08-01\&filters=\[{%22channel%22:%22book%22,%22symbols%22:\[%22BTC/USD%22]}]) Level 2 order book snapshots and updates with `depth=1000`
* [ticker](https://api.tardis.dev/v1/data-feeds/kraken?from=2026-08-01\&filters=\[{%22channel%22:%22ticker%22}]) Level 1 market data and 24h statistics, published when the best bid or offer changes (`event_trigger=bbo`)
* [instrument](https://api.tardis.dev/v1/data-feeds/kraken?from=2026-08-01\&filters=\[{%22channel%22:%22instrument%22}]) Reference data snapshots and updates for all active assets and tradeable pairs, including tokenized assets
**Legacy channels (API v1, until 2026-07-10):**
* [trade](https://api.tardis.dev/v1/data-feeds/kraken?from=2024-01-01\&filters=\[{%22channel%22:%22trade%22}]) Public trade executions stream
* [book](https://api.tardis.dev/v1/data-feeds/kraken?from=2024-01-01\&filters=\[{%22channel%22:%22book%22,%22symbols%22:\[%22XBT/USD%22]}]) Order book snapshots and deltas recorded with depth=1000
* [spread](https://api.tardis.dev/v1/data-feeds/kraken?from=2024-01-01\&filters=\[{%22channel%22:%22spread%22,%22symbols%22:\[%22XBT/USD%22]}]) Best bid and ask spread updates stream
* [ticker](https://api.tardis.dev/v1/data-feeds/kraken?from=2024-01-01\&filters=\[{%22channel%22:%22ticker%22}]) Ticker updates with best bid and ask plus 24h stats
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for Kraken is located in GCP europe-west2 region (London, UK).
Real-time market data is captured via **multiple WebSocket connections** to `wss://ws.kraken.com/v2`. Before **2026-07-10**, data was captured from Kraken WebSocket v1 at `wss://ws.kraken.com`.
{% hint style="info" %}
Kraken's Spot trading engine is hosted at Equinix in London, UK.
{% endhint %}
# Bitfinex Derivatives
Bitfinex Derivatives historical market data details - available instruments, data coverage and data collection specifics
Bitfinex exchange historical data for **all its derivative instruments** is available since **2019-09-14.**
{% embed url="" %}
See Bitfinex Derivatives 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | ----------- | ---------- | ------------------------------------------------------------------------------------------------------------------------ |
| incremental\_book\_L2 | BTCF0-USTF0 | 2019-12-01 | [Download sample](https://datasets.tardis.dev/v1/bitfinex-derivatives/incremental_book_L2/2019/12/01/BTCF0-USTF0.csv.gz) |
| trades | BTCF0-USTF0 | 2019-12-01 | [Download sample](https://datasets.tardis.dev/v1/bitfinex-derivatives/trades/2019/12/01/BTCF0-USTF0.csv.gz) |
| derivative\_ticker | BTCF0-USTF0 | 2019-12-01 | [Download sample](https://datasets.tardis.dev/v1/bitfinex-derivatives/derivative_ticker/2019/12/01/BTCF0-USTF0.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time Bitfinex WebSocket **v2** API with addition of local timestamps and **since 2020-05-27 also with addition of channel and symbol at the end of each message** which allows us providing filtering for the data server-side. If you'd like to work with normalized data format instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/api/quickstart) that 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="bitfinex-derivatives",
from_date="2023-03-01",
to_date="2023-03-02",
filters=[Channel(name="book", symbols=["BTCF0:USTF0"])],
api_key="YOUR_API_KEY",
):
# messages as provided by Bitfinex real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'bitfinex-derivatives',
from: '2023-03-01',
to: '2023-03-02',
filters: [{ channel: 'book', symbols: ['BTCF0:USTF0'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Bitfinex real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/bitfinex-derivatives?from=2023-03-01&filters=[{"channel":"book","symbols":["BTCF0:USTF0"]}]&offset=0'
```
{% embed url="" %}
Example API response for Bitfinex Derivatives historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"bitfinex-derivatives","filters":[{"channel":"book","symbols":["BTCF0:USTF0"]}],"from":"2023-03-01","to":"2023-03-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See Bitfinex WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [trades](https://api.tardis.dev/v1/data-feeds/bitfinex-derivatives?from=2024-01-01\&filters=\[{%22channel%22:%22trades%22}]) Public trade executions stream
* [book](https://api.tardis.dev/v1/data-feeds/bitfinex-derivatives?from=2024-01-01\&filters=\[{%22channel%22:%22book%22}]) Order book snapshots and deltas (prec=P0, freq=F0, len=100) During data collection integrity of order book incremental updates is being **validated** using [sequence numbers](https://docs.bitfinex.com/v2/docs/ws-general#section-available-options) (SEQ\_ALL option) provided by real-time feed - in case of detecting missed message WebSocket connection is being restarted.
* [ticker](https://api.tardis.dev/v1/data-feeds/bitfinex-derivatives?from=2024-01-01\&filters=\[{%22channel%22:%22ticker%22}]) Derivative ticker updates with mark and funding related fields
* [liquidations](https://api.tardis.dev/v1/data-feeds/bitfinex-derivatives?from=2024-01-01\&filters=\[{%22channel%22:%22liquidations%22}]) Forced liquidation events stream
* [status](https://api.tardis.dev/v1/data-feeds/bitfinex-derivatives?from=2024-01-01\&filters=\[{%22channel%22:%22status%22}]) Instrument status and derivative market state updates
* [raw\_book](https://api.tardis.dev/v1/data-feeds/bitfinex-derivatives?from=2024-01-01\&filters=\[{%22channel%22:%22raw_book%22}]) Raw order book snapshots and deltas (prec=R0, freq=F0, len=100)
All data collection is performed with `TIMESTAMP` and `SEQ_ALL` config flags set.
{% hint style="info" %}
Since 2020-05-27 each collected Bitfinex real-time data message has appended channel and symbol at the end of array - this allows us providing data filtering via API. Before that date if filters are provided with API request, always all recorded, unfiltered data feed is being returned.
{% endhint %}
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for Bitfinex Derivatives is located in GCP europe-west2 region (London, UK).
Real-time market data is captured via **multiple WebSocket connections** to `wss://api-pub.bitfinex.com/ws/2`.
{% hint style="info" %}
Bitfinex servers are located in Market Synergy DC (Switzerland). All its public APIs are proxied through Cloudflare.
{% endhint %}
# Bitfinex
Bitfinex historical market data details - currency pairs, data coverage and data collection specifics
Bitfinex exchange historical data for: BTCUSD, BTCUST, ETHUSD, ETHUST, LTCUSD, TRXUSD, EOSUSD, XRPUSD, LEOUSD, BABUSD currency pairs is **available since 2019-05-23**, data for other high caps is available since 2020-05-28, data for all currency pairs is available since **2021-10-29**.
{% embed url="" %}
See Bitfinex 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | ------ | ---------- | ------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTCUSD | 2019-08-01 | [Download sample](https://datasets.tardis.dev/v1/bitfinex/incremental_book_L2/2019/08/01/BTCUSD.csv.gz) |
| trades | BTCUSD | 2019-08-01 | [Download sample](https://datasets.tardis.dev/v1/bitfinex/trades/2019/08/01/BTCUSD.csv.gz) |
| quotes | BTCUSD | 2019-08-01 | [Download sample](https://datasets.tardis.dev/v1/bitfinex/quotes/2019/08/01/BTCUSD.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time Bitfinex WebSocket **v2** API with addition of local timestamps and **since 2020-05-27 also with addition of channel and symbol at the end of each message** which allows us providing filtering for the data server-side. If you'd like to work with normalized data format instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/api/quickstart) that 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="bitfinex",
from_date="2023-03-01",
to_date="2023-03-02",
filters=[Channel(name="book", symbols=["BTCUSD"])],
api_key="YOUR_API_KEY",
):
# messages as provided by Bitfinex real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'bitfinex',
from: '2023-03-01',
to: '2023-03-02',
filters: [{ channel: 'book', symbols: ['BTCUSD'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Bitfinex real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/bitfinex?from=2023-03-01&filters=[{"channel":"book","symbols":["BTCUSD"]}]&offset=0'
```
{% embed url="" %}
Example API response for Bitfinex historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"bitfinex","filters":[{"channel":"book","symbols":["BTCUSD"]}],"from":"2023-03-01","to":"2023-03-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See Bitfinex WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [trades](https://api.tardis.dev/v1/data-feeds/bitfinex?from=2024-01-01\&filters=\[{%22channel%22:%22trades%22}]) Public trade executions stream
* [book](https://api.tardis.dev/v1/data-feeds/bitfinex?from=2024-01-01\&filters=\[{%22channel%22:%22book%22}]) Order book snapshots and deltas (prec=P0, freq=F0, len=100) During data collection integrity of order book incremental updates is being **validated** using [sequence numbers](https://docs.bitfinex.com/v2/docs/ws-general#section-available-options) (SEQ\_ALL option) provided by real-time feed - in case of detecting missed message WebSocket connection is being restarted.
* [ticker](https://api.tardis.dev/v1/data-feeds/bitfinex?from=2024-01-01\&filters=\[{%22channel%22:%22ticker%22}]) Ticker updates with best bid and ask plus 24h stats
* [raw\_book](https://api.tardis.dev/v1/data-feeds/bitfinex?from=2024-01-01\&filters=\[{%22channel%22:%22raw_book%22}]) Raw order book snapshots and deltas (prec=R0, freq=F0, len=100)
All data collection is performed with `TIMESTAMP` and `SEQ_ALL` config flags set.
{% hint style="info" %}
Since 2020-05-27 each collected Bitfinex real-time data message has appended channel and symbol at the end of array - this allows us providing data filtering via API. Before that date if filters are provided with API request, always all recorded, unfiltered data feed is being returned.
{% endhint %}
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for Bitfinex is located in GCP europe-west2 region (London, UK).
Real-time market data is captured via **multiple WebSocket connections** to `wss://api-pub.bitfinex.com/ws/2`.
{% hint style="info" %}
Bitfinex servers are located in Market Synergy DC (Switzerland). All its public APIs are proxied through Cloudflare.
{% endhint %}
# KuCoin Futures
KuCoin Futures historical market data details - instruments, data coverage and data collection specifics
KuCoin Futures historical data for **all its instruments** is available since **2024-01-25**.
{% embed url="" %}
See KuCoin Futures 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | -------- | ---------- | --------------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | XBTUSDTM | 2025-01-01 | [Download sample](https://datasets.tardis.dev/v1/kucoin-futures/incremental_book_L2/2025/01/01/XBTUSDTM.csv.gz) |
| trades | XBTUSDTM | 2025-01-01 | [Download sample](https://datasets.tardis.dev/v1/kucoin-futures/trades/2025/01/01/XBTUSDTM.csv.gz) |
| derivative\_ticker | XBTUSDTM | 2025-01-01 | [Download sample](https://datasets.tardis.dev/v1/kucoin-futures/derivative_ticker/2025/01/01/XBTUSDTM.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time KuCoin Futures WebSocket API with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/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="kucoin-futures",
from_date="2024-02-01",
to_date="2024-02-02",
filters=[Channel(name="contractMarket/level2", symbols=["XBTUSDTM"])],
api_key="YOUR_API_KEY",
):
# messages as provided by KuCoin Futures real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'kucoin-futures',
from: '2024-02-01',
to: '2024-02-02',
filters: [{ channel: 'contractMarket/level2', symbols: ['XBTUSDTM'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by KuCoin Futures real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/kucoin-futures?from=2024-02-01&filters=[{"channel":"contractMarket/level2","symbols":["XBTUSDTM"]}]&offset=0'
```
{% embed url="" %}
Example API response for KuCoin Futures historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"kucoin-futures","filters":[{"channel":"contractMarket/level2","symbols":["XBTUSDTM"]}],"from":"2024-02-01","to":"2024-02-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See KuCoin Futures WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [contractMarket/execution](https://api.tardis.dev/v1/data-feeds/kucoin-futures?from=2024-06-01\&filters=\[{%22channel%22:%22contractMarket/execution%22}]) Public futures trade executions stream
* [contractMarket/level2](https://api.tardis.dev/v1/data-feeds/kucoin-futures?from=2024-06-01\&filters=\[{%22channel%22:%22contractMarket/level2%22,%22symbols%22:\[%22XBTUSDTM%22]}]) Futures Level 2 order book deltas stream
* [contractMarket/level2Snapshot](https://api.tardis.dev/v1/data-feeds/kucoin-futures?from=2024-06-01\&filters=\[{%22channel%22:%22contractMarket/level2Snapshot%22,%22symbols%22:\[%22XBTUSDTM%22]}]) — generated channel
Generated futures Level 2 order book snapshots from REST API. Used to bootstrap book state before contractMarket/level2 deltas. Snapshot messages marked as `"generated":true` on topic `/contractMarket/level2Snapshot:`.
* [contractMarket/tickerV2](https://api.tardis.dev/v1/data-feeds/kucoin-futures?from=2024-06-01\&filters=\[{%22channel%22:%22contractMarket/tickerV2%22,%22symbols%22:\[%22XBTUSDTM%22]}]) Futures ticker updates with mark price and funding fields
* [contract/instrument](https://api.tardis.dev/v1/data-feeds/kucoin-futures?from=2024-06-01\&filters=\[{%22channel%22:%22contract/instrument%22,%22symbols%22:\[%22XBTUSDTM%22]}]) Instrument status and parameter updates, mark/index up to 1s and funding up to 1m
* [contract/details](https://api.tardis.dev/v1/data-feeds/kucoin-futures?from=2024-06-01\&filters=\[{%22channel%22:%22contract/details%22,%22symbols%22:\[%22XBTUSDTM%22]}]) — generated channel
Generated contract details snapshots from REST API. Includes open interest and contract state. Snapshot messages marked as `"generated":true` on topic `/contract/details:`.
* [contractMarket/snapshot](https://api.tardis.dev/v1/data-feeds/kucoin-futures?from=2024-06-01\&filters=\[{%22channel%22:%22contractMarket/snapshot%22,%22symbols%22:\[%22XBTUSDTM%22]}]) Market snapshot stream with index and open interest data
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for KuCoin Futures is located in GCP asia-northeast1 region (Tokyo, Japan).
Real-time market data is captured via **multiple WebSocket connections** to `wss://ws-api-futures.kucoin.com`.
{% hint style="info" %}
KuCoin Futures servers are located in AWS ap-northeast-1 region (Tokyo, Japan).
{% endhint %}
# KuCoin Spot
KuCoin Spot historical market data details - instruments, data coverage and data collection specifics
KuCoin Spot exchange historical data for **all its currency pairs** is available since **2022-08-16**.
{% embed url="" %}
See KuCoin Spot 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | -------- | ---------- | ------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTC-USDT | 2023-02-01 | [Download sample](https://datasets.tardis.dev/v1/kucoin/incremental_book_L2/2023/02/01/BTC-USDT.csv.gz) |
| trades | BTC-USDT | 2023-02-01 | [Download sample](https://datasets.tardis.dev/v1/kucoin/trades/2023/02/01/BTC-USDT.csv.gz) |
| quotes | BTC-USDT | 2023-02-01 | [Download sample](https://datasets.tardis.dev/v1/kucoin/quotes/2023/02/01/BTC-USDT.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time KuCoin Spot WebSocket **Market Data API v1** () with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/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="kucoin",
from_date="2024-01-01",
to_date="2024-01-02",
filters=[Channel(name="market/level2", symbols=["BTC-USDT"])],
api_key="YOUR_API_KEY",
):
# messages as provided by KuCoin Spot real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'kucoin',
from: '2024-01-01',
to: '2024-01-02',
filters: [{ channel: 'market/level2', symbols: ['BTC-USDT'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by KuCoin Spot real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/kucoin?from=2024-01-01&filters=[{"channel":"market/level2","symbols":["BTC-USDT"]}]&offset=0'
```
{% embed url="" %}
Example API response for KuCoin historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"kucoin","filters":[{"channel":"market/level2","symbols":["BTC-USDT"]}],"from":"2024-01-01","to":"2024-01-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See KuCoin Spot WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [market/match](https://api.tardis.dev/v1/data-feeds/kucoin?from=2024-01-01\&filters=\[{%22channel%22:%22market/match%22}]) Public trade executions stream
* [market/level2](https://api.tardis.dev/v1/data-feeds/kucoin?from=2024-01-01\&filters=\[{%22channel%22:%22market/level2%22}]) Level 2 order book deltas stream
* [market/level2Snapshot](https://api.tardis.dev/v1/data-feeds/kucoin?from=2024-01-01\&filters=\[{%22channel%22:%22market/level2Snapshot%22}]) — generated channel Generated Level 2 order book snapshots from REST API. Used to bootstrap book state before market/level2 deltas. Snapshot messages marked as `"generated":true` on topic `/market/level2Snapshot:`.
* [market/ticker](https://api.tardis.dev/v1/data-feeds/kucoin?from=2024-01-01\&filters=\[{%22channel%22:%22market/ticker%22}]) Ticker updates with best bid and ask plus 24h stats
* [market/snapshot](https://api.tardis.dev/v1/data-feeds/kucoin?from=2024-01-01\&filters=\[{%22channel%22:%22market/snapshot%22}]) Market summary snapshots stream
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for KuCoin Spot is located in GCP asia-northeast1 (Tokyo, Japan).
Real-time market data is captured via **multiple WebSocket connections** to `wss://ws-api-spot.kucoin.com`.
{% hint style="info" %}
KuCoin Spot servers are located in AWS ap-northeast-1 region (Tokyo, Japan).
{% endhint %}
# Aster Futures
Aster Futures historical market data details - instruments, data coverage and data collection specifics
Aster Futures historical data for **all its perpetual instruments** is available since **2026-08-23**.
{% embed url="" %}
See Aster Futures 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | ------- | ---------- | ------------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTCUSDT | 2026-09-01 | [Download sample](https://datasets.tardis.dev/v1/aster-futures/incremental_book_L2/2026/09/01/BTCUSDT.csv.gz) |
| trades | BTCUSDT | 2026-09-01 | [Download sample](https://datasets.tardis.dev/v1/aster-futures/trades/2026/09/01/BTCUSDT.csv.gz) |
| derivative\_ticker | BTCUSDT | 2026-09-01 | [Download sample](https://datasets.tardis.dev/v1/aster-futures/derivative_ticker/2026/09/01/BTCUSDT.csv.gz) |
| liquidations | BTCUSDT | 2026-09-01 | [Download sample](https://datasets.tardis.dev/v1/aster-futures/liquidations/2026/09/01/BTCUSDT.csv.gz) |
| book\_ticker | BTCUSDT | 2026-09-01 | [Download sample](https://datasets.tardis.dev/v1/aster-futures/book_ticker/2026/09/01/BTCUSDT.csv.gz) |
### API Access and data format
Historical data format is the same as provided by Aster Futures WebSocket API with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/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="aster-futures",
from_date="2026-09-01",
to_date="2026-09-02",
filters=[Channel(name="depth", symbols=["btcusdt"])],
api_key="YOUR_API_KEY",
):
# messages as provided by Aster Futures real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'aster-futures',
from: '2026-09-01',
to: '2026-09-02',
filters: [{ channel: 'depth', symbols: ['btcusdt'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Aster Futures real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/aster-futures?from=2026-09-01&filters=[{"channel":"depth","symbols":["btcusdt"]}]&offset=0'
```
{% embed url="" %}
Example API response for Aster Futures historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"aster-futures","filters":[{"channel":"depth","symbols":["btcusdt"]}],"from":"2026-09-01","to":"2026-09-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See Aster Futures WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [trade](https://api.tardis.dev/v1/data-feeds/aster-futures?from=2026-09-01\&filters=\[{%22channel%22:%22trade%22,%22symbols%22:\[%22btcusdt%22]}]) Public futures trade executions stream
* [aggTrade](https://api.tardis.dev/v1/data-feeds/aster-futures?from=2026-09-01\&filters=\[{%22channel%22:%22aggTrade%22,%22symbols%22:\[%22btcusdt%22]}]) Aggregated futures trade executions stream
* [depth](https://api.tardis.dev/v1/data-feeds/aster-futures?from=2026-09-01\&filters=\[{%22channel%22:%22depth%22,%22symbols%22:\[%22btcusdt%22]}]) Incremental futures order book updates stream. Subscribed as `depth@0ms` (real-time dynamically adjusted update speed).
* [depthSnapshot](https://api.tardis.dev/v1/data-feeds/aster-futures?from=2026-09-01\&filters=\[{%22channel%22:%22depthSnapshot%22,%22symbols%22:\[%22btcusdt%22]}]) — generated channel Generated initial order book snapshots containing up to 1000 levels per side from the REST API, used to bootstrap depth updates. Snapshot messages are marked with `"stream":"@depthSnapshot"` and `"generated":true`.
During collection, depth sequence continuity and initial snapshot overlap are validated. The connection is restarted if a sequence gap is detected.
* [bookTicker](https://api.tardis.dev/v1/data-feeds/aster-futures?from=2026-09-01\&filters=\[{%22channel%22:%22bookTicker%22,%22symbols%22:\[%22btcusdt%22]}]) Best bid and best ask futures updates stream
* [ticker](https://api.tardis.dev/v1/data-feeds/aster-futures?from=2026-09-01\&filters=\[{%22channel%22:%22ticker%22,%22symbols%22:\[%22btcusdt%22]}]) 24h futures ticker updates stream
* [markPrice](https://api.tardis.dev/v1/data-feeds/aster-futures?from=2026-09-01\&filters=\[{%22channel%22:%22markPrice%22,%22symbols%22:\[%22btcusdt%22]}]) Mark price and funding metrics stream. Subscribed as `@markPrice@1s`.
* [forceOrder](https://api.tardis.dev/v1/data-feeds/aster-futures?from=2026-09-01\&filters=\[{%22channel%22:%22forceOrder%22,%22symbols%22:\[%22btcusdt%22]}]) Liquidation order stream publishing only the latest liquidation per symbol in each 1000ms window
* [assetIndex](https://api.tardis.dev/v1/data-feeds/aster-futures?from=2026-09-01\&filters=\[{%22channel%22:%22assetIndex%22,%22symbols%22:\[%22btcusd%22]}]) Asset index updates stream
* [openInterest](https://api.tardis.dev/v1/data-feeds/aster-futures?from=2026-09-01\&filters=\[{%22channel%22:%22openInterest%22,%22symbols%22:\[%22btcusdt%22]}]) — generated channel Generated open interest snapshots from REST API. Snapshots are fetched from `/fapi/v3/openInterest` about every 30 seconds per instrument and are marked with `"stream":"@openInterest"` and `"generated":true`.
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for Aster Futures is located in GCP asia-northeast1 (Tokyo, Japan).
Real-time market data is captured via **multiple WebSocket connections** to `wss://fstream.asterdex.com/stream`.
{% hint style="info" %}
Aster Futures servers are located in AWS ap-northeast-1 region (Tokyo, Japan).
{% endhint %}
# Aster Spot
Aster Spot historical market data details - currency pairs, data coverage and data collection specifics
Aster Spot historical data for **all its currency pairs** is available since **2026-08-23**.
{% embed url="" %}
See Aster Spot 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | --------- | ---------- | ------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | ASTERUSDT | 2026-09-01 | [Download sample](https://datasets.tardis.dev/v1/aster/incremental_book_L2/2026/09/01/ASTERUSDT.csv.gz) |
| trades | ASTERUSDT | 2026-09-01 | [Download sample](https://datasets.tardis.dev/v1/aster/trades/2026/09/01/ASTERUSDT.csv.gz) |
| quotes | ASTERUSDT | 2026-09-01 | [Download sample](https://datasets.tardis.dev/v1/aster/quotes/2026/09/01/ASTERUSDT.csv.gz) |
| book\_ticker | ASTERUSDT | 2026-09-01 | [Download sample](https://datasets.tardis.dev/v1/aster/book_ticker/2026/09/01/ASTERUSDT.csv.gz) |
### API Access and data format
Historical data format is the same as provided by Aster Spot WebSocket API with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/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="aster",
from_date="2026-09-01",
to_date="2026-09-02",
filters=[Channel(name="depth", symbols=["asterusdt"])],
api_key="YOUR_API_KEY",
):
# messages as provided by Aster Spot real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'aster',
from: '2026-09-01',
to: '2026-09-02',
filters: [{ channel: 'depth', symbols: ['asterusdt'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Aster Spot real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/aster?from=2026-09-01&filters=[{"channel":"depth","symbols":["asterusdt"]}]&offset=0'
```
{% embed url="" %}
Example API response for Aster Spot historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"aster","filters":[{"channel":"depth","symbols":["asterusdt"]}],"from":"2026-09-01","to":"2026-09-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See Aster Spot WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [trade](https://api.tardis.dev/v1/data-feeds/aster?from=2026-09-01\&filters=\[{%22channel%22:%22trade%22,%22symbols%22:\[%22asterusdt%22]}]) Public spot trade executions stream
* [aggTrade](https://api.tardis.dev/v1/data-feeds/aster?from=2026-09-01\&filters=\[{%22channel%22:%22aggTrade%22,%22symbols%22:\[%22asterusdt%22]}]) Aggregated spot trade executions stream
* [depth](https://api.tardis.dev/v1/data-feeds/aster?from=2026-09-01\&filters=\[{%22channel%22:%22depth%22,%22symbols%22:\[%22asterusdt%22]}]) Incremental order book updates stream. Subscribed as `depth@0ms` (real-time dynamically adjusted update speed).
* [depthSnapshot](https://api.tardis.dev/v1/data-feeds/aster?from=2026-09-01\&filters=\[{%22channel%22:%22depthSnapshot%22,%22symbols%22:\[%22asterusdt%22]}]) — generated channel Generated initial order book snapshots containing up to 1000 levels per side from the REST API, used to bootstrap depth updates. Snapshot messages are marked with `"stream":"@depthSnapshot"` and `"generated":true`.
During collection, depth sequence continuity and initial snapshot overlap are validated. The connection is restarted if a sequence gap is detected.
* [bookTicker](https://api.tardis.dev/v1/data-feeds/aster?from=2026-09-01\&filters=\[{%22channel%22:%22bookTicker%22,%22symbols%22:\[%22asterusdt%22]}]) Best bid and best ask updates stream
* [ticker](https://api.tardis.dev/v1/data-feeds/aster?from=2026-09-01\&filters=\[{%22channel%22:%22ticker%22,%22symbols%22:\[%22asterusdt%22]}]) 24h spot ticker updates stream
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for Aster Spot is located in GCP asia-northeast1 (Tokyo, Japan).
Real-time market data is captured via **multiple WebSocket connections** to `wss://sstream.asterdex.com/stream`.
{% hint style="info" %}
Aster Spot servers are located in AWS ap-northeast-1 region (Tokyo, Japan).
{% endhint %}
# MEXC Spot
MEXC Spot historical market data details - currency pairs, data coverage and data collection specifics
MEXC Spot historical data for **all its currency pairs** is available since **2026-06-25**.
{% embed url="" %}
See MEXC Spot 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | ------- | ---------- | ---------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTCUSDT | 2026-07-01 | [Download sample](https://datasets.tardis.dev/v1/mexc/incremental_book_L2/2026/07/01/BTCUSDT.csv.gz) |
| trades | BTCUSDT | 2026-07-01 | [Download sample](https://datasets.tardis.dev/v1/mexc/trades/2026/07/01/BTCUSDT.csv.gz) |
| quotes | BTCUSDT | 2026-07-01 | [Download sample](https://datasets.tardis.dev/v1/mexc/quotes/2026/07/01/BTCUSDT.csv.gz) |
| book\_ticker | BTCUSDT | 2026-07-01 | [Download sample](https://datasets.tardis.dev/v1/mexc/book_ticker/2026/07/01/BTCUSDT.csv.gz) |
### API Access and data format
Historical data format is the same as provided by MEXC Spot WebSocket API v3 Market Streams with addition of local timestamps. MEXC Spot WebSocket market data is delivered as Protocol Buffers messages; Tardis.dev stores the decoded JSON form. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/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="mexc",
from_date="2026-07-01",
to_date="2026-07-02",
filters=[Channel(name="spot@public.aggre.depth.v3.api.pb@10ms", symbols=["BTCUSDT"])],
api_key="YOUR_API_KEY",
):
# messages as provided by MEXC Spot real-time stream, decoded from protobuf to JSON
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'mexc',
from: '2026-07-01',
to: '2026-07-02',
filters: [{ channel: 'spot@public.aggre.depth.v3.api.pb@10ms', symbols: ['BTCUSDT'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by MEXC Spot real-time stream, decoded from protobuf to JSON
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/mexc?from=2026-07-01&filters=[{"channel":"spot@public.aggre.depth.v3.api.pb@10ms","symbols":["BTCUSDT"]}]&offset=0'
```
{% embed url="" %}
Example API response for MEXC Spot historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"mexc","filters":[{"channel":"spot@public.aggre.depth.v3.api.pb@10ms","symbols":["BTCUSDT"]}],"from":"2026-07-01","to":"2026-07-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See MEXC Spot WebSocket API v3 Market Streams docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [spot@public.aggre.deals.v3.api.pb@10ms](https://api.tardis.dev/v1/data-feeds/mexc?from=2026-07-01\&filters=\[{%22channel%22:%22spot@public.aggre.deals.v3.api.pb@10ms%22,%22symbols%22:\[%22BTCUSDT%22]}]) Spot public trade executions stream
* [spot@public.aggre.depth.v3.api.pb@10ms](https://api.tardis.dev/v1/data-feeds/mexc?from=2026-07-01\&filters=\[{%22channel%22:%22spot@public.aggre.depth.v3.api.pb@10ms%22,%22symbols%22:\[%22BTCUSDT%22]}]) Spot order book incremental updates stream
* [spot@public.aggre.depth.snapshot.v3.api.pb@10ms](https://api.tardis.dev/v1/data-feeds/mexc?from=2026-07-01\&filters=\[{%22channel%22:%22spot@public.aggre.depth.snapshot.v3.api.pb@10ms%22,%22symbols%22:\[%22BTCUSDT%22]}]) Generated spot order book snapshots from REST API, up to 5000 levels. Snapshot messages are marked with `"generated":true`.
* [spot@public.aggre.bookTicker.v3.api.pb@10ms](https://api.tardis.dev/v1/data-feeds/mexc?from=2026-07-01\&filters=\[{%22channel%22:%22spot@public.aggre.bookTicker.v3.api.pb@10ms%22,%22symbols%22:\[%22BTCUSDT%22]}]) Best bid and ask price and amount updates stream
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for MEXC Spot is located in GCP asia-northeast1 (Tokyo, Japan).
Real-time market data is captured via **multiple WebSocket connections** to `wss://wbs-api.mexc.com/ws`.
{% hint style="info" %}
MEXC Spot servers are located in AWS ap-northeast-1 region (Tokyo, Japan).
{% endhint %}
# MEXC Futures
MEXC Futures historical market data details - available instruments, data coverage and data collection specifics
MEXC Futures historical data for **all its instruments** is available since **2026-06-25**.
{% embed url="" %}
See MEXC Futures 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | --------- | ---------- | ------------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTC\_USDT | 2026-07-01 | [Download sample](https://datasets.tardis.dev/v1/mexc-futures/incremental_book_L2/2026/07/01/BTC_USDT.csv.gz) |
| trades | BTC\_USDT | 2026-07-01 | [Download sample](https://datasets.tardis.dev/v1/mexc-futures/trades/2026/07/01/BTC_USDT.csv.gz) |
| derivative\_ticker | BTC\_USDT | 2026-07-01 | [Download sample](https://datasets.tardis.dev/v1/mexc-futures/derivative_ticker/2026/07/01/BTC_USDT.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time MEXC Futures WebSocket API with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/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="mexc-futures",
from_date="2026-07-01",
to_date="2026-07-02",
filters=[Channel(name="push.depth", symbols=["BTC_USDT"])],
api_key="YOUR_API_KEY",
):
# messages as provided by MEXC Futures real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'mexc-futures',
from: '2026-07-01',
to: '2026-07-02',
filters: [{ channel: 'push.depth', symbols: ['BTC_USDT'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by MEXC Futures real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/mexc-futures?from=2026-07-01&filters=[{"channel":"push.depth","symbols":["BTC_USDT"]}]&offset=0'
```
{% embed url="" %}
Example API response for MEXC Futures historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"mexc-futures","filters":[{"channel":"push.depth","symbols":["BTC_USDT"]}],"from":"2026-07-01","to":"2026-07-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See MEXC Futures WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [push.deal](https://api.tardis.dev/v1/data-feeds/mexc-futures?from=2026-07-01\&filters=\[{%22channel%22:%22push.deal%22}]) Recent futures trades stream
* [push.depth](https://api.tardis.dev/v1/data-feeds/mexc-futures?from=2026-07-01\&filters=\[{%22channel%22:%22push.depth%22,%22symbols%22:\[%22BTC_USDT%22]}]) Futures depth updates stream
* [push.depth.snapshot](https://api.tardis.dev/v1/data-feeds/mexc-futures?from=2026-07-01\&filters=\[{%22channel%22:%22push.depth.snapshot%22,%22symbols%22:\[%22BTC_USDT%22]}]) Generated futures order book snapshots from REST API, up to 5000 levels. Snapshot messages are marked with `"generated":true`.
* [push.ticker](https://api.tardis.dev/v1/data-feeds/mexc-futures?from=2026-07-01\&filters=\[{%22channel%22:%22push.ticker%22,%22symbols%22:\[%22BTC_USDT%22]}]) Perpetual contracts latest price, best bid/ask, and 24h volume stream
* [push.index.price](https://api.tardis.dev/v1/data-feeds/mexc-futures?from=2026-07-01\&filters=\[{%22channel%22:%22push.index.price%22,%22symbols%22:\[%22BTC_USDT%22]}]) Perpetual contracts index price stream
* [push.fair.price](https://api.tardis.dev/v1/data-feeds/mexc-futures?from=2026-07-01\&filters=\[{%22channel%22:%22push.fair.price%22,%22symbols%22:\[%22BTC_USDT%22]}]) Perpetual contracts fair price stream
* [push.funding.rate](https://api.tardis.dev/v1/data-feeds/mexc-futures?from=2026-07-01\&filters=\[{%22channel%22:%22push.funding.rate%22,%22symbols%22:\[%22BTC_USDT%22]}]) Perpetual contracts funding rate updates stream
* [push.contract](https://api.tardis.dev/v1/data-feeds/mexc-futures?from=2026-07-01\&filters=\[{%22channel%22:%22push.contract%22}]) Perpetual contracts metadata updates stream. This channel is available in raw exchange-native format only.
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for MEXC Futures is located in GCP asia-northeast1 region (Tokyo, Japan).
Real-time market data is captured via **multiple WebSocket connections** to `wss://contract.mexc.com/edge`.
{% hint style="info" %}
MEXC Futures servers are located in AWS ap-northeast-1 region (Tokyo, Japan).
{% endhint %}
# Crypto.com
Crypto.com exchange historical market data details - instruments, data coverage and data collection specifics
Crypto.com exchange historical data for **all its instruments** is available since **2022-06-01**.
{% embed url="" %}
See Crypto.com exchange 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | ----------- | ---------- | -------------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTCUSD-PERP | 2023-03-01 | [Download sample](https://datasets.tardis.dev/v1/crypto-com/incremental_book_L2/2023/03/01/BTCUSD-PERP.csv.gz) |
| trades | BTCUSD-PERP | 2023-03-01 | [Download sample](https://datasets.tardis.dev/v1/crypto-com/trades/2023/03/01/BTCUSD-PERP.csv.gz) |
| derivative\_ticker | BTCUSD-PERP | 2023-03-01 | [Download sample](https://datasets.tardis.dev/v1/crypto-com/derivative_ticker/2023/03/01/BTCUSD-PERP.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time Crypto.com Exchange WebSocket **Market Data API v1** () with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/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="crypto-com",
from_date="2024-01-01",
to_date="2024-01-02",
filters=[Channel(name="book", symbols=["BTCUSD-PERP"])],
api_key="YOUR_API_KEY",
):
# messages as provided by Crypto.com exchange real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'crypto-com',
from: '2024-01-01',
to: '2024-01-02',
filters: [{ channel: 'book', symbols: ['BTCUSD-PERP'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Crypto.com exchange real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/crypto-com?from=2024-01-01&filters=[{"channel":"book","symbols":["BTCUSD-PERP"]}]&offset=0'
```
{% embed url="" %}
Example API response for Crypto.com exchange historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"crypto-com","filters":[{"channel":"book","symbols":["BTCUSD-PERP"]}],"from":"2024-01-01","to":"2024-01-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See Crypto.com exchange docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [trade](https://api.tardis.dev/v1/data-feeds/crypto-com?from=2024-01-01\&filters=\[{%22channel%22:%22trade%22}]) Trade executions stream
* [book](https://api.tardis.dev/v1/data-feeds/crypto-com?from=2024-01-01\&filters=\[{%22channel%22:%22book%22}]) Order book snapshots and updates stream with 5s heartbeat when unchanged
* [ticker](https://api.tardis.dev/v1/data-feeds/crypto-com?from=2024-01-01\&filters=\[{%22channel%22:%22ticker%22}]) Best bid/ask, last price and 24h stats stream
* [index](https://api.tardis.dev/v1/data-feeds/crypto-com?from=2024-01-01\&filters=\[{%22channel%22:%22index%22}]) — available since **2022-11-02** Index price updates stream
* [mark](https://api.tardis.dev/v1/data-feeds/crypto-com?from=2024-01-01\&filters=\[{%22channel%22:%22mark%22}]) — available since **2022-11-02** Mark price updates stream
* [funding](https://api.tardis.dev/v1/data-feeds/crypto-com?from=2024-01-01\&filters=\[{%22channel%22:%22funding%22}]) — available since **2022-11-01** Funding rate updates stream
* [estimatedfunding](https://api.tardis.dev/v1/data-feeds/crypto-com?from=2025-01-01\&filters=\[{%22channel%22:%22estimatedfunding%22}]) Estimated funding rate updates stream
* [settlement](https://api.tardis.dev/v1/data-feeds/crypto-com?from=2025-01-01\&filters=\[{%22channel%22:%22settlement%22}]) — available since **2022-11-01** Settlement price and event updates stream
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for Crypto.com exchange is located in GCP asia-northeast1 (Tokyo, Japan).
Real-time market data is captured via **multiple WebSocket connections** to `wss://stream.crypto.com/exchange/v1/market` (proxied via Cloudflare).
{% hint style="info" %}
Crypto.com exchange servers are located in AWS ap-northeast-1 region (Tokyo, Japan).
{% endhint %}
# Bitstamp
Bitstamp historical market data details - currency pairs, data coverage and data collection specifics
Bitstamp historical data for **all its currency pairs** is available since **2019-03-30**.
{% embed url="" %}
See Bitstamp 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | ------ | ---------- | ------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTCUSD | 2019-07-01 | [Download sample](https://datasets.tardis.dev/v1/bitstamp/incremental_book_L2/2019/07/01/BTCUSD.csv.gz) |
| trades | BTCUSD | 2019-07-01 | [Download sample](https://datasets.tardis.dev/v1/bitstamp/trades/2019/07/01/BTCUSD.csv.gz) |
| quotes | BTCUSD | 2019-07-01 | [Download sample](https://datasets.tardis.dev/v1/bitstamp/quotes/2019/07/01/BTCUSD.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time Bitstamp WebSocket **v2** with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/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="bitstamp",
from_date="2023-03-01",
to_date="2023-03-02",
filters=[Channel(name="diff_order_book", symbols=["btcusd"])],
api_key="YOUR_API_KEY",
):
# messages as provided by Bitstamp real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'bitstamp',
from: '2023-03-01',
to: '2023-03-02',
filters: [{ channel: 'diff_order_book', symbols: ['btcusd'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Bitstamp real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/bitstamp?from=2023-03-01&filters=[{"channel":"diff_order_book","symbols":["btcusd"]}]&offset=0'
```
{% embed url="" %}
Example API response for Bitstamp historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"bitstamp","filters":[{"channel":"diff_order_book","symbols":["btcusd"]}],"from":"2023-03-01","to":"2023-03-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See Bitstamp WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [live\_trades](https://api.tardis.dev/v1/data-feeds/bitstamp?from=2024-01-01\&filters=\[{%22channel%22:%22live_trades%22}]) Public trade executions stream
* [diff\_order\_book](https://api.tardis.dev/v1/data-feeds/bitstamp?from=2024-01-01\&filters=\[{%22channel%22:%22diff_order_book%22}]) Order book delta stream
* [live\_orders](https://api.tardis.dev/v1/data-feeds/bitstamp?from=2024-01-01\&filters=\[{%22channel%22:%22live_orders%22}]) Level 3 live order events stream
Bitstamp real-time WebSocket API **does not provide initial full order book snapshots** for `diff_order_book` and `live_orders` channels subscriptions. To overcome this issue we fetch initial order book snapshots from REST API and store them together with the rest of the WebSocket messages. Such snapshot messages are marked with `"event": "snapshot"` and `"generated": true` fields for respective channels.
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for Bitstamp is located in GCP europe-west2 region (London, UK).
Real-time market data is captured via **multiple WebSocket connections** to `wss://ws.bitstamp.net`.
{% hint style="info" %}
Bitstamp servers are located in AWS eu-central-1 region (Frankfurt, Germany).
{% endhint %}
# Bitget Futures
Bitget Futures historical market data details - currency pairs, data coverage and data collection specifics
Bitget Futures historical data is available since **2024-11-08**.
{% embed url="" %}
See Bitget Futures 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | ------- | ---------- | -------------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTCUSDT | 2024-12-01 | [Download sample](https://datasets.tardis.dev/v1/bitget-futures/incremental_book_L2/2024/12/01/BTCUSDT.csv.gz) |
| trades | BTCUSDT | 2024-12-01 | [Download sample](https://datasets.tardis.dev/v1/bitget-futures/trades/2024/12/01/BTCUSDT.csv.gz) |
| derivative\_ticker | BTCUSDT | 2024-12-01 | [Download sample](https://datasets.tardis.dev/v1/bitget-futures/derivative_ticker/2024/12/01/BTCUSDT.csv.gz) |
| book\_ticker | BTCUSDT | 2025-01-01 | [Download sample](https://datasets.tardis.dev/v1/bitget-futures/book_ticker/2025/01/01/BTCUSDT.csv.gz) |
| liquidations | BTCUSDT | 2026-05-01 | [Download sample](https://datasets.tardis.dev/v1/bitget-futures/liquidations/2026/05/01/BTCUSDT.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time Bitget Futures WebSocket API with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/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="bitget-futures",
from_date="2026-05-01",
to_date="2026-05-02",
filters=[Channel(name="books", symbols=["BTCUSDT"])],
api_key="YOUR_API_KEY",
):
# messages as provided by Bitget Futures real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'bitget-futures',
from: '2026-05-01',
to: '2026-05-02',
filters: [{ channel: 'books', symbols: ['BTCUSDT'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Bitget Futures real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/bitget-futures?from=2026-05-01&filters=[{"channel":"books","symbols":["BTCUSDT"]}]&offset=0'
```
{% embed url="" %}
Example API response for Bitget Futures historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"bitget-futures","filters":[{"channel":"books","symbols":["BTCUSDT"]}],"from":"2026-05-01","to":"2026-05-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See Bitget Futures WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
**Current channels (API v3, since 2026-04-28):**
* [publicTrade](https://api.tardis.dev/v1/data-feeds/bitget-futures?from=2026-05-01\&filters=\[{%22channel%22:%22publicTrade%22,%22symbols%22:\[%22BTCUSDT%22]}]) Futures public trade executions stream
* [books](https://api.tardis.dev/v1/data-feeds/bitget-futures?from=2026-05-01\&filters=\[{%22channel%22:%22books%22,%22symbols%22:\[%22BTCUSDT%22]}]) Full-depth futures order book snapshots and incremental updates stream, pushed every 50ms. During data collection, order book integrity is validated using Bitget `seq` and `pseq` fields.
* [books1](https://api.tardis.dev/v1/data-feeds/bitget-futures?from=2026-05-01\&filters=\[{%22channel%22:%22books1%22,%22symbols%22:\[%22BTCUSDT%22]}]) Futures best bid and ask snapshots stream. Since 2026-04-28 collected through Bitget WebSocket API v3 at 1ms; before that, collected through API v2 at 10ms.
* [ticker](https://api.tardis.dev/v1/data-feeds/bitget-futures?from=2026-05-01\&filters=\[{%22channel%22:%22ticker%22,%22symbols%22:\[%22BTCUSDT%22]}]) Futures ticker with funding rate, open interest, mark price and index price. Since 2026-04-28 collected through Bitget WebSocket API v3 at 300ms; before that, collected through API v2 at 150ms.
* [liquidation](https://api.tardis.dev/v1/data-feeds/bitget-futures?from=2026-05-01\&filters=\[{%22channel%22:%22liquidation%22}]) — available since **2026-04-28** Futures liquidation events stream, pushed every 20s or when 10,000 liquidation records are accumulated.
**Legacy channels (API v2, until 2026-04-28):**
* [trade](https://api.tardis.dev/v1/data-feeds/bitget-futures?from=2025-01-01\&filters=\[{%22channel%22:%22trade%22}]) Futures public trade executions stream
* [books15](https://api.tardis.dev/v1/data-feeds/bitget-futures?from=2025-01-01\&filters=\[{%22channel%22:%22books15%22,%22symbols%22:\[%22BTCUSDT%22]}]) Futures order book snapshots at depth 15, pushed every 150ms
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for Bitget Futures is located in GCP asia-northeast1 (Tokyo, Japan).
Real-time market data is captured via **multiple WebSocket connections** to `wss://ws.bitget.com/v3/ws/public` from 2026-04-28. Before that date, data was captured from Bitget WebSocket API v2 at `wss://ws.bitget.com/v2/ws/public`.
{% hint style="info" %}
Bitget Futures servers are located in AWS ap-northeast-1 region (Tokyo, Japan).
{% endhint %}
# Bitget Spot
Bitget historical market data details - currency pairs, data coverage and data collection specifics
Bitget historical data is available since **2024-11-08**.
{% embed url="" %}
See Bitget 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| ------------------ | ------- | ---------- | --------------------------------------------------------------------------------------------------- |
| trades | BTCUSDT | 2024-12-01 | [Download sample](https://datasets.tardis.dev/v1/bitget/trades/2024/12/01/BTCUSDT.csv.gz) |
| quotes | BTCUSDT | 2024-12-01 | [Download sample](https://datasets.tardis.dev/v1/bitget/quotes/2024/12/01/BTCUSDT.csv.gz) |
| book\_snapshot\_25 | BTCUSDT | 2024-12-01 | [Download sample](https://datasets.tardis.dev/v1/bitget/book_snapshot_25/2024/12/01/BTCUSDT.csv.gz) |
| book\_ticker | BTCUSDT | 2025-01-01 | [Download sample](https://datasets.tardis.dev/v1/bitget/book_ticker/2025/01/01/BTCUSDT.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time Bitget WebSocket API with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/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="bitget",
from_date="2026-05-01",
to_date="2026-05-02",
filters=[Channel(name="books", symbols=["BTCUSDT"])],
api_key="YOUR_API_KEY",
):
# messages as provided by Bitget real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'bitget',
from: '2026-05-01',
to: '2026-05-02',
filters: [{ channel: 'books', symbols: ['BTCUSDT'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Bitget real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/bitget?from=2026-05-01&filters=[{"channel":"books","symbols":["BTCUSDT"]}]&offset=0'
```
{% embed url="" %}
Example API response for Bitget historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"bitget","filters":[{"channel":"books","symbols":["BTCUSDT"]}],"from":"2026-05-01","to":"2026-05-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See Bitget WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
**Current channels (API v3, since 2026-04-28):**
* [publicTrade](https://api.tardis.dev/v1/data-feeds/bitget?from=2026-05-01\&filters=\[{%22channel%22:%22publicTrade%22,%22symbols%22:\[%22BTCUSDT%22]}]) Spot public trade executions stream
* [books](https://api.tardis.dev/v1/data-feeds/bitget?from=2026-05-01\&filters=\[{%22channel%22:%22books%22,%22symbols%22:\[%22BTCUSDT%22]}]) Full-depth spot order book snapshots and incremental updates stream, pushed every 50ms. During data collection, order book integrity is validated using Bitget `seq` and `pseq` fields.
* [books1](https://api.tardis.dev/v1/data-feeds/bitget?from=2026-05-01\&filters=\[{%22channel%22:%22books1%22,%22symbols%22:\[%22BTCUSDT%22]}]) Spot best bid and ask snapshots stream. Since 2026-04-28 collected through Bitget WebSocket API v3 at 1ms; before that, collected through API v2 at 10ms.
**Legacy channels (API v2, until 2026-04-28):**
* [trade](https://api.tardis.dev/v1/data-feeds/bitget?from=2025-01-01\&filters=\[{%22channel%22:%22trade%22}]) Spot public trade executions stream
* [books15](https://api.tardis.dev/v1/data-feeds/bitget?from=2025-01-01\&filters=\[{%22channel%22:%22books15%22,%22symbols%22:\[%22BTCUSDT%22]}]) Spot order book snapshots at depth 15, pushed every 200ms
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for Bitget is located in GCP asia-northeast1 (Tokyo, Japan).
Real-time market data is captured via **multiple WebSocket connections** to `wss://ws.bitget.com/v3/ws/public` from 2026-04-28. Before that date, data was captured from Bitget WebSocket API v2 at `wss://ws.bitget.com/v2/ws/public`.
{% hint style="info" %}
Bitget Spot servers are located in AWS ap-northeast-1 region (Tokyo, Japan).
{% endhint %}
# Gate.io Futures
Gate.io Futures historical market data details - available instruments, data coverage and data collection specifics
Gate.io Futures historical data for **all its instruments** is available since **2020-07-01**.
{% embed url="" %}
See Gate.io Futures 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | --------- | ---------- | ---------------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTC\_USDT | 2020-07-01 | [Download sample](https://datasets.tardis.dev/v1/gate-io-futures/incremental_book_L2/2020/07/01/BTC_USDT.csv.gz) |
| trades | BTC\_USDT | 2020-07-01 | [Download sample](https://datasets.tardis.dev/v1/gate-io-futures/trades/2020/07/01/BTC_USDT.csv.gz) |
| derivative\_ticker | BTC\_USDT | 2020-07-01 | [Download sample](https://datasets.tardis.dev/v1/gate-io-futures/derivative_ticker/2020/07/01/BTC_USDT.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time Gate.io Futures **WebSocket v4 API** with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/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="gate-io-futures",
from_date="2024-01-01",
to_date="2024-01-02",
filters=[Channel(name="order_book", symbols=["BTC_USDT"])],
api_key="YOUR_API_KEY",
):
# messages as provided by Gate.io Futures real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'gate-io-futures',
from: '2024-01-01',
to: '2024-01-02',
filters: [{ channel: 'order_book', symbols: ['BTC_USDT'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Gate.io Futures real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/gate-io-futures?from=2024-01-01&filters=[{"channel":"order_book","symbols":["BTC_USDT"]}]&offset=0'
```
{% embed url="" %}
Example API response for Gate.io Futures historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"gate-io-futures","filters":[{"channel":"order_book","symbols":["BTC_USDT"]}],"from":"2024-01-01","to":"2024-01-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See Gate.io Futures WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [trades](https://api.tardis.dev/v1/data-feeds/gate-io-futures?from=2024-01-01\&filters=\[{%22channel%22:%22trades%22}]) Trade executions stream
* [order\_book](https://api.tardis.dev/v1/data-feeds/gate-io-futures?from=2024-01-01\&filters=\[{%22channel%22:%22order_book%22}]) Legacy order book channel providing full depth snapshots. Subscribed with payload \[symbol, "20", "0"] (limit=20, interval=0). Delivers full order book snapshots approximately every 100ms.
* [book\_ticker](https://api.tardis.dev/v1/data-feeds/gate-io-futures?from=2024-01-01\&filters=\[{%22channel%22:%22book_ticker%22}]) — available since **2022-03-17** Best bid and ask price updates stream
* [tickers](https://api.tardis.dev/v1/data-feeds/gate-io-futures?from=2024-01-01\&filters=\[{%22channel%22:%22tickers%22}]) Contract ticker with highest, lowest, last trade price and daily volume
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for Gate.io Futures is located in GCP asia-northeast1 (Tokyo, Japan).
Real-time market data is captured via **multiple WebSocket connections** to `wss://fx-ws.gateio.ws/v4/ws`.
{% hint style="info" %}
Gate.io Futures servers are located in AWS ap-northeast-1 region (Tokyo, Japan).
{% endhint %}
# Gate.io
Gate.io historical market data details - currency pairs, data coverage and data collection specifics
Gate.io historical data for **high caps currency pairs** is available since **2020-07-01**, data for all currency pairs is available since **2022-06-09.**
{% embed url="" %}
See Gate.io 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | --------- | ---------- | -------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTC\_USDT | 2020-07-01 | [Download sample](https://datasets.tardis.dev/v1/gate-io/incremental_book_L2/2020/07/01/BTC_USDT.csv.gz) |
| trades | BTC\_USDT | 2020-07-01 | [Download sample](https://datasets.tardis.dev/v1/gate-io/trades/2020/07/01/BTC_USDT.csv.gz) |
| quotes | BTC\_USDT | 2020-07-01 | [Download sample](https://datasets.tardis.dev/v1/gate-io/quotes/2020/07/01/BTC_USDT.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time Gate.io **WebSocket v4 API** (v3 API for data before 2023-04-29) with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/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="gate-io",
from_date="2025-09-01",
to_date="2025-09-02",
filters=[Channel(name="obu", symbols=["BTC_USDT"])],
api_key="YOUR_API_KEY",
):
# messages as provided by Gate.io real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'gate-io',
from: '2025-09-01',
to: '2025-09-02',
filters: [{ channel: 'obu', symbols: ['BTC_USDT'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Gate.io real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/gate-io?from=2025-09-01&filters=[{"channel":"obu","symbols":["BTC_USDT"]}]&offset=0'
```
{% embed url="" %}
Example API response for Gate.io historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"gate-io","filters":[{"channel":"obu","symbols":["BTC_USDT"]}],"from":"2025-09-01","to":"2025-09-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See Gate.io WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
**Current channels (API v4, since 2023-04-29):**
* [trades](https://api.tardis.dev/v1/data-feeds/gate-io?from=2024-01-01\&filters=\[{%22channel%22:%22trades%22}]) Trade executions stream. Also collected under v3 API until 2023-04-29 with different message format: v3 used method-based params array (trades.update), v4 uses channel-based result object (spot.trades)
* [order\_book\_update](https://api.tardis.dev/v1/data-feeds/gate-io?from=2024-01-01\&filters=\[{%22channel%22:%22order_book_update%22}]) — available since **2023-04-29**, until **2025-08-01** Order book incremental updates stream for local book management. Includes generated initial order book snapshots from REST API (/spot/order\_book). Snapshot messages are marked as "event":"snapshot", "channel":"spot.order\_book\_update" and "generated":true.
* [obu](https://api.tardis.dev/v1/data-feeds/gate-io?from=2025-08-01\&filters=\[{%22channel%22:%22obu%22}]) — available since **2025-08-01** Order book incremental updates with snapshots via WebSocket
* [book\_ticker](https://api.tardis.dev/v1/data-feeds/gate-io?from=2024-01-01\&filters=\[{%22channel%22:%22book_ticker%22}]) — available since **2023-04-29** Best bid and ask price and amount updates stream
**Legacy channels (API v3, until 2023-04-29):**
* [depth](https://api.tardis.dev/v1/data-feeds/gate-io?from=2020-07-01\&filters=\[{%22channel%22:%22depth%22}]) — available until **2023-04-29** Order book snapshots and deltas stream (level 30, interval 0)
* [ticker](https://api.tardis.dev/v1/data-feeds/gate-io?from=2020-07-01\&filters=\[{%22channel%22:%22ticker%22}]) — available until **2023-04-29** Market ticker with 24h stats, best bid/ask and volume
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for Gate.io is located in GCP asia-northeast1 (Tokyo, Japan).
Real-time market data is captured via **multiple WebSocket connections** to `wss://api.gateio.ws/ws/v4`. Until 2023-04-29, data was collected via `wss://ws.gate.io/v3` (API v3).
{% hint style="info" %}
Gate.io servers are located in AWS ap-northeast-1 region (Tokyo, Japan).
{% endhint %}
# HTX Coin-M Futures
HTX Coin-M Futures historical market data details - instruments, data coverage and data collection specifics
HTX Coin-M Futures historical data for **all its instruments** is available since **2019-11-19**.
{% embed url="" %}
See HTX Coin-M Futures 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](/downloadable-csv-files/overview).
{% hint style="info" %}
Derivative ticker datasets are available since 2020-06-24.
{% endhint %}
| data type | symbol | date | |
| --------------------- | ------- | ---------- | ------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTC\_CQ | 2020-02-01 | [Download sample](https://datasets.tardis.dev/v1/huobi-dm/incremental_book_L2/2020/02/01/BTC_CQ.csv.gz) |
| trades | BTC\_CQ | 2020-02-01 | [Download sample](https://datasets.tardis.dev/v1/huobi-dm/trades/2020/02/01/BTC_CQ.csv.gz) |
| derivative\_ticker | BTC\_CQ | 2020-07-01 | [Download sample](https://datasets.tardis.dev/v1/huobi-dm/derivative_ticker/2020/07/01/BTC_CQ.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time HTX Coin-M Futures WebSocket API with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/api/quickstart) that 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="huobi-dm",
from_date="2024-01-01",
to_date="2024-01-02",
filters=[Channel(name="depth", symbols=["BTC_CW"])],
api_key="YOUR_API_KEY",
):
# messages as provided by HTX Coin-M Futures real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'huobi-dm',
from: '2024-01-01',
to: '2024-01-02',
filters: [{ channel: 'depth', symbols: ['BTC_CW'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by HTX Coin-M Futures real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/huobi-dm?from=2024-01-01&filters=[{"channel":"depth","symbols":["BTC_CW"]}]&offset=0'
```
{% embed url="" %}
Example API response for HTX Coin-M Futures historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"huobi-dm","filters":[{"channel":"depth","symbols":["BTC_CW"]}],"from":"2024-01-01","to":"2024-01-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See HTX Coin-M Futures WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [trade](https://api.tardis.dev/v1/data-feeds/huobi-dm?from=2024-01-01\&filters=\[{%22channel%22:%22trade%22}]) Trade executions stream
* [depth](https://api.tardis.dev/v1/data-feeds/huobi-dm?from=2024-01-01\&filters=\[{%22channel%22:%22depth%22}]) Order book snapshots and incremental updates stream. Order book integrity is validated using sequence numbers (`version` field) — on missed message the WebSocket connection is restarted. **See also details below regarding depth channel data collection details.**
* [bbo](https://api.tardis.dev/v1/data-feeds/huobi-dm?from=2024-01-01\&filters=\[{%22channel%22:%22bbo%22}]) — available since **2020-06-23** Best bid and ask quote updates stream
* [liquidation\_orders](https://api.tardis.dev/v1/data-feeds/huobi-dm?from=2024-01-01\&filters=\[{%22channel%22:%22liquidation_orders%22}]) — available since **2020-06-23** Liquidation events stream
* [contract\_info](https://api.tardis.dev/v1/data-feeds/huobi-dm?from=2024-01-01\&filters=\[{%22channel%22:%22contract_info%22}]) — available since **2020-06-23** Contract definition and status updates stream
* [basis](https://api.tardis.dev/v1/data-feeds/huobi-dm?from=2024-01-01\&filters=\[{%22channel%22:%22basis%22}]) — available since **2020-06-23** Basis and index price updates stream
* [open\_interest](https://api.tardis.dev/v1/data-feeds/huobi-dm?from=2024-01-01\&filters=\[{%22channel%22:%22open_interest%22}]) — generated channel, available since **2020-06-23** Generated open interest snapshots from REST endpoint every 4-6 seconds per instrument. Messages are marked with `"ch":"market..open_interest"` and `"generated":true` fields and `data` field has the same format as REST API response data.
* [detail](https://api.tardis.dev/v1/data-feeds/huobi-dm?from=2024-01-01\&filters=\[{%22channel%22:%22detail%22}]) 24h contract statistics stream
* [elite\_account\_ratio](https://api.tardis.dev/v1/data-feeds/huobi-dm?from=2024-01-01\&filters=\[{%22channel%22:%22elite_account_ratio%22}]) — generated channel, available since **2020-10-29** Generated elite account long/short ratio snapshots from REST endpoint using 5min period buckets.
* [elite\_position\_ratio](https://api.tardis.dev/v1/data-feeds/huobi-dm?from=2024-01-01\&filters=\[{%22channel%22:%22elite_position_ratio%22}]) — generated channel, available since **2020-10-29** Generated elite position long/short ratio snapshots from REST endpoint using 5min period buckets.
**Up until 2020-01-31** `depth` channel was collected with `step0` aggregation level (no aggregation) which produces full order book snapshots for each book change which is very inefficient to store. To circumvent this issue we stored only initial book snapshots and then incremental updates instead - incremental updates were calculated by diffing two subsequent book snapshots and provided in the same format as other `depth` messages, except having additional **`update: true`** flag set as in snippet below. Update with amount (second value in array) set to 0 means such level should be deleted, otherwise price level should be updated with new amount value.
```javascript
{
"ch": "market.ETC_CW.depth.step0",
"ts": 1572652860024,
"update": true,
"tick": {
"mrid": 24660973159,
"id": 1572652860,
"bids": [
[
4.869,
1175
]
],
"asks": [],
"ts": 1572652860013,
"version": 1572652860,
"ch": "market.ETC_CW.depth.step0"
}
}
```
**On 2020-01-31** we've switched to `depth.size_150.high_freq` channel instead when collecting data and which natively provides incremental order book updates without workarounds described above.
Unfortunately it means that when requesting data for **`depth`** channel it may return slightly different format depending for which time period request was made. It's only slightly different and boils down to the way order book update messages are marked vs order book snapshots. In `depth.size_150.high_freq` order book message has `event` field always present with value `update` or `snapshot`, for example:
```javascript
{
"ch": "market.LTC_CW.depth.size_150.high_freq",
"tick": {
...
"event": "update",
...
}
}
```
For messages before **2020-01-31** we used the `depth.step0` channel for collecting order book data, which means an order book update message has the `update` flag set to `true`; if it's a snapshot, it doesn't have that flag at all, for example:
```javascript
{
"ch": "market.ETC_CW.depth.step0",
"update": true,
"tick": {
...
}
}
```
All other fields are the same (tick.bids, tick.asks, etc.).
Please feel free to [contact us](https://tardis.dev/#contact) if it's confusing in any way.
We also provide a normalization layer that handles those differences transparently via our [client libs](/api/quickstart).
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for HTX Coin-M Futures is located in GCP asia-northeast1 (Tokyo, Japan).
Real-time market data is captured via **multiple WebSocket connections** to `wss://api.hbdm.vn/ws` (proxied via Cloudflare).
{% hint style="info" %}
HTX servers are located in AWS ap-northeast-1 region (Tokyo, Japan).
{% endhint %}
# HTX Coin-M Perpetual
HTX Coin-M Perpetual historical market data details - instruments, data coverage and data collection specifics
HTX Coin-M Perpetual historical data for **all its instruments** is available since **2020-03-28**.
{% embed url="" %}
See HTX Coin-M Perpetual 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](/downloadable-csv-files/overview).
{% hint style="info" %}
Derivative ticker datasets are available since 2020-06-24.
{% endhint %}
| data type | symbol | date | |
| --------------------- | ------- | ---------- | ------------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTC-USD | 2020-04-01 | [Download sample](https://datasets.tardis.dev/v1/huobi-dm-swap/incremental_book_L2/2020/04/01/BTC-USD.csv.gz) |
| trades | BTC-USD | 2020-04-01 | [Download sample](https://datasets.tardis.dev/v1/huobi-dm-swap/trades/2020/04/01/BTC-USD.csv.gz) |
| derivative\_ticker | BTC-USD | 2020-07-01 | [Download sample](https://datasets.tardis.dev/v1/huobi-dm-swap/derivative_ticker/2020/07/01/BTC-USD.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time HTX Coin-M Perpetual WebSocket API with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/api/quickstart) that 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="huobi-dm-swap",
from_date="2024-01-01",
to_date="2024-01-02",
filters=[Channel(name="depth", symbols=["BTC-USD"])],
api_key="YOUR_API_KEY",
):
# messages as provided by HTX Coin-M Perpetual real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'huobi-dm-swap',
from: '2024-01-01',
to: '2024-01-02',
filters: [{ channel: 'depth', symbols: ['BTC-USD'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by HTX Coin-M Perpetual real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/huobi-dm-swap?from=2024-01-01&filters=[{"channel":"depth","symbols":["BTC-USD"]}]&offset=0'
```
{% embed url="" %}
Example API response for HTX Coin-M Perpetual historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"huobi-dm-swap","filters":[{"channel":"depth","symbols":["BTC-USD"]}],"from":"2024-01-01","to":"2024-01-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See HTX Coin-M Perpetual WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [trade](https://api.tardis.dev/v1/data-feeds/huobi-dm-swap?from=2024-01-01\&filters=\[{%22channel%22:%22trade%22}]) Trade executions stream
* [depth](https://api.tardis.dev/v1/data-feeds/huobi-dm-swap?from=2024-01-01\&filters=\[{%22channel%22:%22depth%22}]) Order book snapshots and incremental updates stream (depth.size\_150.high\_freq). Order book integrity is validated using sequence numbers (`version` field) — on missed message the WebSocket connection is restarted.
* [bbo](https://api.tardis.dev/v1/data-feeds/huobi-dm-swap?from=2024-01-01\&filters=\[{%22channel%22:%22bbo%22}]) — available since **2020-08-17** Best bid and ask quote updates stream
* [liquidation\_orders](https://api.tardis.dev/v1/data-feeds/huobi-dm-swap?from=2024-01-01\&filters=\[{%22channel%22:%22liquidation_orders%22}]) — available since **2020-06-23** Liquidation events stream
* [basis](https://api.tardis.dev/v1/data-feeds/huobi-dm-swap?from=2024-01-01\&filters=\[{%22channel%22:%22basis%22}]) — available since **2020-06-23** Basis and index price updates stream
* [funding\_rate](https://api.tardis.dev/v1/data-feeds/huobi-dm-swap?from=2024-01-01\&filters=\[{%22channel%22:%22funding_rate%22}]) — available since **2020-06-23** Funding rate updates stream
* [open\_interest](https://api.tardis.dev/v1/data-feeds/huobi-dm-swap?from=2024-01-01\&filters=\[{%22channel%22:%22open_interest%22}]) — available since **2020-06-23** — generated channel Generated open interest snapshots from REST endpoint every 4-6 seconds per instrument. Messages marked as `"ch":"market..open_interest"` and `"generated":true` with data field in the same format as REST API response.
* [detail](https://api.tardis.dev/v1/data-feeds/huobi-dm-swap?from=2024-01-01\&filters=\[{%22channel%22:%22detail%22}]) 24h contract statistics stream
* [contract\_info](https://api.tardis.dev/v1/data-feeds/huobi-dm-swap?from=2024-01-01\&filters=\[{%22channel%22:%22contract_info%22}]) — available since **2020-06-23** Contract definition and status updates stream
* [elite\_account\_ratio](https://api.tardis.dev/v1/data-feeds/huobi-dm-swap?from=2024-01-01\&filters=\[{%22channel%22:%22elite_account_ratio%22}]) — available since **2020-10-29** — generated channel Generated elite account long/short ratio snapshots from REST endpoint using 5min period buckets.
* [elite\_position\_ratio](https://api.tardis.dev/v1/data-feeds/huobi-dm-swap?from=2024-01-01\&filters=\[{%22channel%22:%22elite_position_ratio%22}]) — available since **2020-10-29** — generated channel Generated elite position long/short ratio snapshots from REST endpoint using 5min period buckets.
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for HTX Coin-M Perpetual is located in GCP asia-northeast1 (Tokyo, Japan).
Real-time market data is captured via **multiple WebSocket connections** to `wss://api.hbdm.vn/swap-ws` (proxied via Cloudflare).
{% hint style="info" %}
HTX servers are located in AWS ap-northeast-1 region (Tokyo, Japan).
{% endhint %}
# HTX USDT-M Contracts
HTX USDT-M Contracts historical market data details - instruments, data coverage and data collection specifics
HTX USDT-M Contracts historical data for **all its instruments** is available since **2020-10-30**.
{% embed url="" %}
See HTX USDT-M Contracts 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | -------- | ---------- | --------------------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTC-USDT | 2023-03-01 | [Download sample](https://datasets.tardis.dev/v1/huobi-dm-linear-swap/incremental_book_L2/2023/03/01/BTC-USDT.csv.gz) |
| trades | BTC-USDT | 2023-03-01 | [Download sample](https://datasets.tardis.dev/v1/huobi-dm-linear-swap/trades/2023/03/01/BTC-USDT.csv.gz) |
| derivative\_ticker | BTC-USDT | 2023-03-01 | [Download sample](https://datasets.tardis.dev/v1/huobi-dm-linear-swap/derivative_ticker/2023/03/01/BTC-USDT.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time HTX USDT-M Contracts WebSocket API with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/api/quickstart) that 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="huobi-dm-linear-swap",
from_date="2024-01-01",
to_date="2024-01-02",
filters=[Channel(name="depth", symbols=["BTC-USDT"])],
api_key="YOUR_API_KEY",
):
# messages as provided by HTX USDT-M Contracts real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'huobi-dm-linear-swap',
from: '2024-01-01',
to: '2024-01-02',
filters: [{ channel: 'depth', symbols: ['BTC-USDT'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by HTX USDT-M Contracts real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/huobi-dm-linear-swap?from=2024-01-01&filters=[{"channel":"depth","symbols":["BTC-USDT"]}]&offset=0'
```
{% embed url="" %}
Example API response for HTX USDT-M Contracts historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"huobi-dm-linear-swap","filters":[{"channel":"depth","symbols":["BTC-USDT"]}],"from":"2024-01-01","to":"2024-01-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See HTX USDT-M Contracts WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [trade](https://api.tardis.dev/v1/data-feeds/huobi-dm-linear-swap?from=2024-01-01\&filters=\[{%22channel%22:%22trade%22}]) Trade executions stream
* [depth](https://api.tardis.dev/v1/data-feeds/huobi-dm-linear-swap?from=2024-01-01\&filters=\[{%22channel%22:%22depth%22}]) Order book snapshots and incremental updates stream. Order book integrity is validated using sequence numbers (`version` field) — on missed message the WebSocket connection is restarted. Uses `depth.size_150.high_freq` which natively provides incremental updates with `"event":"update"|"snapshot"` field.
* [bbo](https://api.tardis.dev/v1/data-feeds/huobi-dm-linear-swap?from=2024-01-01\&filters=\[{%22channel%22:%22bbo%22}]) Best bid and ask quote updates stream
* [liquidation\_orders](https://api.tardis.dev/v1/data-feeds/huobi-dm-linear-swap?from=2024-01-01\&filters=\[{%22channel%22:%22liquidation_orders%22}]) Liquidation events stream
* [basis](https://api.tardis.dev/v1/data-feeds/huobi-dm-linear-swap?from=2024-01-01\&filters=\[{%22channel%22:%22basis%22}]) Basis and index price updates stream
* [funding\_rate](https://api.tardis.dev/v1/data-feeds/huobi-dm-linear-swap?from=2024-01-01\&filters=\[{%22channel%22:%22funding_rate%22}]) Funding rate updates stream
* [open\_interest](https://api.tardis.dev/v1/data-feeds/huobi-dm-linear-swap?from=2024-01-01\&filters=\[{%22channel%22:%22open_interest%22}]) — generated channel Generated open interest snapshots from REST endpoint every 4-6 seconds per instrument. Messages marked as `"ch":"market..open_interest"` and `"generated":true` with `data` field in the same format as REST API response.
* [detail](https://api.tardis.dev/v1/data-feeds/huobi-dm-linear-swap?from=2024-01-01\&filters=\[{%22channel%22:%22detail%22}]) 24h contract statistics stream
* [contract\_info](https://api.tardis.dev/v1/data-feeds/huobi-dm-linear-swap?from=2024-01-01\&filters=\[{%22channel%22:%22contract_info%22}]) Contract definition and status updates stream
* [elite\_account\_ratio](https://api.tardis.dev/v1/data-feeds/huobi-dm-linear-swap?from=2024-01-01\&filters=\[{%22channel%22:%22elite_account_ratio%22}]) — generated channel Generated elite account long/short ratio snapshots from REST endpoint using 5min period buckets.
* [elite\_position\_ratio](https://api.tardis.dev/v1/data-feeds/huobi-dm-linear-swap?from=2024-01-01\&filters=\[{%22channel%22:%22elite_position_ratio%22}]) — generated channel Generated elite position long/short ratio snapshots from REST endpoint using 5min period buckets.
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for HTX USDT-M Contracts is located in GCP asia-northeast1 (Tokyo, Japan).
Real-time market data is captured via **multiple WebSocket connections** to `wss://api.hbdm.vn/linear-swap-ws` (proxied via Cloudflare).
{% hint style="info" %}
HTX servers are located in AWS ap-northeast-1 region (Tokyo, Japan).
{% endhint %}
# HTX Spot
HTX Spot historical market data details - currency pairs, data coverage and data collection specifics
HTX Spot historical data for **high caps currency pairs** is available since **2019-11-19,** data for all currency pairs is available since **2022-06-09**.
{% embed url="" %}
See HTX Spot 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | ------- | ---------- | ----------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTCUSDT | 2019-12-01 | [Download sample](https://datasets.tardis.dev/v1/huobi/incremental_book_L2/2019/12/01/BTCUSDT.csv.gz) |
| trades | BTCUSDT | 2019-12-01 | [Download sample](https://datasets.tardis.dev/v1/huobi/trades/2019/12/01/BTCUSDT.csv.gz) |
| quotes | BTCUSDT | 2019-12-01 | [Download sample](https://datasets.tardis.dev/v1/huobi/quotes/2019/12/01/BTCUSDT.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time HTX Spot WebSocket API with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/api/quickstart) that 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="huobi",
from_date="2024-01-01",
to_date="2024-01-02",
filters=[Channel(name="mbp", symbols=["btcusdt"])],
api_key="YOUR_API_KEY",
):
# messages as provided by HTX Spot real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'huobi',
from: '2024-01-01',
to: '2024-01-02',
filters: [{ channel: 'mbp', symbols: ['btcusdt'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by HTX Spot real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/huobi?from=2024-01-01&filters=[{"channel":"mbp","symbols":["btcusdt"]}]&offset=0'
```
{% embed url="" %}
Example API response for HTX Spot historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"huobi","filters":[{"channel":"mbp","symbols":["btcusdt"]}],"from":"2024-01-01","to":"2024-01-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See HTX Spot WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [trade](https://api.tardis.dev/v1/data-feeds/huobi?from=2024-01-01\&filters=\[{%22channel%22:%22trade%22,%22symbols%22:\[%22btcusdt%22]}]) Trade executions stream
* [depth](https://api.tardis.dev/v1/data-feeds/huobi?from=2020-12-01\&filters=\[{%22channel%22:%22depth%22,%22symbols%22:\[%22btcusdt%22]}]) — available **until 2020-12-10** Legacy full depth snapshots stream replaced by mbp. Collected with `step0` aggregation level. Publishes full order book snapshots which are stored as initial snapshot plus incremental updates (calculated by diffing subsequent snapshots, marked with `"update": true` flag).
* [mbp](https://api.tardis.dev/v1/data-feeds/huobi?from=2024-01-01\&filters=\[{%22channel%22:%22mbp%22,%22symbols%22:\[%22btcusdt%22]}]) — available since **2020-07-03** Market by price incremental updates stream. Subscribed as mbp.150 (150-level) until 2021-08-26, after that as mbp.400 (400-level). MBP feed is based on snapshots at 100ms interval via /feed endpoint. Initial order book snapshot is fetched via "req" request on the same WebSocket connection. During data collection integrity of incremental updates is validated using sequence numbers (seqNum and prevSeqNum) — on sequence gap a new snapshot is requested automatically.
* [mbp.20](https://api.tardis.dev/v1/data-feeds/huobi?from=2024-01-01\&filters=\[{%22channel%22:%22mbp.20%22,%22symbols%22:\[%22btcusdt%22]}]) — available since **2022-05-27** Market by price 20-level incremental updates stream. Tick by tick feed via /feed endpoint. Only collected for select high-cap symbols. Initial order book snapshot is fetched via "req" request.
* [bbo](https://api.tardis.dev/v1/data-feeds/huobi?from=2024-01-01\&filters=\[{%22channel%22:%22bbo%22,%22symbols%22:\[%22btcusdt%22]}]) Best bid and ask quote updates stream
* [detail](https://api.tardis.dev/v1/data-feeds/huobi?from=2024-01-01\&filters=\[{%22channel%22:%22detail%22,%22symbols%22:\[%22btcusdt%22]}]) 24h market statistics stream
* [etp](https://api.tardis.dev/v1/data-feeds/huobi?from=2022-11-01\&filters=\[{%22channel%22:%22etp%22}]) — available since **2020-08-17**, available **until 2022-11-22** Leveraged token NAV and premium updates stream
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for HTX Spot is located in GCP asia-northeast1 region (Tokyo, Japan). Before **2020-06-19** it was located in GCP europe-west2 region (London, UK).
Real-time market data is captured via **multiple WebSocket connections** to `wss://api-aws.huobi.pro/ws`.
{% hint style="info" %}
HTX servers are located in AWS ap-northeast-1 region (Tokyo, Japan).
{% endhint %}
# Gemini
Gemini historical market data details - instruments, data coverage and data collection specifics
Gemini exchange historical data for **all its supported instruments** is available since **2019-08-30**.
{% embed url="" %}
See Gemini 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | ------ | ---------- | ----------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTCUSD | 2020-01-01 | [Download sample](https://datasets.tardis.dev/v1/gemini/incremental_book_L2/2020/01/01/BTCUSD.csv.gz) |
| trades | BTCUSD | 2020-01-01 | [Download sample](https://datasets.tardis.dev/v1/gemini/trades/2020/01/01/BTCUSD.csv.gz) |
| quotes | BTCUSD | 2020-01-01 | [Download sample](https://datasets.tardis.dev/v1/gemini/quotes/2020/01/01/BTCUSD.csv.gz) |
| book\_ticker | BTCUSD | 2026-08-01 | [Download sample](https://datasets.tardis.dev/v1/gemini/book_ticker/2026/08/01/BTCUSD.csv.gz) |
### API Access and data format
Historical data uses the exchange-native Gemini WebSocket format with the addition of local timestamps. Data recorded before **2026-07-24** UTC uses Gemini **Market Data Version 2**; data recorded from **2026-07-24** UTC uses Gemini WebSocket API **v3**.
Gemini v3 raw payloads use lowercase symbols, for example `btcusd`. For backward compatibility with Gemini v2, whose raw payloads used uppercase symbols, Tardis symbol IDs and normalized messages remain uppercase. Gemini symbol filters are case-insensitive, so existing filters such as `BTCUSD` continue to match v3 messages for `btcusd`.
If you'd like to work with **normalized data format** instead (same format for each exchange), see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/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="gemini",
from_date="2026-08-01",
to_date="2026-08-02",
filters=[Channel(name="depth", symbols=["BTCUSD"])],
api_key="YOUR_API_KEY",
):
# messages as provided by Gemini real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'gemini',
from: '2026-08-01',
to: '2026-08-02',
filters: [{ channel: 'depth', symbols: ['BTCUSD'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Gemini real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/gemini?from=2026-08-01&filters=[{"channel":"depth","symbols":["BTCUSD"]}]&offset=0'
```
{% embed url="" %}
Example API response for Gemini historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"gemini","filters":[{"channel":"depth","symbols":["BTCUSD"]}],"from":"2026-08-01","to":"2026-08-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See Gemini WebSocket API docs for current channel formats
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
**Current channels (API v3, since 2026-07-24):**
* [trade](https://api.tardis.dev/v1/data-feeds/gemini?from=2026-08-01\&filters=\[{%22channel%22:%22trade%22}]) Public trade executions stream
* [depth](https://api.tardis.dev/v1/data-feeds/gemini?from=2026-08-01\&filters=\[{%22channel%22:%22depth%22}]) Incremental level 2 order book updates captured from Gemini's `{symbol}@depth@100ms` stream. Collection uses `snapshot=-1`, so the first `depthUpdate` for each symbol and connection is a full order book snapshot; subsequent messages are incremental updates.
* [bookTicker](https://api.tardis.dev/v1/data-feeds/gemini?from=2026-08-01\&filters=\[{%22channel%22:%22bookTicker%22}]) Best bid and ask price and quantity updates
**Legacy channels (API v2, until 2026-07-24):**
Legacy v2 message formats are documented in the [archived Gemini Market Data Version 2 documentation](https://web.archive.org/web/20250130160317/https://docs.gemini.com/websocket-api/#market-data-version-2).
* [trade](https://api.tardis.dev/v1/data-feeds/gemini?from=2024-01-01\&filters=\[{%22channel%22:%22trade%22}]) Public trade executions stream
* [l2\_updates](https://api.tardis.dev/v1/data-feeds/gemini?from=2024-01-01\&filters=\[{%22channel%22:%22l2_updates%22}]) Level 2 order book deltas stream
* [auction\_open](https://api.tardis.dev/v1/data-feeds/gemini?from=2024-01-01\&filters=\[{%22channel%22:%22auction_open%22}]) Auction open events stream
* [auction\_indicative](https://api.tardis.dev/v1/data-feeds/gemini?from=2024-01-01\&filters=\[{%22channel%22:%22auction_indicative%22}]) Auction indicative price and quantity updates
* [auction\_result](https://api.tardis.dev/v1/data-feeds/gemini?from=2024-01-01\&filters=\[{%22channel%22:%22auction_result%22}]) Auction result events stream
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for Gemini is located in GCP europe-west2 region (London, UK).
Real-time market data is captured via **multiple WebSocket connections** to Gemini WebSocket API v3 at `wss://ws.gemini.com?snapshot=-1`. Before **2026-07-24**, data was captured from API v2 at `wss://api.gemini.com/v2/marketdata`.
{% hint style="info" %}
Gemini exchange servers are located in AWS us-east-1 region (N. Virginia, North America).
{% endhint %}
# WOO X
WOO X historical market data details - instruments, data coverage and data collection specifics
WOO X exchange historical data for **all its instruments** is available since **2023-01-20**.
{% embed url="" %}
See WOO X 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | --------------- | ---------- | ----------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | SPOT\_BTC\_USDT | 2023-02-01 | [Download sample](https://datasets.tardis.dev/v1/woo-x/incremental_book_L2/2023/02/01/SPOT_BTC_USDT.csv.gz) |
| trades | SPOT\_BTC\_USDT | 2023-02-01 | [Download sample](https://datasets.tardis.dev/v1/woo-x/trades/2023/02/01/SPOT_BTC_USDT.csv.gz) |
| derivative\_ticker | PERP\_BTC\_USDT | 2023-02-01 | [Download sample](https://datasets.tardis.dev/v1/woo-x/derivative_ticker/2023/02/01/PERP_BTC_USDT.csv.gz) |
### API Access and data format
For data since **2026-06-29 22:00 UTC**, historical data format is the same as provided by real-time WOO X WebSocket **Market Data API v3** () with addition of local timestamps. Before that, WOO X data was captured from **Market Data API v2** (). Public Tardis channel names stayed the same, but native message payloads follow the WOO X API version used at the replay timestamp. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/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="woo-x",
from_date="2026-07-01",
to_date="2026-07-02",
filters=[Channel(name="orderbook", symbols=["PERP_BTC_USDT"])],
api_key="YOUR_API_KEY",
):
# messages as provided by WOO X real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'woo-x',
from: '2026-07-01',
to: '2026-07-02',
filters: [{ channel: 'orderbook', symbols: ['PERP_BTC_USDT'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by WOO X real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/woo-x?from=2026-07-01&filters=[{"channel":"orderbook","symbols":["PERP_BTC_USDT"]}]&offset=0'
```
{% embed url="" %}
Example API response for Woo X historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"woo-x","filters":[{"channel":"orderbook","symbols":["PERP_BTC_USDT"]}],"from":"2026-07-01","to":"2026-07-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See WOO X WebSocket v3 API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [trade](https://api.tardis.dev/v1/data-feeds/woo-x?from=2026-07-01\&filters=\[{%22channel%22:%22trade%22}]) Public trade executions stream
* [orderbook](https://api.tardis.dev/v1/data-feeds/woo-x?from=2026-07-01\&filters=\[{%22channel%22:%22orderbook%22}]) — generated channel Initial order book snapshots from REST API used to bootstrap `orderbookupdate` stream. Since **2026-06-29 22:00 UTC**, snapshots are fetched from WOO X V3 public orderbook API with `maxLevel=50` and stored as V3-like messages with `topic:"orderbook@@50"`, `generated:true`, `data` from the REST response and `ts` from the REST response timestamp. Before that, generated snapshots used the legacy WebSocket order book request flow.
* [orderbookupdate](https://api.tardis.dev/v1/data-feeds/woo-x?from=2026-07-01\&filters=\[{%22channel%22:%22orderbookupdate%22}]) Order book incremental updates. Since **2026-06-29 22:00 UTC**, collected from WOO X V3 `orderbookupdate@{symbol}@50` at `50ms`; before that, WOO X V2 provided this channel at `200ms`.
* [bbo](https://api.tardis.dev/v1/data-feeds/woo-x?from=2026-07-01\&filters=\[{%22channel%22:%22bbo%22}]) Best bid and ask updates
* [indexprice](https://api.tardis.dev/v1/data-feeds/woo-x?from=2026-07-01\&filters=\[{%22channel%22:%22indexprice%22}]) Index price updates
* [markprice](https://api.tardis.dev/v1/data-feeds/woo-x?from=2026-07-01\&filters=\[{%22channel%22:%22markprice%22}]) Mark price updates
* [openinterest](https://api.tardis.dev/v1/data-feeds/woo-x?from=2026-07-01\&filters=\[{%22channel%22:%22openinterest%22}]) Open interest updates. Since **2026-06-29 22:00 UTC**, WOO X V3 pushes every `1s` when open interest changes and forces an update every `10s` when unchanged; before that, WOO X V2 frequency was `10s`.
* [estfundingrate](https://api.tardis.dev/v1/data-feeds/woo-x?from=2026-07-01\&filters=\[{%22channel%22:%22estfundingrate%22}]) Estimated funding rate updates
* [ticker](https://api.tardis.dev/v1/data-feeds/woo-x?from=2026-07-01\&filters=\[{%22channel%22:%22ticker%22}]) 24h ticker updates
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for WOO X is located in GCP asia-northeast1 (Tokyo, Japan).
Real-time market data is captured via **multiple WebSocket connections** to `wss://wss.woox.io/v3/public`. Before **2026-06-29 22:00 UTC**, data was captured from WOO X Market Data API v2 at `wss://wss.woo.org/ws/stream`.
{% hint style="info" %}
WOO X servers are located in GCP asia-northeast1 (Tokyo, Japan).
{% endhint %}
# Upbit
Upbit historical market data details - currency pairs, data coverage and data collection specifics
Upbit exchange historical data for **all its currency pairs** is available since **2021-03-03**.
{% embed url="" %}
See Upbit 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | ------- | ---------- | ----------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | KRW-BTC | 2021-09-01 | [Download sample](https://datasets.tardis.dev/v1/upbit/incremental_book_L2/2021/09/01/KRW-BTC.csv.gz) |
| trades | KRW-BTC | 2021-09-01 | [Download sample](https://datasets.tardis.dev/v1/upbit/trades/2021/09/01/KRW-BTC.csv.gz) |
| quotes | KRW-BTC | 2021-09-01 | [Download sample](https://datasets.tardis.dev/v1/upbit/quotes/2021/09/01/KRW-BTC.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time Upbit WebSocket **Market Data API v1** () with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/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="upbit",
from_date="2024-01-01",
to_date="2024-01-02",
filters=[Channel(name="orderbook", symbols=["KRW-BTC"])],
api_key="YOUR_API_KEY",
):
# messages as provided by Upbit real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'upbit',
from: '2024-01-01',
to: '2024-01-02',
filters: [{ channel: 'orderbook', symbols: ['KRW-BTC'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Upbit real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/upbit?from=2024-01-01&filters=[{"channel":"orderbook","symbols":["KRW-BTC"]}]&offset=0'
```
{% embed url="" %}
Example API response for Upbit historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"upbit","filters":[{"channel":"orderbook","symbols":["KRW-BTC"]}],"from":"2024-01-01","to":"2024-01-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See Upbit WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [trade](https://api.tardis.dev/v1/data-feeds/upbit?from=2024-01-01\&filters=\[{%22channel%22:%22trade%22}]) Public trade executions stream
* [orderbook](https://api.tardis.dev/v1/data-feeds/upbit?from=2024-01-01\&filters=\[{%22channel%22:%22orderbook%22}]) Order book snapshots and unit updates
* [ticker](https://api.tardis.dev/v1/data-feeds/upbit?from=2024-01-01\&filters=\[{%22channel%22:%22ticker%22}]) 24h ticker updates
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for Upbit is located in GCP asia-northeast1 (Tokyo, Japan).
Real-time market data is captured via **multiple WebSocket connections** to .
{% hint style="info" %}
Upbit servers are located in AWS ap-northeast-2 region (Seoul, South Korea).
{% endhint %}
# Phemex
Phemex historical market data details - available instruments, data coverage and data collection specifics
Phemex historical data for **all its derivative instruments** is available since **2020-03-17** (for spot markets since 2020-06-04).
{% embed url="" %}
See Phemex 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | ------ | ---------- | ----------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTCUSD | 2020-04-01 | [Download sample](https://datasets.tardis.dev/v1/phemex/incremental_book_L2/2020/04/01/BTCUSD.csv.gz) |
| trades | BTCUSD | 2020-04-01 | [Download sample](https://datasets.tardis.dev/v1/phemex/trades/2020/04/01/BTCUSD.csv.gz) |
| derivative\_ticker | BTCUSD | 2020-04-01 | [Download sample](https://datasets.tardis.dev/v1/phemex/derivative_ticker/2020/04/01/BTCUSD.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time Phemex WebSocket API with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/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="phemex",
from_date="2024-01-01",
to_date="2024-01-02",
filters=[Channel(name="book", symbols=["BTCUSD"])],
api_key="YOUR_API_KEY",
):
# messages as provided by Phemex real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'phemex',
from: '2024-01-01',
to: '2024-01-02',
filters: [{ channel: 'book', symbols: ['BTCUSD'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Phemex real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/phemex?from=2024-01-01&filters=[{"channel":"book","symbols":["BTCUSD"]}]&offset=0'
```
{% embed url="" %}
Example API response for Phemex historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"phemex","filters":[{"channel":"book","symbols":["BTCUSD"]}],"from":"2024-01-01","to":"2024-01-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See Phemex WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [trades](https://api.tardis.dev/v1/data-feeds/phemex?from=2024-01-01\&filters=\[{%22channel%22:%22trades%22}]) Public trade executions stream
* [trades\_p](https://api.tardis.dev/v1/data-feeds/phemex?from=2024-01-01\&filters=\[{%22channel%22:%22trades_p%22}]) — available since **2022-11-23** Public perpetual trade executions stream
* [book](https://api.tardis.dev/v1/data-feeds/phemex?from=2024-01-01\&filters=\[{%22channel%22:%22book%22}]) Order book snapshots and incremental updates
* [orderbook\_p](https://api.tardis.dev/v1/data-feeds/phemex?from=2024-01-01\&filters=\[{%22channel%22:%22orderbook_p%22}]) — available since **2022-11-23** Perpetual order book snapshots and incremental updates
* [market24h](https://api.tardis.dev/v1/data-feeds/phemex?from=2024-01-01\&filters=\[{%22channel%22:%22market24h%22}]) 24h market statistics updates
* [perp\_market24h\_pack\_p](https://api.tardis.dev/v1/data-feeds/phemex?from=2024-01-01\&filters=\[{%22channel%22:%22perp_market24h_pack_p%22}]) — available since **2022-11-23** Perpetual 24h market statistics batch updates
* [spot\_market24h](https://api.tardis.dev/v1/data-feeds/phemex?from=2024-01-01\&filters=\[{%22channel%22:%22spot_market24h%22}]) — available since **2020-06-04** Spot 24h market statistics updates
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for Phemex **since 2020-06-04** is located in GCP asia-northeast1 (Tokyo, Japan), before that it was located in GCP europe-west2 region (London, UK).
Real-time market data is captured via **multiple WebSocket connections** to `wss://vapi.phemex.com/ws`.
{% hint style="info" %}
Phemex servers are located in AWS ap-southeast-1 region (Singapore, Asia Pacific).
{% endhint %}
# Delta Exchange
Delta Exchange historical market data details - available instruments, data coverage and data collection specifics
Delta Exchange historical data for **all its instruments** is available since **2020-03-30**.
{% embed url="" %}
See Delta Exchange 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | ------ | ---------- | ---------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTCUSD | 2020-06-01 | [Download sample](https://datasets.tardis.dev/v1/delta/incremental_book_L2/2020/06/01/BTCUSD.csv.gz) |
| trades | BTCUSD | 2020-06-01 | [Download sample](https://datasets.tardis.dev/v1/delta/trades/2020/06/01/BTCUSD.csv.gz) |
| derivative\_ticker | BTCUSD | 2020-06-01 | [Download sample](https://datasets.tardis.dev/v1/delta/derivative_ticker/2020/06/01/BTCUSD.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time Delta Exchange WebSocket API with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/api/quickstart) that 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="delta",
from_date="2023-01-01",
to_date="2023-01-02",
filters=[Channel(name="l2_orderbook", symbols=["BTCUSDT"])],
api_key="YOUR_API_KEY",
):
# messages as provided by Delta Exchange real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'delta',
from: '2023-01-01',
to: '2023-01-02',
filters: [{ channel: 'l2_orderbook', symbols: ['BTCUSDT'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Delta Exchange real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/delta?from=2023-01-01&filters=[{"channel":"l2_orderbook","symbols":["BTCUSDT"]}]&offset=0'
```
{% embed url="" %}
Example API response for Delta Exchange historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"delta","filters":[{"channel":"l2_orderbook","symbols":["BTCUSDT"]}],"from":"2023-01-01","to":"2023-01-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See Delta Exchange WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [recent\_trade](https://api.tardis.dev/v1/data-feeds/delta?from=2020-10-01\&filters=\[{%22channel%22:%22recent_trade%22}]) — available **until 2020-10-14** Legacy trade updates stream replaced by all\_trades. After that date trades are available via `all_trades` channel, this is due to change in Delta Exchange API which discontinued `recent_trade` channel support, see
* [all\_trades](https://api.tardis.dev/v1/data-feeds/delta?from=2024-01-01\&filters=\[{%22channel%22:%22all_trades%22}]) — available since **2020-10-14** Trade executions stream
* [l2\_orderbook](https://api.tardis.dev/v1/data-feeds/delta?from=2023-04-01\&filters=\[{%22channel%22:%22l2_orderbook%22}]) Order book snapshots and incremental updates stream
* [l2\_updates](https://api.tardis.dev/v1/data-feeds/delta?from=2024-01-01\&filters=\[{%22channel%22:%22l2_updates%22}]) — available since **2023-04-01** Incremental level 2 order book updates stream
* [l1\_orderbook](https://api.tardis.dev/v1/data-feeds/delta?from=2024-01-01\&filters=\[{%22channel%22:%22l1_orderbook%22}]) — available since **2023-04-01** Top of book snapshots stream
* [mark\_price](https://api.tardis.dev/v1/data-feeds/delta?from=2024-01-01\&filters=\[{%22channel%22:%22mark_price%22}]) Mark price updates stream
* [funding\_rate](https://api.tardis.dev/v1/data-feeds/delta?from=2024-01-01\&filters=\[{%22channel%22:%22funding_rate%22}]) Funding rate updates stream
* [spot\_price](https://api.tardis.dev/v1/data-feeds/delta?from=2024-01-01\&filters=\[{%22channel%22:%22spot_price%22}]) Spot index price updates stream
* [product\_updates](https://api.tardis.dev/v1/data-feeds/delta?from=2020-10-01\&filters=\[{%22channel%22:%22product_updates%22}]) — available **until 2020-10-14** Instrument definition and status updates stream
* [announcements](https://api.tardis.dev/v1/data-feeds/delta?from=2020-10-01\&filters=\[{%22channel%22:%22announcements%22}]) — available **until 2020-10-14** Exchange announcements stream
* [v2/ticker](https://api.tardis.dev/v1/data-feeds/delta?from=2024-01-01\&filters=\[{%22channel%22:%22v2/ticker%22}]) — available since **2020-10-14** Best bid/ask, last price and 24h market stats stream
* [spot\_30mtwap\_price](https://api.tardis.dev/v1/data-feeds/delta?from=2024-01-01\&filters=\[{%22channel%22:%22spot_30mtwap_price%22}]) — available since **2023-04-01** 30 minute TWAP spot price updates stream
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for Delta Exchange is located in GCP europe-west2 region (London, UK).
Real-time market data is captured via **multiple WebSocket connections** to `wss://socket.delta.exchange`.
{% hint style="info" %}
Delta Exchange servers are located in AWS ap-northeast-1 region (Tokyo, Japan).
{% endhint %}
# Blockchain.com
Blockchain.com Exchange historical market data details - instruments, data coverage and data collection specifics
Blockchain.com exchange historical data for **all its currency pairs** is available since **2023-02-23**.
{% embed url="" %}
See Blockchain.com exchange 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | ------- | ---------- | -------------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTC-USD | 2023-03-01 | [Download sample](https://datasets.tardis.dev/v1/blockchain-com/incremental_book_L2/2023/03/01/BTC-USD.csv.gz) |
| trades | BTC-USD | 2023-03-01 | [Download sample](https://datasets.tardis.dev/v1/blockchain-com/trades/2023/03/01/BTC-USD.csv.gz) |
| quotes | BTC-USD | 2023-03-01 | [Download sample](https://datasets.tardis.dev/v1/blockchain-com/quotes/2023/03/01/BTC-USD.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time Blockchain.com Exchange WebSocket **Market Data API v1** () with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/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="blockchain-com",
from_date="2023-03-01",
to_date="2023-03-02",
filters=[Channel(name="l2", symbols=["BTC-USD"])],
api_key="YOUR_API_KEY",
):
# messages as provided by Blockchain.com exchange real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'blockchain-com',
from: '2023-03-01',
to: '2023-03-02',
filters: [{ channel: 'l2', symbols: ['BTC-USD'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Blockchain.com exchange real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/blockchain-com?from=2023-03-01&filters=[{"channel":"l2","symbols":["BTC-USD"]}]&offset=0'
```
{% embed url="" %}
Example API response for Blockchain.com exchange historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"blockchain-com","filters":[{"channel":"l2","symbols":["BTC-USD"]}],"from":"2023-03-01","to":"2023-03-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See Blockchain.com exchange docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [trades](https://api.tardis.dev/v1/data-feeds/blockchain-com?from=2025-01-01\&filters=\[{%22channel%22:%22trades%22}]) Public trade executions stream
* [l2](https://api.tardis.dev/v1/data-feeds/blockchain-com?from=2024-01-01\&filters=\[{%22channel%22:%22l2%22}]) Level 2 order book snapshots and deltas
* [l3](https://api.tardis.dev/v1/data-feeds/blockchain-com?from=2024-01-01\&filters=\[{%22channel%22:%22l3%22}]) Level 3 order book updates stream
* [ticker](https://api.tardis.dev/v1/data-feeds/blockchain-com?from=2024-01-01\&filters=\[{%22channel%22:%22ticker%22}]) Ticker updates with best bid and ask plus 24h stats
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for Blockchain.com exchange is located in GCP europe-west2 region (London, UK).
Real-time market data is captured via **multiple WebSocket connections** to `wss://ws.blockchain.info/mercury-gateway/v1/ws`.
{% hint style="info" %}
Blockchain.com exchange public APIs are proxied through Cloudflare.
{% endhint %}
# Bitnomial
Bitnomial historical market data details - instruments, data coverage and data collection specifics
Bitnomial exchange historical data for **all its instruments** is available since **2023-01-13**.
{% embed url="" %}
See Bitnomial exchange 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | ------ | ---------- | -------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BUIH23 | 2023-03-01 | [Download sample](https://datasets.tardis.dev/v1/bitnomial/incremental_book_L2/2023/03/01/BUIH23.csv.gz) |
| trades | BUIH23 | 2023-02-01 | [Download sample](https://datasets.tardis.dev/v1/bitnomial/trades/2023/02/01/BUIH23.csv.gz) |
| quotes | BUIH23 | 2023-03-01 | [Download sample](https://datasets.tardis.dev/v1/bitnomial/quotes/2023/03/01/BUIH23.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time Bitnomial WebSocket **Market Data API** with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/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="bitnomial",
from_date="2023-05-01",
to_date="2023-05-02",
filters=[Channel(name="book", symbols=[])],
api_key="YOUR_API_KEY",
):
# messages as provided by Bitnomial exchange real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'bitnomial',
from: '2023-05-01',
to: '2023-05-02',
filters: [{ channel: 'book', symbols: [] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Bitnomial exchange real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/bitnomial?from=2023-05-01&filters=[{"channel":"book","symbols":[]}]&offset=1000'
```
{% embed url="" %}
Example API response for Bitnomial exchange historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"bitnomial","filters":[{"channel":"book","symbols":[]}],"from":"2023-05-01","to":"2023-05-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See Bitnomial WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [trade](https://api.tardis.dev/v1/data-feeds/bitnomial?from=2023-05-01\&filters=\[{%22channel%22:%22trade%22}]\&offset=1000) Trade executions stream
* [level](https://api.tardis.dev/v1/data-feeds/bitnomial?from=2023-05-01\&filters=\[{%22channel%22:%22level%22}]\&offset=1000) Price level order book updates stream
* [book](https://api.tardis.dev/v1/data-feeds/bitnomial?from=2023-05-01\&filters=\[{%22channel%22:%22book%22}]\&offset=1000) — available since **2023-04-07** Order book snapshots stream
* [block](https://api.tardis.dev/v1/data-feeds/bitnomial?from=2023-05-01\&filters=\[{%22channel%22:%22block%22}]\&offset=1000) Block trade updates stream
* [status](https://api.tardis.dev/v1/data-feeds/bitnomial?from=2023-05-01\&filters=\[{%22channel%22:%22status%22}]\&offset=1000) Market status and trading state updates stream
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for Bitnomial exchange is located in GCP europe-west2 region (London, UK).
Real-time market data is captured via **multiple WebSocket connections** to `wss://bitnomial.com/exchange/ws`.
{% hint style="info" %}
Bitnomial servers are located in AWS us-east-2 region (US East, Ohio, USA).
{% endhint %}
# bitFlyer
bitFlyer historical market data details - available instruments, data coverage and data collection specifics
bitFlyer historical data for **all its instruments** is available since **2019-08-30**.
{% embed url="" %}
See bitFlyer historical data coverage: available symbols, channels, date ranges and incidents
{% endembed %}
{% hint style="warning" %}
Real-time market data provided by bitFlyer exchange isn't always the most reliable and clean, especially during market volatility periods (crossed order books, delayed trade data).
{% endhint %}
### 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | ------------ | ---------- | ----------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | FX\_BTC\_JPY | 2020-01-01 | [Download sample](https://datasets.tardis.dev/v1/bitflyer/incremental_book_L2/2020/01/01/FX_BTC_JPY.csv.gz) |
| trades | FX\_BTC\_JPY | 2020-01-01 | [Download sample](https://datasets.tardis.dev/v1/bitflyer/trades/2020/01/01/FX_BTC_JPY.csv.gz) |
| quotes | FX\_BTC\_JPY | 2020-01-01 | [Download sample](https://datasets.tardis.dev/v1/bitflyer/quotes/2020/01/01/FX_BTC_JPY.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time bitFlyer **lightning** **JSON-RPC 2.0 over WebSocket** API with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/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="bitflyer",
from_date="2023-03-01",
to_date="2023-03-02",
filters=[Channel(name="lightning_board", symbols=["FX_BTC_JPY"])],
api_key="YOUR_API_KEY",
):
# messages as provided by bitFlyer real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'bitflyer',
from: '2023-03-01',
to: '2023-03-02',
filters: [{ channel: 'lightning_board', symbols: ['FX_BTC_JPY'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by bitFlyer real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/bitflyer?from=2023-03-01&filters=[{"channel":"lightning_board","symbols":["FX_BTC_JPY"]}]&offset=0'
```
{% embed url="" %}
Example API response for bitFlyer historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"bitflyer","filters":[{"channel":"lightning_board","symbols":["FX_BTC_JPY"]}],"from":"2023-03-01","to":"2023-03-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See bitFlyer WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [lightning\_executions](https://api.tardis.dev/v1/data-feeds/bitflyer?from=2024-01-01\&filters=\[{%22channel%22:%22lightning_executions%22}]) Trade executions stream
* [lightning\_board\_snapshot](https://api.tardis.dev/v1/data-feeds/bitflyer?from=2024-01-01\&filters=\[{%22channel%22:%22lightning_board_snapshot%22}]) — **generated** Generated initial order book snapshot stream used for order book bootstrap
* [lightning\_board](https://api.tardis.dev/v1/data-feeds/bitflyer?from=2024-01-01\&filters=\[{%22channel%22:%22lightning_board%22}]) Order book snapshots and updates stream
* [lightning\_ticker](https://api.tardis.dev/v1/data-feeds/bitflyer?from=2024-01-01\&filters=\[{%22channel%22:%22lightning_ticker%22}]) Best bid/ask, last price and 24h stats stream. Docs state delivery frequency is throttled but do not specify interval.
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for bitFlyer **since 2020-05-28** is located in GCP asia-northeast1 (Tokyo, Japan), before that it was located in GCP europe-west2 region (London, UK).
Real-time market data is captured via **single WebSocket connection** to `wss://ws.lightstream.bitflyer.com/json-rpc`.
{% hint style="info" %}
bitFlyer servers are located in AWS ap-northeast-1 region (Tokyo, Japan).
{% endhint %}
# HitBTC
HitBTC historical market data details - currency pairs, data coverage and data collection specifics
HitBTC historical data for **high caps currency pairs** is available since **2019-11-19**.
{% embed url="" %}
See HitBTC historical data coverage: available symbols, channels, date ranges and incidents
{% endembed %}
### Downloadable **CSV** files
Not available.
### API Access and data format
Historical data format is the same as provided by real-time HitBTC WebSocket **v2** API with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/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="hitbtc",
from_date="2024-01-01",
to_date="2024-01-02",
filters=[Channel(name="updateOrderbook", symbols=["BTCUSD"])],
api_key="YOUR_API_KEY",
):
# messages as provided by HitBTC real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'hitbtc',
from: '2024-01-01',
to: '2024-01-02',
filters: [{ channel: 'updateOrderbook', symbols: ['BTCUSD'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by HitBTC real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/hitbtc?from=2024-01-01&filters=[{"channel":"updateOrderbook","symbols":["BTCUSD"]}]&offset=0'
```
{% embed url="" %}
Example API response for HitBTC historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"hitbtc","filters":[{"channel":"updateOrderbook","symbols":["BTCUSD"]}],"from":"2024-01-01","to":"2024-01-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See HitBTC WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [updateTrades](https://api.tardis.dev/v1/data-feeds/hitbtc?from=2024-01-01\&filters=\[{%22channel%22:%22updateTrades%22}]) Incremental trade updates stream
* [snapshotOrderbook](https://api.tardis.dev/v1/data-feeds/hitbtc?from=2024-01-01\&filters=\[{%22channel%22:%22snapshotOrderbook%22}]) Full order book snapshot on subscription
* [updateOrderbook](https://api.tardis.dev/v1/data-feeds/hitbtc?from=2024-01-01\&filters=\[{%22channel%22:%22updateOrderbook%22}]) Order book incremental updates stream
* [snapshotTrades](https://api.tardis.dev/v1/data-feeds/hitbtc?from=2024-01-01\&filters=\[{%22channel%22:%22snapshotTrades%22}]) Initial trade snapshot on subscription
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for HitBTC is located in GCP europe-west2 region (London, UK).
Real-time market data is captured via **single WebSocket connection** to `wss://api.hitbtc.com/api/2/ws/public`.
{% hint style="info" %}
HitBTC servers are located in Equinix ld4 (Slough, Europe).
{% endhint %}
# Poloniex
Poloniex historical market data details - currency pairs, data coverage and data collection specifics
Poloniex exchange historical data for **all its currency pairs** is available since **2020-07-01.**
{% embed url="" %}
See Poloniex 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | --------- | ---------- | --------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | USDT\_BTC | 2020-07-01 | [Download sample](https://datasets.tardis.dev/v1/poloniex/incremental_book_L2/2020/07/01/USDT_BTC.csv.gz) |
| trades | USDT\_BTC | 2020-07-01 | [Download sample](https://datasets.tardis.dev/v1/poloniex/trades/2020/07/01/USDT_BTC.csv.gz) |
| quotes | USDT\_BTC | 2020-07-01 | [Download sample](https://datasets.tardis.dev/v1/poloniex/quotes/2020/07/01/USDT_BTC.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time Poloniex WebSocket **v2** API with addition of local timestamps and **also with addition of symbol at the end of each message** which allows us providing filtering for the data server-side. If you'd like to work with normalized data format instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/api/quickstart) that 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="poloniex",
from_date="2024-01-01",
to_date="2024-01-02",
filters=[Channel(name="book_lv2", symbols=["BTC_USDT"])],
api_key="YOUR_API_KEY",
):
# messages as provided by Poloniex real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'poloniex',
from: '2024-01-01',
to: '2024-01-02',
filters: [{ channel: 'book_lv2', symbols: ['BTC_USDT'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Poloniex real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/poloniex?from=2024-01-01&filters=[{"channel":"book_lv2","symbols":["BTC_USDT"]}]&offset=0'
```
{% embed url="" %}
Example API response for Poloniex historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"poloniex","filters":[{"channel":"book_lv2","symbols":["BTC_USDT"]}],"from":"2024-01-01","to":"2024-01-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See Poloniex WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [price\_aggregated\_book](https://api.tardis.dev/v1/data-feeds/poloniex?from=2020-07-01\&filters=\[{%22channel%22:%22price_aggregated_book%22}]) — available to **2022-08-02** Order book snapshots and deltas with embedded trades, sequence validated. During data collection integrity of order book incremental updates is being **validated** using [sequence numbers](https://docs.poloniex.com/#price-aggregated-book) provided by real-time feed - in case of detecting missed message WebSocket connection is being restarted.
* [trades](https://api.tardis.dev/v1/data-feeds/poloniex?from=2024-01-01\&filters=\[{%22channel%22:%22trades%22}]) — available since **2022-08-02** Public trade executions stream
* [book\_lv2](https://api.tardis.dev/v1/data-feeds/poloniex?from=2024-01-01\&filters=\[{%22channel%22:%22book_lv2%22}]) — available since **2022-08-02** Level 2 order book updates
* [ticker](https://api.tardis.dev/v1/data-feeds/poloniex?from=2024-01-01\&filters=\[{%22channel%22:%22ticker%22}]) — available since **2022-08-02** 24h ticker updates
{% hint style="info" %}
Each collected Poloniex real-time data message has appended symbol at the end of array - this allows us providing data filtering via API.
{% endhint %}
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for Poloniex is located in GCP europe-west2 region (London, UK).
Real-time market data is captured via **multiple WebSocket connections** to `wss://ws.poloniex.com/ws/public`.
{% hint style="info" %}
Poloniex servers are located in AWS eu-west-1 region (Dublin, Ireland). All its public APIs are proxied through Cloudflare.
{% endhint %}
# Hyperliquid
Hyperliquid historical market data details - currency pairs, data coverage and data collection specifics
Hyperliquid historical data is available since **2024-10-29**.
{% embed url="" %}
See Hyperliquid 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](/downloadable-csv-files/overview).
| data type | symbol | date | |
| --------------------- | ------ | ---------- | ------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTC | 2024-12-01 | [Download sample](https://datasets.tardis.dev/v1/hyperliquid/incremental_book_L2/2024/12/01/BTC.csv.gz) |
| trades | BTC | 2024-12-01 | [Download sample](https://datasets.tardis.dev/v1/hyperliquid/trades/2024/12/01/BTC.csv.gz) |
| derivative\_ticker | BTC | 2024-12-01 | [Download sample](https://datasets.tardis.dev/v1/hyperliquid/derivative_ticker/2024/12/01/BTC.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time Hyperliquid WebSocket API with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/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="hyperliquid",
from_date="2024-11-01",
to_date="2024-11-02",
filters=[Channel(name="l2Book", symbols=["BTC"])],
api_key="YOUR_API_KEY",
):
# messages as provided by Hyperliquid real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'hyperliquid',
from: '2024-11-01',
to: '2024-11-02',
filters: [{ channel: 'l2Book', symbols: ['BTC'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Hyperliquid real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/hyperliquid?from=2024-11-01&filters=[{"channel":"l2Book","symbols":["BTC"]}]&offset=0'
```
{% embed url="" %}
Example API response for Hyperliquid historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"hyperliquid","filters":[{"channel":"l2Book","symbols":["BTC"]}],"from":"2024-11-01","to":"2024-11-02"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See Hyperliquid WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [trades](https://api.tardis.dev/v1/data-feeds/hyperliquid?from=2025-01-01\&filters=\[{%22channel%22:%22trades%22,%22symbols%22:\[%22BTC%22]}]) Trade executions stream
* [l2Book](https://api.tardis.dev/v1/data-feeds/hyperliquid?from=2025-01-01\&filters=\[{%22channel%22:%22l2Book%22,%22symbols%22:\[%22BTC%22]}]) Regular 20-level order book snapshots stream, currently observed around every 5.4s.
* [fastBook](https://api.tardis.dev/v1/data-feeds/hyperliquid?from=2026-07-01\&filters=\[{%22channel%22:%22fastBook%22,%22symbols%22:\[%22BTC%22]}]) — available since **2026-06-17** Fast 5-level raw order book snapshots stream, currently observed around every 500ms. This is Hyperliquid `l2Book` with `fast: true`, exposed as raw channel `fastBook`.
Node.js client `tardis-dev` `18.1.0` or newer uses `fastBook` for real-time normalization and for historical data recorded from `2026-06-17` onward. The normalized `book_snapshot_5` and `book_snapshot_25` CSV datasets use the same cutoff; from that date, both are derived from the 5-level `fastBook` snapshots. Earlier historical data continues to use `l2Book`.
* [bbo](https://api.tardis.dev/v1/data-feeds/hyperliquid?from=2025-07-01\&filters=\[{%22channel%22:%22bbo%22,%22symbols%22:\[%22BTC%22]}]) — available since **2025-06-26** Best bid and offer updates stream. Sent only if the BBO changes on a block.
* [activeAssetCtx](https://api.tardis.dev/v1/data-feeds/hyperliquid?from=2025-01-01\&filters=\[{%22channel%22:%22activeAssetCtx%22}]) Perpetual asset context updates stream with funding, open interest and mark price
* [activeSpotAssetCtx](https://api.tardis.dev/v1/data-feeds/hyperliquid?from=2025-01-01\&filters=\[{%22channel%22:%22activeSpotAssetCtx%22}]) Spot asset context updates stream. Uses the same activeAssetCtx subscription type — returns WsActiveSpotAssetCtx for spot coins.
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for Hyperliquid is located in GCP asia-northeast1 (Tokyo, Japan).
Real-time market data is captured via **multiple WebSocket connections** to `wss://api.hyperliquid.xyz/ws`.
# Lighter
Lighter historical market data details - currency pairs, data coverage and data collection specifics
Lighter historical data is available since **2026-04-17**.
{% embed url="" %}
See Lighter 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](/downloadable-csv-files/overview).
{% hint style="info" %}
Lighter data collection started after the April 2026 monthly sample date. Public monthly sample links will be available from the next first-day dataset.
{% endhint %}
### API Access and data format
Historical data format is the same as provided by real-time Lighter WebSocket API with addition of local timestamps. Lighter symbols in Tardis.dev APIs are numeric market ids, for example `1` for a perpetual market and `2048` for a spot market. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/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="lighter",
from_date="2026-04-17",
to_date="2026-04-18",
filters=[Channel(name="order_book", symbols=["1"])],
api_key="YOUR_API_KEY",
):
# messages as provided by Lighter real-time stream
print(message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';
const messages = replay({
exchange: 'lighter',
from: '2026-04-17',
to: '2026-04-18',
filters: [{ channel: 'order_book', symbols: ['1'] }],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Lighter real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/lighter?from=2026-05-01&filters=[{"channel":"order_book","symbols":["1"]}]&offset=0'
```
{% embed url="" %}
Example API response for Lighter historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
curl -g 'localhost:8000/replay?options={"exchange":"lighter","filters":[{"channel":"order_book","symbols":["1"]}],"from":"2026-04-17","to":"2026-04-18"}'
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Captured real-time channels
{% embed url="" %}
See Lighter WebSocket API docs providing documentation for each captured channel's format
{% endembed %}
{% hint style="info" %}
Click any channel below to see [HTTP API](/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}
* [order\_book](https://api.tardis.dev/v1/data-feeds/lighter?from=2026-05-01\&filters=\[{%22channel%22:%22order_book%22,%22symbols%22:\[%221%22]}]) Order book snapshots and incremental updates stream
* [trade](https://api.tardis.dev/v1/data-feeds/lighter?from=2026-05-01\&filters=\[{%22channel%22:%22trade%22,%22symbols%22:\[%221%22]}]) Trade executions stream including liquidation trades
* [ticker](https://api.tardis.dev/v1/data-feeds/lighter?from=2026-05-01\&filters=\[{%22channel%22:%22ticker%22,%22symbols%22:\[%221%22]}]) Best bid and offer updates stream
* [market\_stats](https://api.tardis.dev/v1/data-feeds/lighter?from=2026-05-01\&filters=\[{%22channel%22:%22market_stats%22}]) Perpetual market stats updates stream with mark price, index price, funding rate and open interest. Subscribed as `market_stats/all`.
* [spot\_market\_stats](https://api.tardis.dev/v1/data-feeds/lighter?from=2026-05-01\&filters=\[{%22channel%22:%22spot_market_stats%22}]) Spot market stats updates stream with index price, mid price, last trade price and 24h stats. Subscribed as `spot_market_stats/all`.
### Market data collection details
[Market data collection infrastructure](/faq/general#what-is-your-infrastructure-setup) for Lighter is located in GCP asia-northeast1 (Tokyo, Japan).
Real-time market data is captured via **multiple WebSocket connections** to `wss://mainnet.zklighter.elliot.ai/stream`.
# Polymarket
Polymarket historical market data details - prediction market assets, data coverage and data collection specifics
Polymarket historical data is available since **2026-05-25**.
{% embed url="" %}
See Polymarket historical data coverage: channels, dataset date ranges and incidents. Find CLOB token IDs through the Polymarket API as described below.
{% 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](/downloadable-csv-files/overview).
Polymarket CSV exports use CLOB token IDs as per-symbol file names. The grouped daily trades file uses the `PREDICTIONS` symbol.
| data type | symbol | date | |
| --------------------- | ----------------------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| trades | PREDICTIONS | 2026-06-01 | [Download sample](https://datasets.tardis.dev/v1/polymarket/trades/2026/06/01/PREDICTIONS.csv.gz) |
| trades | 57661695455036831478287776153129850803351574978201924270494418960712051882696 | 2026-06-01 | [Download sample](https://datasets.tardis.dev/v1/polymarket/trades/2026/06/01/57661695455036831478287776153129850803351574978201924270494418960712051882696.csv.gz) |
| book\_ticker | 97903420938606091954598995247916642127489952123621529862160273048309855576367 | 2026-06-01 | [Download sample](https://datasets.tardis.dev/v1/polymarket/book_ticker/2026/06/01/97903420938606091954598995247916642127489952123621529862160273048309855576367.csv.gz) |
| incremental\_book\_L2 | 27240772368842340548393958038359200077022257197570320676979474039971830802302 | 2026-06-01 | [Download sample](https://datasets.tardis.dev/v1/polymarket/incremental_book_L2/2026/06/01/27240772368842340548393958038359200077022257197570320676979474039971830802302.csv.gz) |
| quotes | 27240772368842340548393958038359200077022257197570320676979474039971830802302 | 2026-06-01 | [Download sample](https://datasets.tardis.dev/v1/polymarket/quotes/2026/06/01/27240772368842340548393958038359200077022257197570320676979474039971830802302.csv.gz) |
| book\_snapshot\_5 | 27240772368842340548393958038359200077022257197570320676979474039971830802302 | 2026-06-01 | [Download sample](https://datasets.tardis.dev/v1/polymarket/book_snapshot_5/2026/06/01/27240772368842340548393958038359200077022257197570320676979474039971830802302.csv.gz) |
| book\_snapshot\_25 | 27240772368842340548393958038359200077022257197570320676979474039971830802302 | 2026-06-01 | [Download sample](https://datasets.tardis.dev/v1/polymarket/book_snapshot_25/2026/06/01/27240772368842340548393958038359200077022257197570320676979474039971830802302.csv.gz) |
### API Access and data format
Historical data format is the same as provided by real-time Polymarket WebSocket APIs with addition of local timestamps. Polymarket symbols in Tardis.dev APIs are CLOB token IDs, not event slugs or market questions. In Polymarket market channel messages this identifier appears as `asset_id`.
Symbol filters apply to per-token market data such as `book`, `price_change`, `last_trade_price`, and `best_bid_ask`. Market-level channels such as `tick_size_change`, `new_market`, `market_resolved`, and `sport_result` do not require symbols.
If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](/downloadable-csv-files/overview) or official [client libs](/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
symbols = [
"27240772368842340548393958038359200077022257197570320676979474039971830802302",
"33657678411548069412646838419011738363351964246263910293068444617014480555282",
]
async def main():
async for local_timestamp, message in replay(
exchange="polymarket",
from_date="2026-06-01",
to_date="2026-06-02",
filters=[
Channel(name="price_change", symbols=symbols),
Channel(name="book", symbols=symbols),
],
api_key="YOUR_API_KEY",
):
# messages as provided by Polymarket real-time stream
print(local_timestamp, message)
asyncio.run(main())
```
See [Python client docs](/python-client/quickstart).
{% endtab %}
{% tab title="Node.js" %}
```javascript
// npm install tardis-dev
// Save as replay.mjs
import { replay } from 'tardis-dev';
const symbols = [
'27240772368842340548393958038359200077022257197570320676979474039971830802302',
'33657678411548069412646838419011738363351964246263910293068444617014480555282'
];
const messages = replay({
exchange: 'polymarket',
from: '2026-06-01',
to: '2026-06-02',
filters: [
{ channel: 'price_change', symbols },
{ channel: 'book', symbols }
],
apiKey: 'YOUR_API_KEY'
});
// messages as provided by Polymarket real-time stream
for await (const { localTimestamp, message } of messages) {
console.log(localTimestamp, message);
}
```
See [Node.js client docs](/node-client/quickstart).
{% endtab %}
{% tab title="cURL & HTTP API" %}
```bash
filters='[
{"channel":"price_change","symbols":[
"27240772368842340548393958038359200077022257197570320676979474039971830802302",
"33657678411548069412646838419011738363351964246263910293068444617014480555282"
]},
{"channel":"book","symbols":[
"27240772368842340548393958038359200077022257197570320676979474039971830802302",
"33657678411548069412646838419011738363351964246263910293068444617014480555282"
]}
]'
curl --compressed --get 'https://api.tardis.dev/v1/data-feeds/polymarket' \
--data-urlencode 'from=2026-06-01' \
--data-urlencode "filters=${filters}" \
--data-urlencode 'offset=0'
```
{% embed url="" %}
Example API response for Polymarket historical market data request
{% endembed %}
See [HTTP API docs](/api/http-api-reference).
{% endtab %}
{% tab title="cURL & tardis-machine" %}
```bash
replay_options='{
"exchange":"polymarket",
"filters":[
{"channel":"price_change","symbols":[
"27240772368842340548393958038359200077022257197570320676979474039971830802302",
"33657678411548069412646838419011738363351964246263910293068444617014480555282"
]},
{"channel":"book","symbols":[
"27240772368842340548393958038359200077022257197570320676979474039971830802302",
"33657678411548069412646838419011738363351964246263910293068444617014480555282"
]}
],
"from":"2026-06-01",
"to":"2026-06-02"
}'
curl --get 'http://localhost:8000/replay' \
--data-urlencode "options=${replay_options}"
```
[Tardis-machine](/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](/api/http-api-reference) that provides data only in minute by minute slices.
See [tardis-machine](/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}
### Download data for a Polymarket event
Tardis.dev does not mirror Polymarket's full instrument catalog. The `availableSymbols` field in `/v1/exchanges/polymarket` is empty, and `/v1/instruments/polymarket` does not enumerate CLOB token IDs. Use Polymarket's public [Gamma API](https://docs.polymarket.com/api-reference/introduction) as the source of truth for events, markets, outcomes and token IDs. It does not require an API key.
Polymarket [groups one or more markets under an event](https://docs.polymarket.com/concepts/markets-events). Each market outcome has its own CLOB token ID, which Tardis.dev uses as the symbol. For a known event, start with its Polymarket URL and use the value after `/event/` as the event slug. The examples below:
1. fetch the event from Gamma,
2. select a market by its question and an outcome by its label,
3. map the outcome to its CLOB token ID, and
4. download the corresponding Tardis.dev CSV dataset.
They use [this historical event](https://polymarket.com/event/what-price-will-ethereum-hit-may-25-31-2026), market `Will Ethereum dip to $1,800 May 25-31?` and outcome `No`. Change those values, `data_type` and `date` for your use case.
{% tabs %}
{% tab title="Python" %}
```python
# pip install requests
import json
import os
from pathlib import Path
import requests
event_slug = "what-price-will-ethereum-hit-may-25-31-2026"
market_question = "Will Ethereum dip to $1,800 May 25-31?"
outcome = "No"
data_type = "trades"
date = "2026-06-01"
response = requests.get(
f"https://gamma-api.polymarket.com/events/slug/{event_slug}",
timeout=30,
)
response.raise_for_status()
event = response.json()
market = next(
(item for item in event["markets"] if item["question"] == market_question),
None,
)
if market is None:
raise ValueError("Market not found. Check market_question against the event page.")
outcomes = json.loads(market["outcomes"])
token_ids = json.loads(market["clobTokenIds"])
if outcome not in outcomes:
raise ValueError(f"Outcome must be one of: {', '.join(outcomes)}")
token_id = token_ids[outcomes.index(outcome)]
date_path = date.replace("-", "/")
url = f"https://datasets.tardis.dev/v1/polymarket/{data_type}/{date_path}/{token_id}.csv.gz"
output = Path(f"polymarket_{data_type}_{date}_{token_id}.csv.gz")
headers = {}
if api_key := os.getenv("TARDIS_API_KEY"):
headers["Authorization"] = f"Bearer {api_key}"
with requests.get(url, headers=headers, stream=True, timeout=(10, 300)) as response:
response.raise_for_status()
with output.open("wb") as file:
for chunk in response.iter_content(chunk_size=1024 * 1024):
file.write(chunk)
print(token_id)
print(output)
```
{% endtab %}
{% tab title="Node.js" %}
```javascript
// Save as polymarket-download.mjs
import { createWriteStream } from 'node:fs';
import { Readable } from 'node:stream';
import { pipeline } from 'node:stream/promises';
const eventSlug = 'what-price-will-ethereum-hit-may-25-31-2026';
const marketQuestion = 'Will Ethereum dip to $1,800 May 25-31?';
const outcome = 'No';
const dataType = 'trades';
const date = '2026-06-01';
const eventResponse = await fetch(
`https://gamma-api.polymarket.com/events/slug/${encodeURIComponent(eventSlug)}`
);
if (!eventResponse.ok) throw new Error(`Gamma API returned ${eventResponse.status}`);
const event = await eventResponse.json();
const market = event.markets.find((item) => item.question === marketQuestion);
if (!market) throw new Error('Market not found. Check marketQuestion against the event page.');
const outcomes = JSON.parse(market.outcomes);
const tokenIds = JSON.parse(market.clobTokenIds);
const outcomeIndex = outcomes.indexOf(outcome);
if (outcomeIndex === -1) throw new Error(`Outcome must be one of: ${outcomes.join(', ')}`);
const tokenId = tokenIds[outcomeIndex];
const datePath = date.replaceAll('-', '/');
const url = `https://datasets.tardis.dev/v1/polymarket/${dataType}/${datePath}/${tokenId}.csv.gz`;
const output = `polymarket_${dataType}_${date}_${tokenId}.csv.gz`;
const headers = process.env.TARDIS_API_KEY
? { Authorization: `Bearer ${process.env.TARDIS_API_KEY}` }
: {};
const datasetResponse = await fetch(url, { headers });
if (!datasetResponse.ok) throw new Error(`Datasets API returned ${datasetResponse.status}`);
await pipeline(Readable.fromWeb(datasetResponse.body), createWriteStream(output));
console.log(tokenId);
console.log(output);
```
{% endtab %}
{% tab title="cURL and jq" %}
```bash
#!/usr/bin/env bash
set -euo pipefail
event_slug='what-price-will-ethereum-hit-may-25-31-2026'
market_question='Will Ethereum dip to $1,800 May 25-31?'
outcome='No'
data_type='trades'
date='2026-06-01'
token_id="$(
curl --silent --show-error --fail \
"https://gamma-api.polymarket.com/events/slug/${event_slug}" |
jq --exit-status --raw-output \
--arg question "${market_question}" \
--arg outcome "${outcome}" '
(.markets[] | select(.question == $question)) as $market
| ($market.outcomes | fromjson) as $outcomes
| ($market.clobTokenIds | fromjson) as $tokens
| ($outcomes | index($outcome)) as $index
| if $index == null then error("outcome not found") else $tokens[$index] end
'
)"
date_path="${date:0:4}/${date:5:2}/${date:8:2}"
output="polymarket_${data_type}_${date}_${token_id}.csv.gz"
curl_args=(--fail --location --output "${output}")
if [[ -n "${TARDIS_API_KEY:-}" ]]; then
curl_args+=(--header "Authorization: Bearer ${TARDIS_API_KEY}")
fi
curl "${curl_args[@]}" \
"https://datasets.tardis.dev/v1/polymarket/${data_type}/${date_path}/${token_id}.csv.gz"
printf '%s\n%s\n' "${token_id}" "${output}"
```
{% endtab %}
{% endtabs %}
The example date is the first UTC day of a month, so it works without an API key. Set `TARDIS_API_KEY` for other dates. A `404` means no file was exported for that token, data type and date, or that the requested date has not been exported yet. Use a data type from the CSV table above and a date between the market's `startDate` and `endDate`.
Gamma returns `outcomes` and `clobTokenIds` as JSON-encoded arrays. Values at the same index belong together; the examples preserve this mapping rather than treating an event or market slug as a tradable symbol.
#### Discover events without a URL
For a specific event, Polymarket recommends fetching the event by the slug from its URL. For broader discovery, [fetch events with pagination or tag filters](https://docs.polymarket.com/market-data/fetching-markets); each event includes its markets:
```bash
curl --silent --show-error --fail --get \
'https://gamma-api.polymarket.com/events' \
--data-urlencode 'tag_slug=crypto' \
--data-urlencode 'active=true' \
--data-urlencode 'closed=false' \
--data-urlencode 'order=volume24hr' \
--data-urlencode 'ascending=false' \
--data-urlencode 'limit=20' \
--data-urlencode 'offset=0' |
jq -r '.[] | [.title, .slug] | @tsv'
```
Increase `offset` by `limit` until Gamma returns an empty array. Gamma also provides a `/markets` endpoint for market-level pagination. Starting from `/events` is usually simpler when the user-facing event may contain multiple related markets.
#### Discover traded tokens from grouped trades
The grouped `PREDICTIONS` trades file is an alternative when you need every token that traded on a specific UTC date and do not need event, question or outcome metadata. Its `symbol` column contains CLOB token IDs.
Download `https://datasets.tardis.dev/v1/polymarket/trades/YYYY/MM/DD/PREDICTIONS.csv.gz` as `polymarket_trades_YYYY-MM-DD_PREDICTIONS.csv.gz`, then run this example to create a list of per-token order book dataset URLs:
```python
import csv
import gzip
from pathlib import Path
date = "2026-06-01"
data_type = "incremental_book_L2"
trades_file = Path(f"polymarket_trades_{date}_PREDICTIONS.csv.gz")
with gzip.open(trades_file, mode="rt", newline="") as file:
token_ids = sorted({row["symbol"] for row in csv.DictReader(file)})
date_path = date.replace("-", "/")
urls = [
f"https://datasets.tardis.dev/v1/polymarket/{data_type}/{date_path}/{token_id}.csv.gz"
for token_id in token_ids
]
Path(f"polymarket_{data_type}_{date}_urls.txt").write_text("\n".join(urls) + "\n")
print(f"Found {len(token_ids)} traded tokens")
```
This method finds only tokens with at least one trade in that file; it misses non-trading markets and does not map tokens back to events or outcomes. A generated URL can still return `404` when no file of that data type was exported. `PREDICTIONS` is not a CLOB token ID and cannot be used for order book datasets or raw replay symbol filters.
#### Replay raw data for a token
Use the same CLOB token ID as the symbol in Tardis.dev replay filters. For example:
```json
[
{
"channel": "book",
"symbols": [
"57661695455036831478287776153129850803351574978201924270494418960712051882696"
]
}
]
```
The Python, Node.js, HTTP API and tardis-machine examples above show how to pass these filters for a historical date range.
### Captured real-time channels
{% embed url="