WebSocket API 说明

WebSocket API简介

WebSocket协议是基于TCP的一种新的网络协议。它实现了客户端与服务器之间在单个 tcp 连接上的全双工通信，由服务器主动发送信息给客户端，减少了频繁的身份验证等不必要的开销。其最大优点有两个：

• 两方请求的 header 数据很小，大概只有2 Bytes。
• 服务器不再是被动的接到客户端的请求后才返回数据，而是有了新数据后主动推送给客户端。

以上 WebSocket 协议带来的优点使得其十分适用于数字货币行情和交易这种实时性强的接口。

注意：WebSocket 目前只支持行情查询，交易接口将在后续提供。

访问地址

Bibox行情请求地址：wss://push.bibox.com/

请求与订阅说明

1. 访问地址

• Bibox行情请求地址：wss://push.bibox.com/

限速策略：为提高数据并发处理性能，一个Websocket连接允许最多20个channel订阅，如果您有大量订阅的需求，可以创建多个Websocket连接。

2. 数据压缩

WebSocket API 返回的所有数据都进行了 GZIP 压缩，需要 client 在收到数据之后解压，推荐使用pako。（【pako】 是一个支持压缩和解压 GZIP 的库）

注：Server对压缩的数据进行一次BASE64编码，Client解压前需要先解码BASE64.

解压缩例子 (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库

【ws】 是 Node.js 下的 WebSocket 库。

4. 心跳

WebSocket API 支持双向心跳，无论是 Server 还是 Client 都可以发起 ping message，对方返回 pong message。

WebSocket Server 发送心跳：

{"ping": 1536743613834}

WebSocket Client 会返回：

 {"pong": 1536743613834}

注：返回的数据里 "pong" 的值为收到的 "ping" 的值

注：WebSocket Client 和 WebSocket Server 建立连接之后，WebSocket Server 每隔 10s（这个频率可能会变化）会向 WebSocket Client 发起一次心跳，WebSocket Client 忽略心跳2次后，WebSocket Server 将会主动断开连接。

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

注：WebSocket Client 发送最近2次心跳 message 中的其中一个 "ping" 的值，WebSocket Server 都会保持 WebSocket 连接

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

注：WebSocket Client 忽略心跳2次后，WebSocket Server 将会主动断开连接。

WebSocket Client 发送心跳：

{"ping": 1536743614839}

WebSocket Server 会返回：

{"pong": 1536743614839}

注：返回的数据里面的 "pong" 的值为收到的 "ping" 的值

注：如果Client发送 ping message n次（n由Client自定义）都没有收到 pong message，Client需要断开 Websocket，重新连接。

注：如果Client连接频繁被Server断开，请检查Client是否回复pong message，确保Client能正常回应Server发起的ping message。

5. channel格式

订阅数据使用 channel，语法如下

• $pair 为交易对，必须大写，可选值： { BIX_BTC, BIX_ETH, BTC_USDT, ETH_USDT...... }

6. 订阅数据(addChannel)

订阅数据(addChannel)以及接收订阅数据的大致流程

┌────────┐                         ┌────────┐ 
│ 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"}│
    │<┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤
    │                                  │

注：订阅 channel 成功之后，当 channel 对应的数据有更新时，Server 按一定的频率把 channel 对应的新数据推送给 Client

订阅数据的格式

成功建立和 WebSocket API 的连接之后，向 Server 发送如下格式的数据来订阅数据

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

正确订阅的例子

正确订阅

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

• "channel" 的值为 channel ，请参考 "5. channel格式" 的 channel 格式

订阅成功返回数据的例子

[{
  "channel": "bibox_sub_spot_BIX_BTC_kline_1min",
  "data_type": 0, //订阅成功返回一次全量数据，之后返回增量 
  "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" 标识返回的数据是全量还是增量，0-返回全量数据，1-返回增量数据

data 说明

  "data": {
    "time": k线某周期开始时间,
    "count": 成交笔数,
    "open": 开盘价,
    "high": 最高价,
    "low": 最低价,
    "close": 收盘价
    "vol": 成交量
  }

之后每当 Kline 有更新时，client 会收到数据，例子

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

注：返回增量k线时，每次都返回最新相邻两条kline

错误订阅的例子

错误订阅（错误的 pair，大小写敏感）

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

订阅失败返回数据的例子

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

7. 取消订阅(removeChannel)

取消订阅的格式

WebSocket Client 订阅数据之后，可以取消订阅，取消订阅之后 WebSocket Server 将不会再发送该 channel 的数据，取消订阅的格式如下

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

正确取消订阅的例子

正确取消订阅的例子

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