Streaming Real-Time Data

This page contains the detailed real-time streaming reference for the Node.js tardis-dev client. For a shorter onboarding flow with simple examples, see Getting Started.

stream(options)

Streams real-time market data messages for given stream options in exchange-native format. It connects directly to exchanges WebSocket APIs and transparently restarts closed, broken or stale connections (open connections without data being sent for specified amount of time). Returns async iterable.

const { stream } = require('tardis-dev')

const messages = stream({
  exchange: 'bitmex',
  filters: [
    { channel: 'trade', symbols: ['XBTUSD'] },
    { channel: 'orderBookL2', symbols: ['XBTUSD'] }
  ]
})

for await (const message of messages) {
  console.log(message)
}

replay(options) is the historical market data counterpart of stream function, returning historical market data in the same format.

stream options

name	type	default	description
exchange	string	-	requested exchange id - one of allowed values
filters	{channel:string, symbols?: string[]}[]	[]	optional filters of requested real-time data feed - use getExchangeDetails from Getting Started to get allowed channels and symbols ids for requested exchange
skipDecoding	boolean (optional)	undefined	when set to true returns messages as buffers instead of decoding them to objects
withDisconnects	boolean (optional)	undefined	when set to true returns message with value undefined for real-time stream disconnect events
timeoutIntervalMS	number	10000	specifies time in milliseconds after which connection is restarted if no message has been received from the exchange
onError	function (optional)	undefined	Optional callback (err) => void invoked when real-time WebSocket connection error occurs, useful for custom error logging etc.

type of messages provided by stream iterator (for await ...of)

type Message =
  | {
      localTimestamp: Date // local timestamp when message has been received
      message: any // message in exchange-native data format
    }
    // when skipDecoding is set to true
  | {
      localTimestamp: Buffer
      message: Buffer
    }

// when withDisconnects is set to true whole message can be undefined
Message | undefined

sample message

{
  localTimestamp: 2019-10-22T09:24:51.025Z,
  message: {
    table: 'orderBookL2',
    action: 'update',
    data: [
      { symbol: 'XBTUSD', id: 8799172400, side: 'Sell', size: 369501 }
    ]
  }
}

streamNormalized(options, ...normalizers)

Streams real-time market data messages for given stream options and normalizes messages using provided normalizers provided as rest arguments. It connects directly to exchanges WebSocket APIs and transparently restarts closed, broken or stale connections (open connections without data being sent for specified amount of time). Returns async iterable.

const tardis = require('tardis-dev')
const { streamNormalized, normalizeTrades, normalizeBookChanges } = tardis

const messages = streamNormalized(
  {
    exchange: 'bitmex',
    symbols: ['XBTUSD', 'ETHUSD']
  },
  normalizeTrades,
  normalizeBookChanges
)

for await (const message of messages) {
  console.log(message)
}

replayNormalized(options) is the historical counterpart of streamNormalized function, returning historical market data in the same format.

stream normalized options

name	type	default	description
exchange	string	-	requested exchange id - one of allowed values
symbols	string[] (optional)	undefined	instruments symbols for requested data feed
withDisconnectMessages	boolean (optional)	undefined	when set to true returns disconnect messages for real-time stream disconnect events
timeoutIntervalMS	number	10000	specifies time in milliseconds after which connection is restarted if no message has been received from the exchange
onError	function (optional)	undefined	Optional callback (err) => void invoked when real-time WebSocket connection or mapping error occurs, useful for custom error logging etc.

For sparse instruments (e.g., illiquid options or niche currency pairs), increase timeoutIntervalMS (e.g., 60000) to prevent unnecessary connection restarts when no messages arrive for extended periods. This is especially important for computed data types like trade_bar on low-volume symbols.

Built-in normalizers

streamNormalized function can accept any number of custom normalizers as rest parameters that map from exchange-native format to normalized data format. tardis-dev ships with built in ones that normalize trades, order book and derivative ticker data but also allows adding custom ones.

types of messages provided by streamNormalized iterator (for await ...of)

Message types and formats depend on specific normalizers provided to streamNormalized function and are documented in detail in Normalization and Local Processing.

sample message

Sample message produced by normalizeTrades

{
  type: 'trade',
  symbol: 'XBTUSD',
  exchange: 'bitmex',
  id: 'b1f4b309-80e2-1ffb-340b-2f7576f6ef0d',
  price: 7447.5,
  amount: 100,
  side: 'buy',
  timestamp: 2019-10-24T13:28:07.867Z,
  localTimestamp: 2019-10-24T13:28:07.938Z
}