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 GZIP 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

GitHub - tardis-dev/tardis-node: Convenient access to tick-level real-time and historical cryptocurrency market data via Node.jsGitHub

Tardis-dev GitHub repository

Installation

Requires Node.js v24+ installed.

npm install tardis-dev --save

Historical Replay

Exchange-native

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

const messages = replay({
  exchange: 'bitmex',
  filters: [
    { channel: 'trade', symbols: ['XBTUSD'] },
    { channel: 'orderBookL2', symbols: ['XBTUSD'] }
  ],
  from: '2019-05-01',
  to: '2019-05-02'
})

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

Normalized

Replaying Historical Data

Real-Time Streaming

Exchange-native

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

Normalized

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*.

Usage with TypeScript

Simply change from require

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

to ES Modules import

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

to enjoy 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, as well as a custom cacheDir. apiKey can also be provided directly via options of replay and replayNormalized functions - that overrides anything that was provided via init.

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

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

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

getExchangeDetails(exchange)

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

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

const bitmexExchangeDetails = await getExchangeDetails('bitmex')

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'
    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'
      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 is available for it - exchanges, date ranges, symbols.

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

const details = await getApiKeyAccessInfo('YOUR_API_KEY')

type of response returned by awaiting on getApiKeyAccessInfo()

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

clearCache()

Clears local data cache dir.

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

await clearCache()

downloadDatasets(options)

Downloads CSV datasets for specified exchange, data types, symbols and date range. Handles pagination, retries and local file caching automatically.

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

await downloadDatasets({
  exchange: 'bitmex',
  dataTypes: ['trades', 'incremental_book_L2'],
  from: '2024-01-01',
  to: '2024-01-02',
  symbols: ['XBTUSD'],
  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.

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

const info = await getInstrumentInfo('bitmex', 'XBTUSD')