Bitcoin price websocket

BitMEX offers a complete pub/sub API with table diffing over WebSocket. You may subscribe to real-time changes on any available table.

Reference Connectors

For working code and examples, please see our WebSocket Connectors on GitHub.

Connecting

Connect your websocket client to .

You can get a basic idea of how to use our websocket API by sending .

All Commands

A basic command is sent in the following format:

The array is optional on some commands. If you are only sending a single argument, the array is not necessary.

Note that placing and canceling orders is not supported via the Websocket. Please use the REST API for this. When using HTTP Keep-Alive, request/response round-trip time will be identical to Websocket.

Subscriptions

BitMEX allows subscribing to real-time data. This access is not rate-limited once connected and is the best way to get the most up-to-date data to your programs.

To subscribe to topics, send them as a comma-separated list in your connection string. For example:

If you are already connected and wish to subscribe to a new topic, send a message with the following format:

You may subscribe to multiple topics at a time by sending an array of subscription topics.

The following subscription topics are available without authentication:

The following subjects require authentication:

If you wish to get real-time order book data, we recommend you use the subscription. pushes the top 10 levels on every tick, but transmits much more data. pushes the full L2 order book, but the payload can get very large. provides a subset of the full L2 orderbook, but is throttled. In the future, may be throttled, so use in any latency-sensitive application. For those curious, the on an or entry is a composite of price and symbol, and is always unique for any given price level. It should be used to apply and actions.

When applicable, subjects may be filtered to a given instrument by appending a colon and instrument name. For example, will subscribe you to messages only for the instrument.

Some traffic:

Upon subscription, you will receive an image of the existing data, so you can get started. This comes through as a action.

You may receive other messages before the comes through. In that case, drop any messages received until you have received the .

Some notes on this response:

• After the subscription acknowledgement, you’ll receive a message with . This is an image of the table, after which you can apply deltas.
  • If you receive any messages before the , ignore them.
• The also contains some table information, like , , and . Depending on your application, this data may be useful.
  • Columns listed in always come back on an , , or . Use them to look up which items to modify in your storage.

For an example of this in action, see our official NodeJS Delta Parser.

You may unsubscribe using the operation. The formatting is identical to .

Authentication

A number of data streams are publicly available (see below). If you wish to subscribe to user-locked streams, you must authenticate first. Note that invalid authentication will close the connection.

API Keys

BitMEX API usage requires an API Key.

Permanent API Keys can be locked to IP address ranges and revoked at will without compromising your main credentials. They also do not require renewal.

To use API Key auth, you must generate an API Key.

To use an API Key with websockets, you can either:

• Sign the initial upgrade request in the same manner you would sign other REST calls ( headers), or
• After connection, send an .

In both cases, use a signature as if you were signing . See this Python implementation for an example and working code.

If you have questions about authenticating with an API Key, please see the API Key Authentication Documentation.

Heartbeats

Some WebSocket libraries are better than others at detecting connection drops. If your websocket library supports , or , you may send a ping at any time and the server will return with a pong.

Due to changes in browser power-saving modes, we no longer support expectant pings via the WebSocket API.

If you are concerned about your connection silently dropping, we recommend implementing the following flow:

• After receiving each message, set a timer a duration of 5 seconds.
• If any message is received before that timer fires, restart the timer.
• When the timer fires (no messages received in 5 seconds), send a raw frame (if supported) or the literal string .
• Expect a raw frame or the literal string in response. If this is not received within 5 seconds, throw an error or reconnect.

Dead Man’s Switch (Auto Cancel)

BitMEX offers “Dead Man’s Switch” functionality to help prevent unexpected losses from network malfunctions. If you are putting up significant risk on BitMEX, it can be nerve-wracking to think of what might happen if you or your datacenter loses connectivity.

Via REST at or via WebSocket via the example below, one can set a millisecond timeout. This will start a timer. If is not called again before time runs out, all of your existing orders on all symbols will be canceled.

To cancel this operation and keep your orders open, pass a of .

Advanced users of BitMEX should use this operation. A common use pattern is to set a of , and call it every 15 seconds. This gives you sufficient wiggle room to keep your orders open in case of a network hiccup, while still offering significant protection in case of a larger outage. Of course, the parameters are up to you.

We recommend not setting a timeout of less than 5 seconds to avoid being rate limited or having your orders unexpectedly canceled in case of network congestion.

For example:

Rate Limits

The following actions are ratelimited:

• Subscription: Consumes one token from your request limiter.
• Connection: 40 per hour, on a separate limiter.
• Dead Man’s Switch (): Consumes one token from your request limiter.

If you exceed your ratelimit on a subscription or call, you will see a message like:

If you are ratelimited from connecting, the message is slightly different (example includes headers):

Response Format

Websocket responses may be of the following three types:

Success: (Emitted upon a successful subscription to a topic)

Error: (Emitted upon a malformed request or an attempt to request a locked resource)

Data: (Emitted when data is available or requested)

This definition follows the typing conventions used in Flowtype and TypeScript. Fields suffixed with are not always present. See the comments for more details.

Reference Implementation

We have a reference implementation of the websocket as part of our reference Market Maker.

Of interest is the function, which handles updating tables in memory.

Data Example

Outgoing messages are prefixed with . Incoming messages are prefixed with .

Using the python tool wsdump:

Data Samples

These include a few messages you might not see often in your testing; they are replicated here so you know how to handle them.

Liquidation

This assumes a 1-contract position with a liquidation price of 1140.1. At the time of this snap, the mark price jumped down to 1136.88.

Deleverage

The following shows the deleverage of a 2000-contract position.

OrderBookL2

A special note on the table, which is the canonical table for orderbook updates and the only way to retrieve all levels:

This orderbook is keyed by a unique ID, not price, so that all levels are unique across all symbols. This may be unintuitive at first but ensures that each level across the entire system is uniquely keyed. Therefore, when you retrieve an update, it may look like this:

Notice that this does not include the , which you should already have set on the level. The process for handling updates, inserts, deletes, and partials on this stream is exactly the same as any other stream and requires no special handling. However, some tooling may make assumptions about book entries, like keying them by price.

In that case, there are a few ways to handle this:

1. Keep a local hashmap of s you’ve seen to their . When you receive an or , look up the in this map. This is simple but will consume some memory.
2. Use the following formula to reverse-engineer the ID:

Definitions:

• is the index of the instrument in the list of instruments
• as the instrument’s property.
  • Due to in-flight changes of on some XBT contracts, an override may need to be applied. See below.

This can be written as:

Applied to our update above, where the ID was , you should get a resulting price of :

Multiplexing

This is intended for advanced users only.

The BitMEX Websocket supports a very simple multiplexing scheme. Use this in place of many individual connections.

The most common use case is to keep a stream open for market data, and multiple streams for individual subaccounts.

Multiplexing has a different endpoint. Use (that’s “realtime-mux-demux”) for multiplexing capabilities.

The protocol is very simple:

Packet Format:

Definitions:

• : See “Packet Types” below.
• : Client-selected unique ID for this stream. This can be arbitrary; consider using a unique identifier like userID.
• : Client-selected non-unique purpose for this stream. This is required but can be any string you wish.
  • Note: All returned messages will include the and . Unsubscribing is done via .
• : For types, the payload is exactly equal to any message one would send via a non-multiplexed stream.

Packet Types:

• :
  • When a stream is opened, use this type to send a message on a given topic.
• :
  • Use to open a stream. Both and may contain any data but must be unique.
• :
  • Use to close a stream. must match the one used for the subscription.

Example

Outgoing messages are prefixed with . Incoming messages are prefixed with .