Potentially-Breaking API Update to ID Generation on WebSocket Orderbook Feeds

BitMEX

On 26 June and 10 July 2023, we will be making a change to our WebSocket API to accommodate future platform upgrades. 

What’s Changing?

  • The ID in orderBookL2 and orderBookL2_25 rows are now arbitrary and will no longer be translatable to a price level.
    • To compensate, price is now provided on all insert, update and delete messages.
    • This means the book can no longer be sorted by ID. Use price for sorting.

Am I Affected?

This is a mandatory API change for clients relying on the previous ID implementation to source prices. If your application does not reverse-engineer the ID generation to generate a price, no change is likely needed to your application. 

What Should I Change?

If your application is affected, simply use the price as it is provided on “update” messages, and sort your book by price.

Example Messages

Old Implementation

{
    “table”: “orderBookL2”,
    “action”: “insert”,
    “data”: [{“symbol”: “XBTUSD”, “id”: 8797309800, “side”: “Buy”, “size”: 32800, “price”: 26902, “timestamp”: “2023-05-19T08:51:43.911Z”}] }
{
    “table”: “orderBookL2”,
    “action”: “update”,
    “data”: [{“symbol”: “XBTUSD”, “id”: 8797309800, “side”: “Buy”, “size”: 42800, “price”: 26902, “timestamp”: “2023-05-19T08:51:44.911Z”}] }

  • On an update you were able to calculate the price from id:8797309800 -> 26902.0, or one could look it up from the previous “insert” message.
  • Since April 2023, the price is provided on every “update” message. 
{
    “table”: “orderBookL2”,
    “action”: “delete”,
    “data”: [{“symbol”: “XBTUSD”, “id”: 8797309800, “side”: “Buy”, “price”: 26902, “timestamp”: “2023-05-19T08:51:45.911Z”}] }

New Implementation

{
    “table”: “orderBookL2”,
    “action”: “insert”,
    “data”: [{“symbol”: “XBTUSD”, “id”: 8798309800, “side”: “Buy”, “size”: 32800, “price”: 26902, “timestamp”: “2023-05-19T08:51:43.911Z”}] }
{
    “table”: “orderBookL2”,
    “action”: “update”,
    “data”: [{“symbol”: “XBTUSD”, “id”: 8798309800, “side”: “Buy”, “size”: 42800, “price”: 26902, “timestamp”: “2023-05-19T08:51:44.911Z”}] }

  • The id: 8798309800 will no longer map to the price of 26902.0, instead users should use price. 
{
    “table”: “orderBookL2”,
    “action”: “delete”,
    “data”: [{“symbol”: “XBTUSD”, “id”: 8798309800, “side”: “Buy”, “price”: 26902, “timestamp”: “2023-05-19T08:51:45.911Z”}] }

Why?

Changing the ID generation algorithm allows more backend flexibility for future exchange upgrades. Additionally, the old mechanism for backdooring a price from an orderbook ID was clunky and complicated for end users. This change allows traders to have a simpler way of getting orderbook prices when parsing slices of streams.    

Deployment Schedule

This API change affecting the IDs will be implemented in the Testnet and Production environments on the following schedule:

  • 25 May: Testnet (testnet.bitmex.com) – All symbols
  • 26 Jun: Production (www.bitmex.com) – The following instruments only:
    DOTUSDT, USDTUSDC, SUIUSD, AXSUSD, XBTU23, SOL_USDT, GMXUSDT, ETHUSD_ETH, AVAXUSD, APTUSD, TRX_USDT, XBTZ23, XBTUSDTM23, ETHUSDM23, ETHM23, NEARUSD, BLURUSDT, EOSUSD, BLURUSD, MATIC_USDT, CROUSD, XBTUSDTU23, AVAXUSDT, BMEXUSD, FLRUSD, ADAM23, GMTUSDT, LUNAUSD, FLOKIUSDT, LINK_USDT, GMTUSD, ARBUSD, ARBUSDTM23, 1TAIDOGEUSDT, UNI_USDT, AXS_USDT, APE_USDT
  • 10 July: Production – All remaining symbols, including the most popular instruments like XBTUSD or ETHUSD.

All customers can begin migrating today and do not need to wait. A price is already explicitly provided on all insert and updates.

To be the first to know about our contracts, new listings, product launches, giveaways, and other updates, you can connect with us on Discord, Telegram, and Twitter. We encourage you to also check our blog regularly. 

In the meantime, if you have any questions please contact Support.