# Streaming Real-Time Data Real-time market data streaming connecting directly to exchanges' WebSocket APIs with automatic reconnection. ## `stream(options)` Streams real-time market data messages for given stream options in [exchange-native format](/faq/data.md#what-is-a-difference-between-exchange-native-and-normalized-data-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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of). ```javascript import { stream } from 'tardis-dev' const messages = stream({ exchange: 'binance', filters: [ { channel: 'trade', symbols: ['btcusdt'] }, { channel: 'depth', symbols: ['btcusdt'] } ] }) for await (const { localTimestamp, message } of messages) { console.log(localTimestamp, message) } ``` {% hint style="info" %} [replay(options)](/node-client/replaying-historical-data.md#replay-options) is the historical market data counterpart of `stream` function, returning historical market data in the same format. {% endhint %} #### stream options | name | type | default | description | | --------------------- | ---------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **exchange** | string | - | requested exchange id - one of [allowed values](https://github.com/tardis-dev/tardis-node/blob/master/src/consts.ts#L1) | | **filters** | {channel:string, symbols?: string\[]}\[] | \[] | optional filters of requested real-time data feed - use [`getExchangeDetails`](/node-client/quickstart.md#historical-market-data-helpers) from [Getting Started](/node-client/quickstart.md#historical-market-data-helpers) to get allowed channels and symbols ids for requested exchange | | **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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of)) ```typescript type Message = { localTimestamp: Date // local timestamp when message has been received message: any // message in exchange-native data format } // when withDisconnects is set to true whole message can be undefined Message | undefined ``` #### sample message ```javascript { localTimestamp: 2024-03-01T00:00:00.001Z, message: { stream: 'btcusdt@trade', data: { e: 'trade', E: 1709251199998, s: 'BTCUSDT', t: 3445374963, p: '61130.98000000', q: '0.00145000', b: 25230662315, a: 25230662808, T: 1709251199998, m: true, M: true } } } ``` ## `streamNormalized(options, ...normalizers)` Streams real-time market data messages for given stream options and **normalizes messages** using provided normalizers provided as [rest arguments](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/rest_parameters). 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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of). ```javascript import { streamNormalized, normalizeTrades, normalizeBookChanges } from 'tardis-dev' const messages = streamNormalized( { exchange: 'binance', symbols: ['btcusdt'] }, normalizeTrades, normalizeBookChanges ) for await (const message of messages) { console.log(message) } ``` {% hint style="info" %} [replayNormalized(options, ...normalizers)](https://docs.tardis.dev/node-client/pages/gkHZyu4v8WrMNBBiqduR#replaynormalized-options-...normalizers) is the historical counterpart of `streamNormalized` function, returning historical market data in the same format. {% endhint %} #### stream normalized options | name | type | default | description | | -------------------------- | -------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | **exchange** | string | - | requested exchange id - one of [allowed values](https://github.com/tardis-dev/tardis-node/blob/master/src/consts.ts#L1) | | **symbols** | string\[] (optional) | undefined | instruments symbols for requested data feed | | **withDisconnectMessages** | boolean (optional) | undefined | when set to `true` returns [`disconnect`](/node-client/normalization.md#disconnect-message) 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. | {% hint style="info" %} 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. {% endhint %} #### Built-in normalizers `streamNormalized` function can accept any number of custom normalizers as [rest parameters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/rest_parameters) that map from [exchange-native format](/faq/data.md#what-is-a-difference-between-exchange-native-and-normalized-data-format) to normalized data format. `tardis-dev` ships with [built in ones that normalize trades, order book and derivative ticker data](/node-client/normalization.md) but also allows [adding custom ones](/node-client/normalization.md#modifying-built-in-and-adding-custom-normalizers). #### types of messages provided by `streamNormalized` iterator ([`for await ...of`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of)) Message types and formats depend on specific normalizers provided to `streamNormalized` function and are documented in detail in [Normalization](/node-client/normalization.md). #### sample message Sample message produced by [`normalizeTrades`](/node-client/normalization.md#normalizetrades) ```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 } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.tardis.dev/node-client/streaming-real-time-data.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.