Output Data Types

This page documents the normalized messages returned by Tardis Machine replay and streaming APIs. Historical replay APIs are documented on Replaying Historical Data, and real-time streaming is documented on Streaming Real-Time Data.

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"
}

{
  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)
}

• 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"
}

{
  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)
}

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

Best bid/ask (BBO) sourced from exchange-native ticker or quote feeds (e.g., Binance bookTicker, Bybit orderbook.1). Unlike quote which derives BBO from L2 order book data, book_ticker uses the exchange's dedicated BBO stream when available.

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

{
  "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"
}

{
  type: 'book_ticker'
  symbol: string // instrument symbol as provided by exchange
  exchange: string // exchange id
  askPrice: number | undefined // best ask price
  askAmount: number | undefined // best ask amount
  bidPrice: number | undefined // best bid price
  bidAmount: number | undefined // best bid amount
  timestamp: string // message timestamp provided by exchange (ISO 8601 format)
  localTimestamp: string // message arrival timestamp (ISO 8601 format)
}

• 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"
}

{
  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 // last funding rate 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 // predicted next funding rate if provided by exchange
  timestamp: string // message timestamp provided by exchange (ISO 8601 format)
  localTimestamp: string // message arrival timestamp (ISO 8601 format)
}

• 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 snapshots
book_snapshot_50_100ms - provides top 50 levels order book snapshots taken at 100 millisecond intervals
book_snapshot_30_10s - provides top 30 levels order book snapshots taken at 10 second intervals
quote is an alias of book_snapshot_1_0ms - provides top of the book (best bid/ask) tick-by-order book snapshots
quote_10s is an alias of book_snapshot_1_10s - provides top of the book (best bid/ask) order book snapshots taken at 10 seconds intervals

Available time units:

ms - milliseconds
s - seconds
m - 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"
}

{
  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; amount: number }[] // top "depth" bids price-amount levels
  asks: { price: number; amount: number }[] // top "depth" asks price-amount levels
  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)
}

• liquidation

Liquidation events sourced from exchange-native liquidation feeds. Available for exchanges that publish liquidation data (e.g., Binance forceOrder, BitMEX liquidation, OKX liquidation-orders). See which exchanges support liquidations.

{
  "type": "liquidation",
  "symbol": "XBTUSD",
  "exchange": "bitmex",
  "id": "0e3a5a47-e3d1-4f5c-a5a3-7e3b1f3a6c9e",
  "price": 42150.5,
  "amount": 10000,
  "side": "sell",
  "timestamp": "2024-01-15T10:30:00.123Z",
  "localTimestamp": "2024-01-15T10:30:00.234Z"
}

{
  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
  timestamp: string // message timestamp provided by exchange (ISO 8601 format); some exchanges (e.g., BitMEX) do not provide a separate liquidation timestamp, in which case this equals localTimestamp
  localTimestamp: string // message arrival timestamp (ISO 8601 format)
}

• option_summary

Options instrument summary sourced from exchange-native options feeds. Available for exchanges that provide options data (e.g., Deribit, OKX Options, Binance Options). Includes greeks, implied volatility, and best bid/ask for options instruments.

{
  "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"
}

{
  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)
}

• 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

{
  "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"
}

{
  type: 'trade_bar'
  symbol: string // instrument symbol as provided by exchange
  exchange: string // exchange id
  name: string // name with format trade_bar_{interval}
  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)
}

• 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"
}

• error

Message sent when an underlying exchange WebSocket connection error occurs. Only available for /ws-stream-normalized when withErrorMessages is set to true. The subSequentErrorsCount tracks consecutive errors without successful data — if it reaches 50, the connection is closed.

{
  "type": "error",
  "exchange": "binance-futures",
  "localTimestamp": "2024-01-15T10:30:00.123Z",
  "details": "WebSocket connection error: Connection reset by peer",
  "subSequentErrorsCount": 1
}

{
  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
}

PreviousStreaming Real-Time Data NextPrivacy Policy

Last updated 1 hour ago

hashtagNormalized data types

hashtag• trade

hashtag• book_change

hashtag• book_ticker

hashtag• derivative_ticker

hashtag• book_snapshot_{number_of_levels}_{snapshot_interval}{time_unit}

hashtagExamples:

hashtagAvailable time units:

hashtag• liquidation

hashtag• option_summary

hashtag• trade_bar_{aggregation_interval}{suffix}

hashtagExamples:

hashtag• disconnect

hashtag• error

Normalized data types

• trade

• book_change

• book_ticker

• derivative_ticker

• book_snapshot_{number_of_levels}_{snapshot_interval}{time_unit}

Examples:

Available time units:

• liquidation

• option_summary

• trade_bar_{aggregation_interval}{suffix}

Examples:

• disconnect

• error