Skip to main content

Depth Channel

Description

Channel

Use books for snapshot data, book1 for 1 depth level, book5 for 5 depth levels, book15 for 15 depth levels.
Default data push frequency is 150ms
Default data push frequency for books1:100ms

  • books: Push the full snapshot data for the first time, push update afterwards, that is, if there is a change in depth, the depth data that has changed will be pushed.
  • books1: 1 depth level will be pushed every time(snapshot).
  • books5: 5 depth levels will be pushed every time(snapshot).
  • books15: 15 depth levels will be pushed every time(snapshot).

Checksum

Calculate Checksum
1. More than 25 levels of bid and ask
A local snapshot of market depth (only 2 levels of the orderbook are shown here, while 25 levels of orderbook should actually be intercepted):
"bids": [
[ 43231.1, 4 ], //bid1
[ 43231, 6 ] //bid2
]
"asks": [
[ 43232.8, 9 ], //ask1
[ 43232.9, 8 ] //ask2
]
Build the string to check CRC32:
"43231.1:4:43232.8:9:43231:6:43232.9:8"
The sequence:
"bid1[price:amount]:ask1[price:amount]:bid2[price:amount]:ask2[price:amount]"

2. Less than 25 levels of bid or ask
A local snapshot of market depth:
"bids": [
[ 3366.1, 7 ] //bid1
]
"asks": [
[ 3366.8, 9 ], //ask1
[ 3368 , 8 ], //ask2
[ 3372 , 8 ] //ask3
]

Build the string to check CRC32:
"3366.1:7:3366.8:9:3368:8:3372:8"
The sequence:
"bid1[price:amount]:ask1[price:amount]:ask2[price:amount]:ask3[price:amount]"

This mechanism can assist users in checking the accuracy of depth(order book) data.

Merging update data into snapshot

After subscribe to the channel (such as books 400 levels) of Order book , user first receive the initial snapshot of market depth. Afterwards the incremental update is subsequently received, user are responsible to update the snapshot from client side.

  1. If there are any levels with same price from the updates, compare the amount with the snapshot order book:

    If the amount is 0, delete this depth data.

    If the amount changes, replace the depth data.

  2. If there is no level in the snapshot with same price from the update, insert the update depth information into the snapshot sort by price (bid in descending order, ask in ascending order).

Calculate Checksum

Use the first 25 bids and asks in the local snapshot to build a string (where a colon connects the price and amount in an ask or a bid), and then calculate the CRC32 value (32-bit signed integer).

  1. When the bid and ask depth data exceeds 25 levels, each of them will intercept 25 levels of data, and the string to be checked is queued in a way that the bid and ask depth data are alternately arranged. Such as: bid1[price:amount]:ask1[price:amount]:bid2[price:amount]:ask2[price:amount]...
  2. When the bid or ask depth data is less than 25 levels, the missing depth data will be ignored. Such as: bid1[price:amount]:ask1[price:amount]:ask2[price:amount]:ask3[price:amount]...
  3. If price is '0.5000', DO NOT calculate the checksum by '0.5', please DO use the original value
Request Example
{
"op": "subscribe",
"args": [
{
"instType": "USDT-FUTURES",
"channel": "books5",
"instId": "BTCUSDT"
}
]
}

Request Parameters

ParameterTypeRequiredDescription
opStringYesOperation, subscribe unsubscribe
argsList<Object>YesList of channels to request subscription
> instTypeStringYesProduct type
USDT-FUTURES USDT professional futures
COIN-FUTURES Mixed futures
USDC-FUTURES USDC professional futures
SUSDT-FUTURES USDT professional futures demo
SCOIN-FUTURES Mixed futures demo
SUSDC-FUTURES USDC professional futures demo
> channelStringYesChannel name: books/books1/books5/books15
> instIdStringYesProduct ID
Response Example
{
"event": "subscribe",
"arg": {
"instType": "USDT-FUTURES",
"channel": "books5",
"instId": "BTCUSDT"
}
}

Response Parameters

ParameterTypeDescription
eventStringEvent,
argObjectSubscribed channels
> instTypeStringProduct type
USDT-FUTURES USDT professional futures
COIN-FUTURES Mixed futures
USDC-FUTURES USDC professional futures
SUSDT-FUTURES USDT professional futures demo
SCOIN-FUTURES Mixed futures demo
SUSDC-FUTURES USDC professional futures demo
> channelStringChannel name, books/books1/books5/books15
> instIdStringProduct ID, e.g. ETHUSDT
msgStringError message
codeStringError code, returned only on error
Push Data
{
"action": "snapshot",
"arg": {
"instType": "USDT-FUTURES",
"channel": "books5",
"instId": "BTCUSDT"
},
"data": [
{
"asks": [
[
"27000.5",
"8.760"
],
[
"27001.0",
"0.400"
]
],
"bids": [
[
"27000.0",
"2.710"
],
[
"26999.5",
"1.460"
]
],
"checksum": 0,
"ts": "1695716059516"
}
],
"ts": 1695716059516
}

Push Parameters

ParameterTypeDescription
argObjectChannels with successful subscription
> instTypeStringProduct type
USDT-FUTURES USDT professional futures
COIN-FUTURES Mixed futures
USDC-FUTURES USDC professional futures
SUSDT-FUTURES USDT professional futures demo
SCOIN-FUTURES Mixed futures demo
SUSDC-FUTURES USDC professional futures demo
> channelStringChannel name, books/books1/books5/books15
> instIdStringProduct ID
actionStringPush data action, Incremental push data or full volume push data
dataList<Object>Subscription data
> asksList<String>Seller depth
> bidsList<String>Buyer depth
> tsStringMilliseconds format of updated data timestamp Unix, e.g. 1597026383085
> checksumLongTesting and

How was your Reading Experience with us?