Streaming Real-Time Data

This page documents the real-time normalized streaming API exposed by Tardis Machine. Historical replay APIs are documented on Replaying Historical Data, and normalized message schemas are documented on Output Data Types.

• 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 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 as an array - provides single consolidated real-time data stream for all exchanges specified in options array.

WebSocket /ws-replay-normalized is the historical counterpart of this API endpoint, providing historical market data in the same format.

Tardis-machine provides real-time streaming only for normalized data types. If you need real-time data in exchange-native format, connect directly to the exchange's WebSocket API.

Python

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())

Node.js

Your preferred language

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	description
exchange	string	-	requested exchange id - use /exchanges HTTP API 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 for which real-time data will be provided
withDisconnectMessages	boolean (optional)	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
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}

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.

Response format & sample messages

See Output Data Types.