Tardis-client NPM

tardis-client

Node.js client for tardis.dev - historical tick-level cryptocurrency market data replay API.

Provides fast easy to use wrapper for more low level HTTP API with local file based caching build in.

Installation

Requires Node.js v12+ installed.

npm install tardis-client

Usage

const { TardisClient } = require('tardis-client')
const tardisClient = new TardisClient()

// replay method returns async iterable
// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of

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

// this will return all trades and orderBookL2 messages for XBTUSD
// and all trades for ETHUSD for bitmex exchange
// between 2019-05-01T00:00:00.000Z and 2019-05-02T00:00:00.000Z (whole first day of May 2019)
for await (let { message, localTimestamp } of bitmexDataFeedMessages) {
  console.log(localTimestamp, message)

  // local timestamp is a JS Date (UTC) that marks timestamp when given message has been received
  // message is a message object as provided by exchange data feed
}

API

tardis-client exports single TardisClient class.

const { TardisClient } = require('tardis-client')

TardisClient

Optional client constructor options

name	type	default value	description
`apiKey` (optional)	`string or undefined`	`undefined`	optional `string` containing API key for tardis.dev API. If not provided only first day of each month of data is accessible (free access)
`cacheDir` (optional)	`string`	`<os.tmpdir>/.tardis-cache`	optional `string` with path to local dir that will be used as cache location. If not provided default `temp` dir for given OS will be used.

Example:

new TardisClient() // creates new client instance with access only to sample data (first day of each month)
new TardisClient({ apiKey: 'YOUR_API_KEY' }) // creates new client with access to all data for given API key
new TardisClient({ cacheDir: './cache' }) // creates new client with custom cache dir

tardisClient.clearCache()
Clears local file cache - it's an async function.
Example:
```
const tardisClient = new TardisClient()
await tardisClient.clearCache()
```
tardisClient.replay(ReplayOptions)
Replays historical market data messages for given replay options. Returns async iterable with objects of { localTimestamp: Date; message: object } type.
- localTimestamp is a JS Date object specyfying when message has been received from the exchange real-time data feed.
- message is and JSON object/array with exactly the same structure as provided by particular exchange.

ReplayOptions

name	type	default value	description
`exchange`	`string`	-	requested exchange name - see allowed exchanges list
`from`	`string`	-	requested UTC start date of data feed - (eg: `2019-04-05` or `2019-05-05T00:00:00.000Z`)
`to`	`string`	-	requested UTC end date of data feed - (eg: `2019-04-05` or `2019-05-05T00:00:00.000Z`)
`filters` (optional)	`{channel:string, symbols?: string[]}[]`	undefined	optional filters of requested data feed. Use /exchanges/:exchange API call to get allowed channel names and symbols for requested exchange

Examples:

const tardisClient = new TardisClient({ apiKey: 'YOUR_API_KEY' })

// replay returns async iterator
//  https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of

const coinbaseBTCTradesInMay = tardisClient.replay({
  exchange: 'coinbase',
  from: '2019-05-01',
  to: '2019-06-01',
  filters: [
    {
      channel: 'match',
      symbols: ['BTC-USD']
    }
  ]
})

for await (let { message, localTimestamp } of coinbaseBTCTradesInMay) {

}

const bimtexPerpTradesAndOrderBookUpdatesInApril = tardisClient.replay({
  exchange: 'bitmex',
  from: '2019-04-01',
  to: '2019-05-01',
  filters: [
    {
      channel: 'trade',
      symbols: ['XBTUSD','ETHUSD']
    },
    {
      channel: 'orderBookL2',
      symbols: ['XBTUSD','ETHUSD']
    }
  ]
})

for await (let { message, localTimestamp } of bimtexPerpTradesAndOrderBookUpdatesInApril) {

}

const wholeDeribitExchangeDataFeedInFirstOfMay = tardisClient.replay({
  exchange: 'deribit',
  from: '2019-05-01',
  to: '2019-05-02'
})

for await (let { message, localTimestamp } of wholeDeribitExchangeDataFeedInFirstOfMay) {

}

tardisClient.ReplayRaw(ReplayOptions)
Replays historical market data messages for given replay options. Accepts the same options as replay method. Returns async iterable with objects of { localTimestamp: Buffer; message: Buffer } type. It's faster than replay (no decoding to objects/dates, just raw buffers), but may manual decoding from buffers depending on the use case.
Example:
```
const rawDeribitDataFeedMessages = tardisClient.replayRaw({
  exchange: 'deribit',
  from: '2019-05-01',
  to: '2019-05-02'
})

for await (let { message, localTimestamp } of rawDeribitDataFeedMessages) {
  // here message and localtimestamps are Node.js buffers
}
```