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

Individual trade

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

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

{
  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

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

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

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.

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

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

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_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

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

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

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.

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

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

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.

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

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

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 NextQuickstart

Last updated 2 months ago

Was this helpful?