Quickstart

Install, configure and get started with the tardis-dev npm package

Node.js tardis-dev library provides convenient access to tick-level historical and real-time cryptocurrency market data both in exchange-native and normalized formats. Instead of callbacks it relies on async iteration (for await ...of) enabling composability features like seamless switching between real-time data streaming and historical data replay or computing derived data locally.

Features

historical tick-level market data replay backed by Tardis.dev HTTP API — includes full order book depth snapshots plus incremental updates, trades, historical open interest, funding, index, mark prices, liquidations and more
consolidated real-time data streaming API connecting directly to exchanges' public WebSocket APIs
support for both exchange-native and normalized market data formats (unified format for accessing market data across all supported exchanges — normalized trades, order book and ticker data)
seamless switching between real-time streaming and historical market data replay thanks to async iterables providing unified way of consuming data messages
transparent historical local data caching (cached data is stored on disk in compressed format and decompressed on demand when reading the data)
support for top cryptocurrency exchanges: BitMEX, Deribit, Binance Spot, Binance USDS-M Futures, OKX Spot, HTX Spot, bitFlyer, Bitstamp, Coinbase Exchange, Kraken Futures (Crypto Facilities), Gemini, Kraken, Bitfinex, Bybit Derivatives and more
automatic closed connections and stale connections reconnection logic for real-time streams
combining multiple exchanges feeds into single one via combine helper function — synchronized historical market data replay and consolidated real-time data streaming from multiple exchanges
computing derived data locally like order book imbalance, customizable trade bars, book snapshots and more via compute helper function and computables, e.g., volume based bars, top 20 levels order book snapshots taken every 10 ms etc
full limit order book reconstruction both for real-time and historical data via OrderBook object
fast and lightweight architecture — low memory footprint and no heavy in-memory buffering
extensible mapping logic that allows adjusting normalized formats for specific needs
built-in TypeScript support
Open Source

Installation

Requires Node.js v24+ installed.

npm install tardis-dev --save

Node.js examples on this page use ES modules and top-level await. Save snippets as .mjs or set "type": "module" in your package.json.

Historical Replay

import { replay } from 'tardis-dev'

const messages = replay({
  exchange: 'binance',
  filters: [
    { channel: 'trade', symbols: ['btcusdt'] },
    { channel: 'depth', symbols: ['btcusdt'] }
  ],
  from: '2024-03-01',
  to: '2024-03-02'
})

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

import { replayNormalized, normalizeTrades, normalizeBookChanges } from 'tardis-dev'

const messages = replayNormalized(
  {
    exchange: 'binance',
    symbols: ['btcusdt'],
    from: '2024-03-01',
    to: '2024-03-02'
  },
  normalizeTrades,
  normalizeBookChanges
)

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

Replaying Historical Data

Real-Time Streaming

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

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

Streaming Real-Time Data

Debugging and logging

tardis-dev lib uses debug package for verbose logging and debugging purposes that can be enabled via DEBUG environment variable set to tardis-dev*.

ES Modules and TypeScript

Examples in this page use standard ES module imports and top-level await:

import { replay, stream } from 'tardis-dev'

const messages = replay({ exchange: 'binance', from: '2024-03-01', to: '2024-03-02' })

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

This works in modern Node.js and gives you first class TypeScript typings.

Historical market data helpers

`init(options)`

This function doesn't affect real-time streaming functionality in any way, it's useful only for historical data replay.

When working with market data via replay and replayNormalized, by default only the first day of each month of historical data is available for replay, and locally cached historical data is stored in the default location on disk (OS temp dir).

Init function allows providing an apiKey received via email after ordering historical market data access via Tardis.dev website, a custom cacheDir, and the preferred compression for historical replay requests. apiKey can also be provided directly via options of replay and replayNormalized functions - that overrides anything that was provided via init.

import { init } from 'tardis-dev'

init({
  apiKey: 'YOUR API KEY',
  cacheDir: 'CUSTOM CACHE DIR PATH',
  dataFeedCompression: 'gzip'
})

init options

name

type

default

description

apiKey

string (optional)

undefined

API key for Tardis.dev HTTP API - if not provided only first day of each month of historical data is accessible

cacheDir

string

<os.tmpdir>/.tardis-cache

path to local dir that will be used as cache location - if not provided default temp dir for given OS will be used

dataFeedCompression

'zstd' | 'gzip' (optional)

'zstd'

preferred compression for historical replay requests; set to 'gzip' when you need the client to request gzip-compressed slices

`getExchangeDetails(exchange)`

Given exchange id provides exchange details (available symbols, availability dates, available channels, pricing info etc) provided by exchanges/:exchange API endpoint.

import { getExchangeDetails } from 'tardis-dev'

const binanceExchangeDetails = await getExchangeDetails('binance')
console.log(binanceExchangeDetails.id)

type of response returned by awaiting on `getExchangeDetails`

{
  id: string
  name: string
  enabled: boolean
  delisted?: boolean
  availableSince: string
  availableTo?: string

  availableChannels: string[]

  availableSymbols: {
    id: string
    type: 'spot' | 'future' | 'perpetual' | 'option' | 'combo' | 'prediction'
    availableSince: string
    availableTo?: string
    name?: string
  }[]

  incidentReports: {
    from: string
    to: string
    status: 'resolved' | 'wontfix' | 'unresolved'
    details: string
  }[]

  channelDetails: {
    name: string
    description: string
    frequency: string
    frequencySource: string
    exchangeDocsUrl?: string
    sourceFor?: string[]
    availableSince: string
    availableTo?: string
    apiVersion?: string
    additionalInfo?: string
    generated?: true
  }[]

  apiDocsUrl?: string

  dataCollectionDetails?: {
    recorderDataCenter: {
      host: string
      regionId: string
      location: string
    }
    recorderDataCenterChanges?: {
      until: string
      dataCenter: { host: string; regionId: string; location: string }
    }[]
    wssConnection?: {
      url: string
      apiVersion?: string
      proxiedViaCloudflare?: boolean
    }
    wssConnectionChanges?: {
      until: string
      url?: string
      apiVersion?: string
      proxiedViaCloudflare?: boolean
    }[]
    exchangeDataCenter?: {
      host: string
      regionId: string
      location: string
    }
    exchangeDataCenterChanges?: {
      until: string
      dataCenter: { host: string; regionId: string; location: string }
    }[]
  }

  datasets: {
    formats: ['csv']
    exportedFrom: string
    exportedUntil: string
    stats: {
      trades: number
      bookChanges: number
    }
    symbols: {
      id: string
      type: 'spot' | 'future' | 'perpetual' | 'option' | 'combo' | 'prediction'
      availableSince: string
      availableTo?: string
      dataTypes: DatasetType[]
    }[]
  }
}

// where DatasetType is one of:
type DatasetType =
  | 'trades'
  | 'incremental_book_L2'
  | 'quotes'
  | 'derivative_ticker'
  | 'options_chain'
  | 'book_snapshot_25'
  | 'book_snapshot_5'
  | 'liquidations'
  | 'book_ticker'

`getApiKeyAccessInfo(apiKey?)`

Given apiKey provided as optional parameter or provided in init function provides information about what historical data access is available for it: exchanges, access type, data plan, date ranges, and symbol restrictions.

import { getApiKeyAccessInfo } from 'tardis-dev'

const details = await getApiKeyAccessInfo('YOUR_API_KEY')
console.log(details)

type of response returned by awaiting on `getApiKeyAccessInfo()`

{
  exchange: string
  accessType: string
  from: string
  to: string
  symbols: string[]
  dataPlan: string
}[]

`clearCache()`

Clears local data cache dir.

import { clearCache } from 'tardis-dev'

await clearCache()

`downloadDatasets(options)`

Downloads CSV datasets for specified exchange, data types, symbols and date range. Handles day-by-day downloads, retries and skipping already-downloaded files automatically.

import { downloadDatasets } from 'tardis-dev'

await downloadDatasets({
  exchange: 'binance',
  dataTypes: ['trades', 'incremental_book_L2'],
  from: '2024-03-01',
  to: '2024-03-02',
  symbols: ['BTCUSDT'],
  apiKey: 'YOUR_API_KEY'
})

Download via client libraries

`getInstrumentInfo(exchange, symbol)`

Returns instrument metadata (tick sizes, contract multipliers, base/quote currencies) for a given exchange and symbol.

import { getInstrumentInfo, init } from 'tardis-dev'

init({ apiKey: 'YOUR_API_KEY' }) // set API key globally for instrument info requests

const info = await getInstrumentInfo('binance', 'btcusdt')
console.log(info)

You can also pass an instrument metadata filter, or an array of exchanges, when you need full metadata records.

`findInstrumentSymbols(exchanges, filter, selector?)`

Use this helper when you know the market you want but not each exchange's symbol format. It queries the Instruments Metadata API with normalized criteria and returns the correct exchange-specific id for each requested exchange, ready to pass to replay, streaming, or raw data feeds.

import { findInstrumentSymbols, init } from 'tardis-dev'

init({ apiKey: 'YOUR_API_KEY' })

const symbolsByExchange = await findInstrumentSymbols(['bitmex', 'binance-futures', 'okex-swap', 'bybit'], {
  baseCurrency: 'BTC',
  quoteCurrency: 'USDT',
  contractType: 'linear_perpetual',
  active: true
})

console.log(symbolsByExchange)
// [
//   { exchange: 'bitmex', symbols: ['XBTUSDT'] },
//   { exchange: 'binance-futures', symbols: ['btcusdt'] },
//   { exchange: 'okex-swap', symbols: ['BTC-USDT-SWAP'] },
//   { exchange: 'bybit', symbols: ['BTCUSDT'] }
// ]

The optional selector defaults to id. Pass datasetId only when you need symbols for direct CSV dataset file downloads:

const csvSymbolsByExchange = await findInstrumentSymbols(
  ['bitmex', 'binance-futures', 'okex-swap', 'bybit'],
  {
    baseCurrency: 'BTC',
    quoteCurrency: 'USDT',
    contractType: 'linear_perpetual',
    active: true
  },
  'datasetId'
)

Returned symbols are exchange-provided IDs and are not normalized by the client.

PreviousHTTP API Reference NextReplaying Historical Data

Last updated 13 days ago

Was this helpful?

Features

Installation

Historical Replay

Real-Time Streaming

Debugging and logging

ES Modules and TypeScript

Historical market data helpers

init(options)

init options

getExchangeDetails(exchange)

type of response returned by awaiting on getExchangeDetails

getApiKeyAccessInfo(apiKey?)

type of response returned by awaiting on getApiKeyAccessInfo()

clearCache()

downloadDatasets(options)

getInstrumentInfo(exchange, symbol)

findInstrumentSymbols(exchanges, filter, selector?)