# bitmex-realtime-api

> A library for interacting with BitMEX's websocket API.

Latest version **1.5.5** (published 2024-05-22) · MIT license · 0 weekly downloads

## Install

```sh
npm install bitmex-realtime-api
pnpm add bitmex-realtime-api
yarn add bitmex-realtime-api
bun add bitmex-realtime-api
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.5.5 |
| Published | 2024-05-22 |
| First published | 2017-02-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=14 |
| Dependencies | 5 |
| Unpacked size | 40.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 907 |
| Author | Samuel Reed |
| Maintainers | strml, bitmexthomasb, bitmexyshing |
| Keywords | bitmex, bitcoin, websocket, api |

## Links

- npm: https://www.npmjs.com/package/bitmex-realtime-api
- Repository: https://github.com/BitMEX/api-connectors
- Homepage: https://github.com/BitMEX/api-connectors#readme
- Issues: https://github.com/BitMEX/api-connectors/issues
- npm.io page: https://npm.io/package/bitmex-realtime-api

## Dependencies (5)

- [ws](https://npm.io/package/ws.md) ^8.16.0
- [debug](https://npm.io/package/debug.md) ^4.3.4
- [lodash](https://npm.io/package/lodash.md) ^4.17.21
- [superagent](https://npm.io/package/superagent.md) ^8.1.2
- [eventemitter2](https://npm.io/package/eventemitter2.md) ^6.4.9

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 1.5.5 (latest) — 2024-05-22
- 1.5.4 — 2024-01-29
- 0.5.3 — 2023-03-20
- 0.5.2 — 2023-03-20
- 0.5.1 — 2021-11-01
- 0.5.0 — 2020-10-12
- 0.4.3 — 2019-11-18
- 0.4.0 — 2018-07-30
- 0.3.0 — 2018-05-30
- 0.2.6 — 2017-12-23
- 0.2.5 — 2017-12-20
- 0.2.4 — 2017-12-19
- 0.2.3 — 2017-09-06
- 0.2.2 — 2017-08-31
- 0.2.1 — 2017-08-22
- … 3 more at https://npm.io/package/bitmex-realtime-api/versions

## README

### 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](example.js).

To get started, create a new client:

```js
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.

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

#### API Reference

##### new BitMEXClient(object options)

Options:

```js
{
  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.

```js
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:
```js
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.

```js
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](https://www.bitmex.com/api/explorer).

```
"chat",            // Trollbox
"instrument",      // Instrument updates including turnover and bid/ask
"liquidation",     // Liquidations
"orderBookL2_25",  // Top 25 levels of level 2 order book
"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.

```
"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:

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

### Heartbeat
https://www.bitmex.com/app/wsAPI#Heartbeats

you can implement a more thorough solution, but hope this helps along
```
setInterval(() => {
  client.socket.send("ping")
}, 30 * 1000); // sends ping every 30 s
```

---
_Source: https://npm.io/package/bitmex-realtime-api · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._