Upcoming Updates to Our WebSocket and REST APIs

We are making some important changes to our WebSocket and REST APIs, of which you will find detailed below.  All changes will be available in Testnet from 15 December 2022 at 04:00 UTC and in Production from  16 January 2023 at 04:00 UTC.

  1. The Separation of  Trading vs. Non-trading Related Data
  2. Depreciation of Fields
  3. Removal of JSON Nulls

Further detail on all these changes has been supplied,  however,  if you have any questions before these changes come into effect, please contact Support.

 

We are introducing separate endpoints for trading vs non-trading related data. The new endpoint will be /realtimePlatform and will support the following topics:

  • announcement
  • chat
  • publicNotifications

The existing websocket will continue to support these topics for a grace period of eight  weeks. Any integrations relying on these topics need to be migrated before then; after which attempting to subscribe to these topics on the primary /realtime will not work.


B) Depreciation of Fields

REST API Websocket Topic Removing Fields
GET /user/wallet wallet
  • prevDeposited
  • prevWithdrawn
  • prevTransferIn
  • prevTransferOut
  • prevAmount
  • prevTimestamp
  • deltaDeposited
  • deltaWithdrawn
  • deltaTransferIn
  • deltaTransferOut
  • deltaAmount
GET /user/margin margin
  • prevState
  • action
  • pendingCredit (use wallet)
  • pendingDebit (use wallet)
  • confirmedDebit (use wallet)
  • prevUnrealisedPnl
  • taxableMargin
  • sessionMargin
  • varMargin
  • indicativeTax
  • unrealisedProfit
  • syntheticMargin
  • marginBalancePcnt
  • excessMarginPcnt
GET /position position
  • prevClosePrice
  • openingTimestamp
  • openingCost
  • openingComm
  • execBuyQty
  • execBuyCost
  • execSellQty
  • execSellCost
  • execQty
  • execCost
  • execComm
  • currentTimestamp
  • grossOpenCost
  • grossExecCost
  • posCost2
  • posInit
  • posAllowance
  • taxableMargin
  • sessionMargin
  • targetExcessMargin
  • varMargin
  • realisedGrossPnl
  • realisedTax
  • unrealisedGrossPnl
  • longBankrupt
  • shortBankrupt
  • taxBase
  • indicativeTaxRate
  • indicativeTax
  • unrealisedTax
  • simpleQty
  • simpleCost
  • simpleValue
  • simplePnl
  • simplePnlPcnt
  • avgCostPrice
  • lastPrice (use instrument)
  • lastValue (use instrument)
GET /order order
  • simpleOrderQty
  • exDestination
  • simpleLeavesQty
  • simpleCumQty
  • multiLegReportingType
GET /execution

GET /execution/tradeHistory

execution
  • underlyingLastPx
  • lastMkt
  • simpleOrderQty
  • exDestination
  • simpleLeavesQty
  • simpleCumQty
  • multiLegReportingType
GET /instrument instrument
  • inverseLeg
  • sellLeg
  • buyLeg
  • optionStrikePcnt
  • optionStrikeRound
  • optionStrikePrice
  • optionMultiplier
  • capped
  • insuranceFee
  • openingTimestamp
  • closingTimestamp
  • sessionInterval
  • bankruptLimitDownPrice
  • bankruptLimitUpPrice
  • prevTotalVolume
  • indicativeTaxRate
  • optionUnderlyingPrice
n.a. account
  • makerFeeDiscount
  • takerFeeDiscount
  • insuranceFeeDiscount
  • timeoutTimestamp

 

C) Removal of JSON Nulls

On the WebSocket feed, for partial messages or topics using full width messages, we will no longer send JSON null or null equivalent values.

Existing format: New format:
{

“orderID”: “98347341-1c8b-452f-96df-821c9f9a2998”,

“clOrdID”: “”,

“clOrdLinkID”: “”,

“account”: 102340,

“symbol”: “XBT_USDT”,

“side”: “Buy”,

“orderQty”: 10000,

“price”: 17013,

“pegPriceType”: “”,

“currency”: “USDT”,

“settlCurrency”: “”,

“ordType”: “Market”,

“timeInForce”: “ImmediateOrCancel”,

“execInst”: “”,

“contingencyType”: “”,

“exDestination”: “XBME”,

“ordStatus”: “New”,

“triggered”: “”,

“workingIndicator”: true,

“ordRejReason”: “”,

“leavesQty”: 10000,

“cumQty”: 0,

“multiLegReportingType”: “SingleSecurity”,

“text”: “Submission from devhk.bitmex.com”,

“transactTime”: “2022-12-06T04:48:22.357Z”,

“timestamp”: “2022-12-06T04:48:22.357Z”,

“lastLiquidityInd”: “”,

“tradePublishIndicator”: “”,

“trdMatchID”: “00000000-0000-0000-0000-000000000000”,

“execID”: “c135466c-dbb3-07ce-3325-f2ad56c37aec”,

“execType”: “New”,

“lastMkt”: “”

}

 {

“execID”: “c135466c-dbb3-07ce-3325-f2ad56c37aec”,

“orderID”: “98347341-1c8b-452f-96df-821c9f9a2998”,

“account”: 102340,

“symbol”: “XBT_USDT”,

“side”: “Buy”,

“orderQty”: 10000,

“price”: 17013.0,

“currency”: “USDT”,

“execType”: “New”,

“ordType”: “Market”,

“timeInForce”: “ImmediateOrCancel”,

“execInst”: “”,

“exDestination”: “XBME”,

“ordStatus”: “New”,

“workingIndicator”: true,

“leavesQty”: 10000,

“cumQty”: 0,

“multiLegReportingType”: “SingleSecurity”,

“text”: “Submission from devhk.bitmex.com”,

“transactTime”: “2022-12-06T04:48:22.357Z”,

“timestamp”: “2022-12-06T04:48:22.357Z”

}

 

Examples of JSON null equivalents:

JSON Data Type Null Equivalent
string “”
timestamp “2000-01-01T00:00:00.000Z”
duration “2000-01-01T00:00:00.000Z”
uuid “00000000-0000-0000-0000-000000000000”

 

Implementations should ensure that appropriate defaults are used, if presence of a null field in the JSON message is required.

If you have any questions about these upcoming changes, please contact Support.