# Data Types

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)](https://docs.tardis.dev/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)](https://docs.tardis.dev/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](https://docs.tardis.dev/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](https://docs.tardis.dev/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 %}