WS_request

The description of request and subscription

1. Access to the url

• Bibox market request url: wss://push.bibox.com/

Rate Limiting Policy: To improve data concurrent processing performance, a Websocket connection allows up to 20 channel subscriptions. If you need a large number of subscriptions, you can create multiple Websocket connections.

2. Data compression

All data returned by WebSocket API are compressed by GZIP, which will be decompressed after client receiving the data. Pako is suggested. (【pako】 is a library supports compression and decompression)

Note: Server performs a BASE64 encoding of compressed data, Client decodes BASE64 before decompression.

Decompression Example (nodejs)

let data = msg.data; // from Server
let text = pako.inflate(Buffer.from(data, 'base64'), {
    to: 'string'
});

let recvMsg = JSON.parse(text); // raw data

3. WebSocket Library

【ws】 is a WebSocket library under Node.js.

4. Ping message

WebSocket API supports double side messages, both server and client can start ping message, pong message will be returned.

WebSocket Server send ping message:

{"ping": 1536743613834}

WebSocket Client will be returned:

 {"pong": 1536743613834}

Note: the value of "pong" is the value of "ping" in data returned.

Note: After WebSocket Client and WebSocket Server connect, WenSocket Server will send a "ping" message to WebSocket Client every 10s (the frequency can be changed), if 2 ping messages are ignored by WebSocket Client. WebSocket Server will disconnect proactively.

┌────────┐                         ┌────────┐ 
│ Client │                         │ Server │
└───┬────┘                         └───┬────┘
    │         {"ping": 1536743613834}  │
    │<─────────────────────────────────┤
    │                                  │ wait 10s
    │                                  ├───┐
    │                                  │<──┘
    │         {"ping": 1536743613834}  │
    │<─────────────────────────────────┤
    │                                  │
    │ {"pong": 1536743613834}          │
    ├┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄>│
    │                                  │

Note: WebSocket Server will keep connecting if WebSocket Client send at least one of the two pings it received nearest.

┌────────┐                         ┌────────┐ 
│ Client │                         │ Server │
└───┬────┘                         └───┬────┘
    │         {"ping": 1523778470416}  │
    │<─────────────────────────────────┤
    │                                  │ wait 10s
    │                                  ├───┐
    │                                  │<──┘
    │         {"ping": 1523778475416}  │
    │<─────────────────────────────────┤
    │                                  │ wait 10s
    │                                  ├───┐
    │                                  │<──┘
    │                                  │
    │                                  │ close WebSocket connection
    │                                  ├───┐
    │                                  │<──┘
    │                                  │

Note: WebSocket Server will disconnect proactively after WebSocket Client ignores 2 ping messages.

WebSocket Client sends ping message:

{"ping": 1536743614839}

WebSocket Server will return:

{"pong": 1536743614839}

Note: the value of "pong" is the value of "ping" in data returned.

Note: if client don’t receive "pong" message after it sends N "ping" messages (N is set by client), then client needs to disconnect WebSocket, and reconnect.

Note: If the client disconnects frequently, then please check the reply function of client and make sure the correct "pong" response to server.

5. Channel Format

Use channel to Subcribe data, the grammar is as follows

Channel Type	Channel Format	Description
Kline	bibox_sub_spot_$pair_kline_$period	K line data, including the opening price, the highest price, the lowest price, the closing price, the trading volume in unit time interval, $period is Optional values: { 1min, 5min, 15min, 30min, 1hour, 2hour, 4hour, 6hour, 12hour, day, week }
Market	bibox_sub_spot_ALL_ALL_market	market information, including the information of lastest price, the highest price in 24h, the lowest price in 24h, the trading volume in 24h of all trading pairs
Depth	bibox_sub_spot_$pair_depth	the depth of handicap, return the lastest 200 pieces of information about trading depth
Ticker	bibox_sub_spot_$pair_ticker	Ticker，return the information of lastest price, the lowest ask price and volume, the highest bid pirce and volume of specific trading pairs
Deals	bibox_sub_spot_$pair_deals	trading records, including the information of trading price, trading volume, trading sides

• $pair a trading pair, must be capitalized，optional values: { BIX_BTC, BIX_ETH, BTC_USDT, ETH_USDT...... }

6. Subscribe(addChannel)

Subscribe(addChannel) and step of receiving data

┌────────┐                         ┌────────┐ 
│ Client │                         │ Server │
└───┬────┘                         └───┬────┘
    │ {"event": "addChannel",          |
    |  "channel": "xxx channel"}       │
    ├─────────────────────────────────>│
    |                                  | 
    │       {"channel": "xxx channel", | 
    |        "data": "data of channel"}│
    │<┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤
    |                                  | 
    │       {"channel": "xxx channel", | 
    |        "data": "data of channel"}│
    │<┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤
    |                                  | 
    │       {"channel": "xxx channel", | 
    |        "data": "data of channel"}│
    │<┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤
    │                                  │

Note: After subscribing channel successfully, server will send the new corresponding data to client at a certain frequency when the corresponding data of channel updates.

Subscribe Format

After buliding the connection with WebSocket API, sending the data with the following format to server to subscribe data

{
  "event": "addChannel",
  "channel": "channel to sub"
}

the correct subcribe

{
  "event": "addChannel",
  "channel": "bibox_sub_spot_BIX_BTC_kline_1min"
}

• "channel" is channel format ，refer to channel format at "5. Channel Format".

The example of subscribing success return data

[{
  "channel": "bibox_sub_spot_BIX_BTC_kline_1min",
  "data_type": 0, //Subscribe one time of returning total value sucessfully, then return increment value 
  "data": 
  [
      {
          "time":1536310020000,
          "open":"0.00006614",
          "high":"0.00006659",
          "low":"0.00006604",
          "close":"0.00006652",
          "vol":"74056.89597166"
      },
      {
          "time":1536310080000,
          "open":"0.00006652",
          "high":"0.00006652",
          "low":"0.00006652",
          "close":"0.00006652",
          "vol":"100"
      }
  ]
}]

• "data_type" The type of data marked to be returned , 0-return total value, 1-return incremental value

data description

  "data": {
    "time": the starting time of K line period,
    "open": the openging price,
    "high": The highest price,
    "low": the lowest price,
    "close": the closing price
    "vol":  trading volume
  }

Client will receive the incremental data as long as Kline updates, for example

[{
  "channel": "bibox_sub_spot_BIX_BTC_kline_1min",
  "data_type": 1, 
  "data": 
  [
      {
          "time":1536310020000,
          "open":"0.00006614",
          "high":"0.00006659",
          "low":"0.00006604",
          "close":"0.00006652",
          "vol":"74056.89597166"
      },
      {
          "time":1536310080000,
          "open":"0.00006652",
          "high":"0.00006652",
          "low":"0.00006652",
          "close":"0.00006652",
          "vol":"100"
      }
  ]
}]

Note: 2 closest k lines will be returned every time, when incremental value k line be returned

example of subscribing wrongly

subscribe wrongly (wrong pair, capitalized sensitively)

{
  "event": "addChannel",
  "channel": "bibox_sub_spot_bix_btc_kline_1min"
}

The example of subscribing wrongly return data

{
  "channel": "bibox_sub_spot_bix_btc_kline_1min",
  "error": 
  {
       "code": "3009",
       "msg":"推送订阅channel不合法"
  }
}

7. Unsubscribe(removeChannel)

Unsubscribe Format

WebSocket Client can cancel the subscription, WebSocket Server will not send the data of this channel after the cancellation. The format of cancellation is as follows

{
  "event": "removeChannel",
  "channel": "xxx channel"
}

the correct unsubcribe channel

{
  "event": "removeChannel",
  "channel": "bibox_sub_spot_BIX_BTC_kline_1min"
}