Tardis Machine Server
Locally runnable server with built-in data caching, providing both tick-level historical and consolidated real-time cryptocurrency market data via HTTP and WebSocket APIs
Introduction
Tardis-machine is a locally runnable server with built-in data caching that uses Tardis.dev HTTP API under the hood. It provides both tick-level historical and consolidated real-time cryptocurrency market data via it's HTTP and WebSocket APIs and is available via npm and Docker.

Features
efficient data replay API endpoints returning historical market data for whole time periods (in contrast to Tardis.dev HTTP API where single call returns data for single minute time period)
exchange-native market data APIs
tick-by-tick historical market data replay in exchange-native format
WebSocket API 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
consistent format for accessing market data across multiple exchanges
consolidated real-time data streaming connecting directly to exchanges' WebSocket APIs
customizable order book snapshots and trade bars data types
transparent historical local data caching (cached data is stored on disk in compressed GZIP format and decompressed on demand when reading the data)
support for top cryptocurrency exchanges: BitMEX, Deribit, Binance, Binance Futures, FTX, OKEx, Huobi Global, Huobi DM, bitFlyer, Bitstamp, Coinbase Pro, Kraken Futures, Gemini, Kraken, Bitfinex, Bybit, OKCoin, CoinFLEX and more
Installation
Docker
Pull and run latest version of tardisdev/tardis-machine
image:
### running without persitent local cache
docker run -p 8000:8000 -p 8001:8001 -e "TM_API_KEY=YOUR_API_KEY" -d tardisdev/tardis-machine
Tardis-machine server's HTTP endpoints will be available on port 8000
and WebSocket API endpoints on port 8001
. Your API key will be passed via ENV variable (TM_API_KEY
) — simply replace YOUR_API_KEY
with API key you've received via email.
Command above does not use persistent volumes for local caching (each docker restart will result in loosing local data cache). In order to use for example./host-cache-dir
as persistent volume (bind mount) cache directory, run:
docker run -v ./host-cache-dir:/.cache -p 8000:8000 -p 8001:8001 -e "TM_API_KEY=YOUR_API_KEY" -d tardisdev/tardis-machine
Since using volumes can cause issues especially on Windows, it's fine to run Docker image without them with the caveat of potentially poor local cache ratio after each container's restart.
Config environment variables
You can set following environment config variables to configure tardis-machine server:
name
default
description
TM_API_KEY
API key for 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
)
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 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
npm
Install and runtardis-machine
server via npx
command:
npx tardis-machine --api-key=YOUR_API_KEY
or install globally via npm
:
npm install -g tardis-machine
and then run:
tardis-machine --api-key=YOUR_API_KEY
Tardis-machine server's HTTP endpoints will be available on port 8000
and WebSocket API endpoints on port 8001
. Your API key will be passed via --api-key
config flag — simply replace YOUR_API_KEY
with API key you've received via email.
CLI config flags
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 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
<os.tmpdir>/.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 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
Exchange-native market data APIs
Exchange-native market data API endpoints provide historical data in exchange-native format. The main difference between HTTP and WebSocket endpoints is the logic of requesting data:
HTTP API accepts request options payload via query string param
WebSocket API accepts exchanges' specific 'subscribe' messages that define what data will be then "replayed" and send to WebSocket client
• HTTP GET
/replay?options={options}
HTTP GET
/replay?options={options}Returns historical market data messages in exchange-native format for given replay options query string param. Single streaming HTTP response returns data for the whole requested time period as NDJSON.
import asyncio
import aiohttp
import json
import urllib.parse
async def replay_via_tardis_machine_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 run():
lines = replay_via_tardis_machine_machine(
{
"exchange": "bitmex",
"from": "2019-10-01",
"to": "2019-10-02",
"filters": [
{"channel": "trade", "symbols": ["XBTUSD", "ETHUSD"]},
{"channel": "orderBookL2", "symbols": ["XBTUSD", "ETHUSD"]},
],
}
)
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(run())
Replay options
HTTP /replay endpoint accepts required options query string param in url encoded JSON format.
name
type
default
filters
{channel:string, symbols?: string[]}[]
[]
optional filters of requested historical data feed - check historical data details for each exchange and /exchanges/:exchange HTTP API to get allowed channels and symbols for requested exchange
withDisconnects
boolean | undefined
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
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 plus local timestamp:
localTimestamp
- date when message has been received in ISO 8601 formatmessage
- JSON with exactly the same format as provided by requested exchange real-time feeds
Sample response
{"localTimestamp":"2019-05-01T00:09:42.2760012Z","message":{"table":"orderBookL2","action":"update","data":[{"symbol":"XBTUSD","id":8799473750,"side":"Buy","size":2333935}]}}
{"localTimestamp":"2019-05-01T00:09:42.2932826Z","message":{"table":"orderBookL2","action":"update","data":[{"symbol":"XBTUSD","id":8799474250,"side":"Buy","size":227485}]}}
{"localTimestamp":"2019-05-01T00:09:42.4249304Z","message":{"table":"trade","action":"insert","data":[{"timestamp":"2019-05-01T00:09:42.407Z","symbol":"XBTUSD","side":"Buy","size":1500,"price":5263,"tickDirection":"ZeroPlusTick","trdMatchID":"29d7de7f-27b6-9574-48d1-3ee9874831cc","grossValue":28501500,"homeNotional":0.285015,"foreignNotional":1500}]}}
{"localTimestamp":"2019-05-01T00:09:42.4249403Z","message":{"table":"orderBookL2","action":"update","data":[{"symbol":"XBTUSD","id":8799473700,"side":"Sell","size":454261}]}}
{"localTimestamp":"2019-05-01T00:09:42.4583155Z","message":{"table":"orderBookL2","action":"update","data":[{"symbol":"XBTUSD","id":8799473750,"side":"Buy","size":2333838},{"symbol":"XBTUSD","id":8799473800,"side":"Buy","size":547746}]}}
• WebSocket
/ws-replay?exchange={exchange}&from={fromDate}&to={toDate}
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 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 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, then data being send to those clients will be synchronized (by local timestamp).
import asyncio
import aiohttp
import json
async def run():
WS_REPLAY_URL = "ws://localhost:8001/ws-replay"
URL = f"{WS_REPLAY_URL}?exchange=bitmex&from=2019-10-01&to=2019-10-02"
async with aiohttp.ClientSession() as session:
async with session.ws_connect(URL) as websocket:
await websocket.send_str(
json.dumps(
{
"op": "subscribe",
"args": [
"trade:XBTUSD",
"trade:ETHUSD",
"orderBookL2:XBTUSD",
"orderBookL2:ETHUSD",
],
}
)
)
async for msg in websocket:
print(msg.data)
asyncio.run(run())
Query string params
name
type
default
description
session
string | undefined
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 across all supported exchanges. Both HTTP /replay-normalized and WebSocket /ws-replay-normalized APIs accept the same replay options payload via query string param. It's mostly matter of preference when choosing which protocol to use, but WebSocket /ws-replay-normalized API has also it's real-time counterpart /ws-stream-normalized, 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}
HTTP GET
/replay-normalized?options={options}Returns historical market data for data types specified via query string. Single streaming HTTP response returns data for the whole requested time period as NDJSON. See supported data types which include normalized trade, order book change, customizable order book snapshots etc.
import asyncio
import aiohttp
import json
import urllib.parse
async def replay_normalized_via_tardis_machine_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 run():
lines = replay_normalized_via_tardis_machine_machine(
{
"exchange": "bitmex",
"from": "2019-10-01",
"to": "2019-10-02",
"symbols": ["XBTUSD", "ETHUSD"],
"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(run())
Replay normalized options
HTTP /replay-normalized 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).
name
type
default
symbols
string[] | undefined
undefined
optional symbols of requested historical data feed - use /exchanges/:exchange HTTP API to get allowed symbols for requested exchange
withDisconnectMessages
boolean | undefined
undefined
when set to true
, response includes disconnect messages that mark events when real-time WebSocket connection that was used to collect the historical data got disconnected
Response format & sample messages
• WebSocket
/ws-replay-normalized?options={options}
WebSocket
/ws-replay-normalized?options={options}Sends normalized historical market data for data types specified via query string. See supported data types which include normalized trade, order book change, customizable order book snapshots etc.
import asyncio
import aiohttp
import json
import urllib.parse
async def run():
replay_options = {
"exchange": "bitmex",
"from": "2019-10-01",
"to": "2019-10-02",
"symbols": ["XBTUSD", "ETHUSD"],
"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(run())
Replay normalized options
WebSocket /ws-replay-normalized 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 being send synchronized (by local timestamp).
name
type
default
symbols
string[] | undefined
undefined
optional symbols of requested historical data feed - use /exchanges/:exchange HTTP API to get allowed symbols for requested exchange
withDisconnectMessages
boolean | undefined
undefined
when set to true
, sends also disconnect messages that mark events when real-time WebSocket connection that was used to collect the historical data got disconnected
Response format & sample messages
• WebSocket
/ws-stream-normalized?options={options}
WebSocket
/ws-stream-normalized?options={options}Sends normalized real-time market data for data types specified via query string. See supported data types which include normalized trade, order book change, customizable order book snapshots etc.
Doesn't requires API key as connects directly to exchanges real-time WebSocket APIs and transparently restarts closed, broken or stale connections (open connections without data being send for specified amount of time).
Provides consolidated real-time market data streaming functionality with options as an array - provides single consolidated real-time data stream for all exchanges specified in options array.
import asyncio
import aiohttp
import json
import urllib.parse
async def run():
data_types = ["trade", "book_change", "book_snapshot_10_100ms"]
stream_options = [
{
"exchange": "bitmex",
"symbols": ["XBTUSD"],
"dataTypes": data_types,
},
{
"exchange": "deribit",
"symbols": ["BTC-PERPETUAL"],
"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(run())
Stream normalized options
WebSocket /ws-stream-normalized 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
symbols
string[] | undefined
undefined
optional symbols of requested real-time data feed
withDisconnectMessages
boolean | undefined
undefined
when set to true
, sends 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
Response format & sample messages
Normalized data types
• trade
Individual trade
{
"type": "trade",
"symbol": "XBTUSD",
"exchange": "bitmex",
"id": "282a0445-0e3a-abeb-f403-11003204ea1b",
"price": 7996,
"amount": 50,
"side": "sell",
"timestamp": "2019-10-23T10:32:49.669Z",
"localTimestamp": "2019-10-23T10:32:49.740Z"
}
• book_change
Initial L2 (market by price) 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.
{
"type": "book_change",
"symbol": "XBTUSD",
"exchange": "bitmex",
"isSnapshot": false,
"bids": [],
"asks": [
{
"price": 7985,
"amount": 283318
}
],
"timestamp": "2019-10-23T11:29:53.469Z",
"localTimestamp": "2019-10-23T11:29:53.469Z"
}
• derivative_ticker
Derivative instrument ticker info sourced from real-time ticker & instrument channels.
{
"type": "derivative_ticker",
"symbol": "BTC-PERPETUAL",
"exchange": "deribit",
"lastPrice": 7987.5,
"openInterest": 84129491,
"fundingRate": -0.00001568,
"indexPrice": 7989.28,
"markPrice": 7987.56,
"timestamp": "2019-10-23T11:34:29.302Z",
"localTimestamp": "2019-10-23T11:34:29.416Z"
}
• 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
.
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).
Examples:
book_snapshot_10_0ms
- provides top 10 levels tick-by-tick order book snapshotsbook_snapshot_50_100ms
- provides top 50 levels order book snapshots taken at 100 millisecond intervalsbook_snapshot_30_10s
- provides top 30 levels order book snapshots taken at 10 second intervalsquote
is an alias ofbook_snapshot_1_0ms
- provides top of the book (best bid/ask) tick-by-order book snapshotsquote_10s
is an alias ofbook_snapshot_1_10s
- provides top of the book (best bid/ask) order book snapshots taken at 10 seconds intervals
Available time units:
ms
- millisecondss
- secondsm
- minutes
{
"type": "book_snapshot",
"symbol": "XBTUSD",
"exchange": "bitmex",
"name": "book_snapshot_2_50ms",
"depth": 2,
"interval": 50,
"bids": [
{
"price": 7633.5,
"amount": 1906067
},
{
"price": 7633,
"amount": 65319
}
],
"asks": [
{
"price": 7634,
"amount": 1467849
},
{
"price": 7634.5,
"amount": 67939
}
],
"timestamp": "2019-10-25T13:39:46.950Z",
"localTimestamp": "2019-10-25T13:39:46.961Z"
}
• 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.
Examples:
trade_bar_10ms
- provides time based trade bars with 10 milliseconds intervalstrade_bar_5m
- provides time based trade bars with 5 minute intervalstrade_bar_100ticks
- provides ticks based trade bars with 100 ticks (individual trades) intervalstrade_bar_100000vol
- provides volume based trade bars with 100 000 volume intervals
Allowed suffixes:
ms
- millisecondss
- secondsm
- minutesticks
- number of ticksvol
- volume size
{
"type": "trade_bar",
"symbol": "XBTUSD",
"exchange": "bitmex",
"name": "trade_bar_10000ms",
"interval": 10000,
"kind": "time",
"open": 7623.5,
"high": 7623.5,
"low": 7623,
"close": 7623.5,
"volume": 37034,
"buyVolume": 24244,
"sellVolume": 12790,
"trades": 9,
"vwap": 7623.327320840309,
"openTimestamp": "2019-10-25T13:11:31.574Z",
"closeTimestamp": "2019-10-25T13:11:39.212Z",
"localTimestamp": "2019-10-25T13:11:40.369Z",
"timestamp": "2019-10-25T13:11:40.000Z"
}
• disconnect
Message that marks events when real-time WebSocket connection that was used to collect the historical data got disconnected.
{
"type": "disconnect",
"exchange": "deribit",
"localTimestamp": "2019-10-23T11:34:29.416Z"
}
Last updated