# 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](https://docs.tardis.dev/faq/data#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)](https://docs.tardis.dev/replaying-historical-data#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`](https://docs.tardis.dev/quickstart#historical-market-data-helpers) from [Getting Started](https://docs.tardis.dev/quickstart#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/replaying-historical-data#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`](https://docs.tardis.dev/normalization#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](https://docs.tardis.dev/faq/data#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](https://docs.tardis.dev/node-client/normalization) but also allows [adding custom ones](https://docs.tardis.dev/normalization#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](https://docs.tardis.dev/node-client/normalization).

#### sample message

Sample message produced by [`normalizeTrades`](https://docs.tardis.dev/normalization#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
}
```