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

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

25 May 2023

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 inorderBookL2andorderBookL2_25rows are now arbitrary and will no longer be translatable to a price level.
- To compensate,priceis now provided on all insert, update and delete messages.
- This means the book can no longer be sorted by ID. Usepricefor 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 thepriceas it is provided on “update” messages, and sort your book byprice.

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"}]}[Content]

{"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"}]}[Content]

{"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 likeXBTUSDorETHUSD.

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.