@andersea/bitmex-realtime-api v0.3.1

Node.JS Adapter for BitMEX Realtime Data

This is a reference adapter for receiving realtime data from the BitMEX API.

Usage

The following is runnable in example.js.

To get started, create a new client:

const BitMEXClient = require('bitmex-realtime-api');
// See 'options' reference below
const client = new BitMEXClient({testnet: true});

Then subscribe to a symbol and table, and pass a callback.

client.addStream('XBTUSD', 'instrument', function (data, symbol, tableName) {
  // Do something with the table data...
});

API Reference

new BitMEXClient(object options)

Options:

{
  testnet: false, // set `true` to connect to the testnet site (testnet.bitmex.com)
  // Set API Key ID and Secret to subscribe to private streams.
  // See `Available Private Streams` below.
  apiKeyID: '',
  apiKeySecret: '',
  maxTableLen: 10000  // the maximum number of table elements to keep in memory (FIFO queue)
}

client.addStream(string symbol, string tableName, function callback)

Subscribe to a data stream. Pass a symbol to subscribe to all public data for an instrument.

Pass tableName to receive data for a specific table.

client.addStream('XBTUSD', 'quote', function (data, symbol, tableName) {
  if (!data.length) return;
  const quote = data[data.length - 1];  // the last data element is the newest quote
  // Do something with the quote (.bidPrice, .bidSize, .askPrice, .askSize)
});

client.on(string eventName, function callback)

The client also doubles as a basic EventEmitter. The following events are fired:

"initialize"  // Socket initialized, client.streams available
"error"
"open"
"close"

Example:

client.on('initialize', () => {
  console.log(client.streams);  // Log .public, .private and .all stream names
});

Note: Don't forget to attach an error handler! If one is not attached, errors will be thrown and crash your client.

client.getData(string symbol, string tableName)

Use this function to access data directly. Pass either a symbol, or tableName, or both. Data returned by this method is safe to modify as it is cloned from the internal stores.

If speed is a concern, all data is accessible directly inside the client via the client._data property. Do not modify this data, or you will corrupt further updates!

client.getSymbol(string symbol)

Same as above, but returns all tables for a given symbol.

client.getTable(string tableName)

Same as above, but returns all symbols for a given table.

client.addStream('XBTUSD', 'trade', () => {});
setTimeout(() => {
  console.log('XBTUSD trades during the last few seconds:', client.getTable('trade').XBTUSD);
}, 5000);

Available Public Streams

The streams below echo the models described in the API Explorer.

"chat",         // Trollbox
"instrument",   // Instrument updates including turnover and bid/ask
"liquidation",  // Liquidations
"orderBookL2",  // Full orderBook using deltas
"orderBook10",  // Last 10 bids and asks (price and size)
"quote",        // Top level of the book
"trade"         // Trades
...             // See https://www.bitmex.com/app/wsAPI#Subscriptions for more streams

Available Private Streams

The following streams require authentication via an API key. Use this Python script to easily create a key.

"execution",    // Individual order placements and executions, settlements, commissions
"margin",       // Your account's margin details
"order",        // Order creations, cancellations, and updates
"position"      // Your positions, per instrument
...             // See https://www.bitmex.com/app/wsAPI#Subscriptions for more streams

Debugging

For much more information on what this module is doing, run it with the DEBUG environment variable. For example:

# Display all debug messages
DEBUG=* node example.js
# Display all high-level debug messages
DEBUG=BitMEX:* node example.js