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 the primary websocket endpoint wss://ws.bitmex.com/realtime for trading related topics (see below).

Alternate endpoints depending on topic:

• For platform topics, wss://ws.bitmex.com/realtimePlatform

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

All Commands

A basic command is sent in the following format:

{"op": "<command>", "args": ["arg1", "arg2", "arg3"]}

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

• Subscriptions:
  • subscribe
  • unsubscribe
• Authentication (required for account data):
• Heartbeating
  • Raw ping
  • cancelAllAfter (Order Cancel on Timeout)

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:

wss://ws.bitmex.com/realtime?subscribe=instrument,orderBookL2_25:XBTUSD

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

{"op": "subscribe", "args": [<SubscriptionTopic>]}

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

The following subscription topics are available on the primary endpoint without authentication:

"funding",             // Updates of swap funding rates. Sent every funding interval (usually 8hrs)
"instrument",          // Instrument updates including turnover and bid/ask
"insurance",           // Daily Insurance Fund updates
"liquidation",         // Liquidation orders as they're entered into the book
"orderBookL2_25",      // Top 25 levels of level 2 order book
"orderBookL2",         // Full level 2 order book
"orderBook10",         // Top 10 levels using traditional full book push
"quote",               // Top level of the book
"quoteBin1m",          // 1-minute quote bins
"quoteBin5m",          // 5-minute quote bins
"quoteBin1h",          // 1-hour quote bins
"quoteBin1d",          // 1-day quote bins
"settlement",          // Settlements
"trade",               // Live trades
"tradeBin1m",          // 1-minute trade bins
"tradeBin5m",          // 5-minute trade bins
"tradeBin1h",          // 1-hour trade bins
"tradeBin1d",          // 1-day trade bins

The following subscription topics require authentication and are also available on the primary endpoint:

"affiliate",   // Affiliate status, such as total referred users & payout %
"execution",   // Individual executions; can be multiple per order
"order",       // Live updates on your orders
"margin",      // Updates on your current account balance and margin requirements
"position",    // Updates on your positions
"transact"     // Deposit/Withdrawal updates
"wallet"       // Bitcoin address balance data, including total deposits & withdrawals

The following subscriptions are only available on the /realtimePlatform endpoint:

"announcement",        // Site announcements
"chat",                // Trollbox chat
"connected",           // Statistics of connected users/bots
"publicNotifications", // System-wide notifications (used for short-lived messages)
"privateNotifications", // Individual notifications - currently not used (requires auth)

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

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

Some traffic:

> {"op": "subscribe", "args": ["orderBookL2_25:XBTUSD"]}
  < {"success":true,"subscribe":"orderBookL2_25:XBTUSD","request":{"op":"subscribe","args":["orderBookL2_25:XBTUSD"]}}
  < {
      "table":"orderBookL2_25",
      "keys":["symbol","id","side"],
      "types":{"id":"long","price":"float","side":"symbol","size":"long","symbol":"symbol","timestamp":"timestamp"}
      "action":"partial",
      "data":[
        {"symbol":"XBTUSD","id":17999992000,"side":"Sell","size":100,"price":80,"timestamp":"2022-02-09T11:23:06.802Z"},
        {"symbol":"XBTUSD","id":17999993000,"side":"Sell","size":20,"price":70,"timestamp":"2022-02-09T11:23:06.802Z"},
        {"symbol":"XBTUSD","id":17999994000,"side":"Sell","size":10,"price":60,"timestamp":"2022-02-09T11:23:06.802Z"},
        {"symbol":"XBTUSD","id":17999995000,"side":"Buy","size":10,"price":50,"timestamp":"2022-02-09T11:23:06.802Z"},
        {"symbol":"XBTUSD","id":17999996000,"side":"Buy","size":20,"price":40,"timestamp":"2022-02-09T11:23:06.802Z"},
        {"symbol":"XBTUSD","id":17999997000,"side":"Buy","size":100,"price":30,"timestamp":"2022-02-09T11:23:06.802Z"}
      ]
    }
  < {
      "table":"orderBookL2_25",
      "action":"update",
      "data":[
        {"symbol":"XBTUSD","id":17999995000,"side":"Buy","size":5}
      ]
    }
  < {
      "table":"orderBookL2_25",
      "action":"delete",
      "data":[
        {"symbol":"XBTUSD","id":17999995000,"side":"Buy"}
      ]
    }
  < {
      "table":"orderBookL2_25",
      "action":"insert",
      "data":[
        {"symbol":"XBTUSD","id":17999995500,"side":"Buy","size":10,"price":45},
      ]
    }

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

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

Some notes on this response:

• After the subscription acknowledgement, you’ll receive a message with "action": "partial". This is an image of the table, after which you can apply deltas.
  • If you receive any messages before the partial, ignore them.
• The partial also contains some table information, like keys and types. Depending on your application, this data may be useful.
  • Columns listed in keys always come back on an insert, delete, or update. 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 'unsubscribe' operation. The formatting is identical to 'subscribe'.

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 (api-* headers), or
• After connection, send an "authKeyExpires".

In both cases, use a signature as if you were signing GET /realtime. 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.

// signature is hex(HMAC_SHA256(secret, 'GET/realtime' + expires))
// expires must be a number, not a string.
{"op": "authKeyExpires", "args": ["<APIKey>", <expires>, "<signature>"]}

Heartbeats

Some WebSocket libraries are better than others at detecting connection drops. If your websocket library supports hybi-13, or ping/pong, 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 ping frame (if supported) or the literal string 'ping'.
• Expect a raw pong frame or the literal string 'pong' 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 /order/cancelAllAfter or via WebSocket via the example below, one can set a millisecond timeout. This will start a timer. If cancelAllAfter 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 timeout of 0.

Advanced users of BitMEX should use this operation. A common use pattern is to set a timeout of 60000, 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:

// Places a dead man's switch at 60 seconds.
> {"op": "cancelAllAfter", "args": 60000}
  < {"now":"2015-09-02T14:18:43.536Z","cancelTime":"2015-09-02T14:19:43.536Z",
     "request":{"op":"cancelAllAfter","args":60000}}
// Cancels the switch.
> {"op": "cancelAllAfter", "args": 0}
  < {"now":"2015-09-02T14:19:11.617Z","cancelTime":0,"request":{"op":"cancelAllAfter","args":0}}

Rate Limits

The following actions are ratelimited:

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

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

{"status":429,"error":"Rate limit exceeded, retry in 1 seconds.","meta":{"retryAfter":1},"request":{"op":"subscribe","args":"orderBookL2_25"}}

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

HTTP/1.1 429 Too Many Requests
Cache-Control: no-store, no-cache, must-revalidate, max-age=0
Pragma: no-cache
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1506983924
Retry-After: 29
Content-Type: application/json
Content-Length: 55
Date: Mon, 02 Oct 2017 21:43:49 GMT
Connection: keep-alive

{"error":"Rate limit exceeded, retry in 29 seconds."}

Response Format

Websocket responses may be of the following three types:

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

{"subscribe": subscriptionName, "success": true}

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

{"error": errorMessage}

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.

{
  // Table name / Subscription topic.
  // Could be "trade", "order", "instrument", etc.
  "table": string,

  // The type of the message. Types:
  // 'partial'; This is a table image, replace your data entirely.
  // 'update': Update a single row.
  // 'insert': Insert a new row.
  // 'delete': Delete a row.
  "action": 'partial' | 'update' | 'insert' | 'delete',

  // An array of table rows is emitted here. They are identical in structure to data returned from the REST API.
  "data": Object[],

  //
  // The below fields define the table and are only sent on a `partial`
  //

  // Attribute names that are guaranteed to be unique per object.
  // If more than one is provided, the key is composite.
  // Use these key names to uniquely identify rows. Key columns are guaranteed
  // to be present on all data received.
  "keys"?: string[],

  // This lists the shape of the table. The possible types:
  // "symbol" - In most languages this is equal to "string"
  // "guid"
  // "timestamp"
  // "timespan"
  // "float"
  // "long"
  // "integer"
  // "boolean"
  "types"?: {[key: string]: string},

  // When multiple subscriptions are active to the same table, use the `filter` to correlate which datagram
  // belongs to which subscription, as the `table` property will not contain the subscription's symbol.
  "filter"?: {account?: number, symbol?: string},
}

Reference Implementation

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

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

Data Example

Outgoing messages are prefixed with >. Incoming messages are prefixed with <.

Using the python tool wsdump:

~/g/f/w/bin (master|✔) $ python wsdump.py \
  wss://ws.bitmex.com/realtime/websocket?accessToken=xnyXWIQL0sbrLC91ISDlFhuLUGQJNq05A...
Press Ctrl+C to quit

  < {"info":"Welcome to the BitMEX Realtime API.","version":"1.1.0",
     "timestamp":"2015-01-18T10:14:06.802Z","docs":"https://www.bitmex.com/app/wsAPI","heartbeatEnabled":false}

> "help"

  < {"info":"See https://www.bitmex.com/app/wsAPI and https://www.bitmex.com/explorer for more documentation.",...}

> {"op": "subscribe", "args": ["trade:XBTUSD","instrument:XBTUSD"]}

  < {"success":true,"subscribe":"trade:XBTUSD",
     "request":{"op":"subscribe","args":["trade:XBTUSD","instrument:XBTUSD"]}}
  < {"success":true,"subscribe":"instrument:XBTUSD",
     "request":{"op":"subscribe","args":["trade:XBTUSD","instrument:XBTUSD"]}}

  < {"table":"trade","action": "partial", ...}
  < {"table":"instrument","action": "partial", ...}

  < {"table":"instrument","action":"update","data":[{"symbol":"XBTUSD","fairPrice":380.52,
     "markPrice":380.52,"indicativeSettlePrice":380.52,"timestamp":"2016-01-15T22:33:15.000Z"}]}
  < {"table":"instrument","action":"update","data":[{"symbol":"XBTUSD","openValue":673520400,
     "timestamp":"2016-01-15T22:33:15.000Z"}]}

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 XBTUSD position with a liquidation price of 1140.1. At the time of this snap, the mark price jumped down to 1136.88.

# First, the position will update to a 'posState' of 'Liquidation'.
# Notice that the mark price is below the liquidation price. On a long, that means liquidation.
< {"table":"position",
   "action":"update",
   "data":[{
    "account":2,"symbol":"XBTUSD","currency":"XBt",
    "currentTimestamp":"2017-04-04T22:07:42.442Z", "currentQty":1,"markPrice":1136.88,"markValue":-87960,
    "riskValue":87960,"homeNotional":0.0008796,"posState":"Liquidation","maintMargin":263,
    "unrealisedGrossPnl":-677,"unrealisedPnl":-677,"unrealisedPnlPcnt":-0.0078,"unrealisedRoePcnt":-0.7756,
    "simpleQty":0.001,"liquidationPrice":1140.1, "timestamp":"2017-04-04T22:07:45.442Z"
   }]}

# Then, the liquidation execution is inserted. Notice that 'text' is 'Liquidation'.
< {"table":"execution",
   "action":"insert",
   "data":[{
    "execID":"0193e879-cb6f-2891-d099-2c4eb40fee21",
    "orderID":"00000000-0000-0000-0000-000000000000","clOrdID":"","clOrdLinkID":"","account":2,"symbol":"XBTUSD",
    "side":"Sell","lastQty":1,"lastPx":1134.37,"underlyingLastPx":null,"lastMkt":"XBME",
    "lastLiquidityInd":"RemovedLiquidity", "simpleOrderQty":null,"orderQty":1,"price":1134.37,"displayQty":null,
    "stopPx":null,"pegOffsetValue":null,"pegPriceType":"","currency":"USD","settlCurrency":"XBt",
    "execType":"Trade","ordType":"Limit","timeInForce":"ImmediateOrCancel","execInst":"",
    "contingencyType":"","exDestination":"XBME","ordStatus":"Filled","triggered":"","workingIndicator":false,
    "ordRejReason":"","simpleLeavesQty":0,"leavesQty":0,"simpleCumQty":0.001,"cumQty":1,"avgPx":1134.37,
    "commission":0.00075,"tradePublishIndicator":"DoNotPublishTrade","multiLegReportingType":"SingleSecurity",
    "text":"Liquidation","trdMatchID":"7f4ab7f6-0006-3234-76f4-ae1385aad00f","execCost":88155,"execComm":66,
    "homeNotional":-0.00088155,"foreignNotional":1,"transactTime":"2017-04-04T22:07:46.035Z",
    "timestamp":"2017-04-04T22:07:46.035Z"
   }]}

# Then, the position enters 'Liquidated' state. Notice the 'currentQty' is still 1.
< {"table":"position",
   "action":"update",
   "data":[{
    "account":2,"symbol":"XBTUSD","currency":"XBt","currentQty":1,
    "markPrice":1136.88,"posState":"Liquidated","simpleQty":0.001,"liquidationPrice":1140.1,"bankruptPrice":1134.37,
    "timestamp":"2017-04-04T22:07:46.019Z"
   }]}

# Quickly thereafter, the position resets.
< {"table":"position",
   "action":"update",
   "data":[{
    "account":2,"symbol":"XBTUSD","currency":"XBt",
    "deleveragePercentile":null,"rebalancedPnl":1003,"prevRealisedPnl":-1003,"execSellQty":1,
    "execSellCost":88155,"execQty":0,"execCost":872,"execComm":131,"currentTimestamp":"2017-04-04T22:07:46.140Z",
    "currentQty":0,"currentCost":872,"currentComm":131,"realisedCost":872,"unrealisedCost":0,"grossExecCost":0,
    "isOpen":false,"markPrice":null,"markValue":0,"riskValue":0,"homeNotional":0,"foreignNotional":0,"posState":"",
    "posCost":0,"posCost2":0,"posInit":0,"posComm":0,"posMargin":0,"posMaint":0,"maintMargin":0,
    "realisedGrossPnl":-872,"realisedPnl":-1003,"unrealisedGrossPnl":0,"unrealisedPnl":0,
    "unrealisedPnlPcnt":0,"unrealisedRoePcnt":0,"simpleQty":0,"simpleCost":0,"simpleValue":0,
    "avgEntryPrice":null,"breakEvenPrice":null,"marginCallPrice":null,"liquidationPrice":null,"bankruptPrice":null,
    "timestamp":"2017-04-04T22:07:46.140Z"
   }]}

Deleverage

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

# First, the position updates to a 'posState' of 'Deleverage'.
< {"table":"position",
   "action":"update",
   "data":[{
    "account":2,"symbol":"XBTUSD","currency":"XBt","currentQty":2000,
    "markPrice":1160.72,"posState":"Deleverage","simpleQty":1.746,"liquidationPrice":1140.1,
    "timestamp":"2017-04-04T22:16:38.460Z"
   }]}

# Then, a 'Deleverage' execution is inserted. Notice the 'text'.
< {"table":"execution",
   "action":"insert",
   "data":[{
    "execID":"20ad1ff4-c110-a4f2-dd31-f94eaa0701fd",
    "orderID":"00000000-0000-0000-0000-000000000000","clOrdID":"","clOrdLinkID":"","account":2,"symbol":"XBTUSD",
    "side":"Sell","lastQty":2000,"lastPx":1160.72,"underlyingLastPx":null,"lastMkt":"XBME",
    "lastLiquidityInd":"AddedLiquidity","simpleOrderQty":null,"orderQty":2000,"price":1160.72,"displayQty":null,
    "stopPx":null,"pegOffsetValue":null,"pegPriceType":"","currency":"USD","settlCurrency":"XBt","execType":"Trade",
    "ordType":"Limit","timeInForce":"GoodTillCancel","execInst":"","contingencyType":"","exDestination":"XBME",
    "ordStatus":"Filled","triggered":"","workingIndicator":false,"ordRejReason":"",
    "simpleLeavesQty":0,"leavesQty":0,"simpleCumQty":1.746,"cumQty":2000,"avgPx":1160.72,"commission":-0.00025,
    "tradePublishIndicator":"PublishTrade","multiLegReportingType":"SingleSecurity","text":"Deleverage",
    "trdMatchID":"1e849b8a-7e88-3c67-a93f-cc654d40e8ba","execCost":172306000,"execComm":-43077,
    "homeNotional":-1.72306,"foreignNotional":2000,"transactTime":"2017-04-04T22:16:38.472Z",
    "timestamp":"2017-04-04T22:16:38.472Z"
   }]}

# Quickly thereafter, the position resets.
< {"table":"position",
   "action":"update",
   "data":[{
    "account":2,"symbol":"XBTUSD","currency":"XBt",
    "deleveragePercentile":null,"rebalancedPnl":-2171150,"prevRealisedPnl":2172153,"execSellQty":2001,
    "execSellCost":172394155,"execQty":0,"execCost":-2259128,"execComm":87978,
    "currentTimestamp":"2017-04-04T22:16:38.547Z","currentQty":0,"currentCost":-2259128,
    "currentComm":87978,"realisedCost":-2259128,"unrealisedCost":0,"grossExecCost":0,"isOpen":false,
    "markPrice":null,"markValue":0,"riskValue":0,"homeNotional":0,"foreignNotional":0,"posState":"","posCost":0,
    "posCost2":0,"posInit":0,"posComm":0,"posMargin":0,"posMaint":0,"maintMargin":0,"realisedGrossPnl":2259128,
    "realisedPnl":2171150,"unrealisedGrossPnl":0,"unrealisedPnl":0,"unrealisedPnlPcnt":0,"unrealisedRoePcnt":0,
    "simpleQty":0,"simpleCost":0,"simpleValue":0,"simplePnl":0,"simplePnlPcnt":0,
    "avgEntryPrice":null,"breakEvenPrice":null,"marginCallPrice":null,"liquidationPrice":null,"bankruptPrice":null,
    "timestamp":"2017-04-04T22:16:38.547Z"
   }]}

OrderBookL2

A special note on the orderBookL2 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 orderBookL2 update, it may look like this:

{"table":"orderBookL2","action":"update","data":[{"symbol":"XBTUSD","id":8798952400,"side":"Sell","size":8003}]}

Notice that this does not include the price, 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 ids you’ve seen to their price. When you receive an update or delete, look up the price in this map. This is simple but will consume some memory.
2. Use the following formula to reverse-engineer the ID:

ID = (100000000 * symbolIdx) - (price / instrumentTickSize)
price = ((100000000 * symbolIdx) - ID) * instrumentTickSize

Definitions:

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

This can be written as:

// This is a compatibility change as the tick sizes of live instruments changed in-flight. If you are listing
// these instruments, you must use their original tick as part of your calculations. If not, this can be ignored,
// and you can use `instrument.tickSize` directly.
const LEGACY_TICKS = {XBTUSD: 0.01};
function instrumentTickSize(instrument) {
  return legacyTicks[instrument.symbol] || instrument.tickSize;
}

// You should have a copy of the full instruments list on startup.
// Fetch from: https://www.bitmex.com/api/v1/instrument?columns=symbol,tickSize&start=0&count=500
const instrumentsList = fetchInstrumentsFromBitMEX();
function getInstrumentAndIdx(symbol) {
  const instrument = instrumentsList.find((i) => i.symbol === symbol);
  const instrumentIdx = instrumentsList.indexOf(instrument);
  return [instrument, instrumentIdx];
}

// To get a price from an ID:
export function priceFromID(id, symbol) {
  const [instrument, instrumentIdx] = getInstrumentAndIdx(symbol);
  return (100000000 * instrumentIdx - id) * instrumentTickSize(instrument);
}

// And reversed:
export function IDFromPrice(price, symbol) {
  const [instrument, instrumentIdx] = getInstrumentAndIdx(symbol);
  return 100000000 * instrumentIdx - price / instrumentTickSize(instrument);
}

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

price = ((1e8 * symbolIdx) - ID) * instrumentTickSize
10476 = ((100000000 * 88) - 8798952400) * 0.01

---

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 /realtimemd (that’s “realtime-mux-demux”) for multiplexing capabilities.

The protocol is very simple:

Packet Format:

[<type>,<id>,<topic>,<payload>]

Definitions:

• type: See “Packet Types” below.
• id: Client-selected unique ID for this stream. This can be arbitrary; consider using a unique identifier like userID.
• topic: 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 id and topic. Unsubscribing is done via id.
• payload: For MESSAGE types, the payload is exactly equal to any message one would send via a non-multiplexed stream.

Packet Types:

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

Example

Outgoing messages are prefixed with >. Incoming messages are prefixed with <.

# Create stream with an id of `hudsyg1q5dda4`, topic of `user_1`
> [1, "hudsyg1q5dda4", "user_1"]
# A welcome message greets you.
< [0, "hudsyg1q5dda4", "user_1",{"info":"Welcome to the BitMEX Realtime API.",...}]

# The stream is created! The stream acts exactly like any other WS connection, just framed with type and id.

# Authenticate inside that stream - see `authentication` above
> [0, "hudsyg1q5dda4", "user_1", {"op": "authKeyExpires", "args": ["pV1CPhfZWUlZM93v..."]}]
< [0, "hudsyg1q5dda4", "user_1", {"success":true}]

# Subscribe to a private table.
> [0, "hudsyg1q5dda4", "user_1", {"subscribe": "position"}]
# One message confirms the subscription,
< [0, "hudsyg1q5dda4", "user_1", {"success":true,"subscribe":"position","request":{"subscribe":"position"}}]
# And another sends the first partial.
< [0, "hudsyg1q5dda4", "user_1", {"table":"position","action":"partial","keys":["account","symbol", ...]}]

# Data will flow from here on out.

# To close a stream:
> [2, "hudsyg1q5dda4", "user_1"]
# A confirmation echo is sent from the server.
< [2, "hudsyg1q5dda4", "user_1"]