WebSocket API description

WebSocket API Introduction

WebSocket protocol is a new TCP-based network protocol. It enables the full-duplex communication of single TCP connection between client and server, the server sends singals to clients actively, which reduces the unnecessary expenses on frequent identity verifications. The greatest two advantages:

• The header data requested by double sides are small, which is about only 2 Bytes.
• Server will not return data passively after receiving the request of clients any more, it will send the new data to clients actively.

The advantages of the above WebSocket protocol is very appropriate for cryptocurrencies market and trading real-time interface.

Attention: WebSocket only supports market viewing, trading interface will be provided later.

Access to the url

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

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

• $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"
}