Websocket 请求与订阅示例

Posted 2020-11-02 ゛竹先森゜

1. 访问地址

• Pro 站行情请求地址为：wss://api.huobipro.com/ws
• HADAX 站行情请求地址为：wss://api.hadax.com/ws

 

2. 数据压缩

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

 

3. WebSocket库

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

 

4. 心跳

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

WebSocket Server 发送心跳：

{"ping": 18212558000}

WebSocket Client 应该返回：

 {"pong": 18212558000}

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

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

例如

WebSocket Client 发送心跳：

{"ping": 18212553000}

注：发送的 message 里面，"ping" 的值必须为 Long 类型，否则返回错误信息：

{
  "ts": 1492420473027,
  "status": "error",
  "err-code": "bad-request",
  "err-msg": "invalid ping"
}

 

WebSocket Server 会返回：

{"pong": 18212553000}

 

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

 

5. topic格式

订阅数据和请求数据都要使用topic，topic的语法如下：

topic 类型	topic 语法	描述
KLine	market.$symbol.kline.$period	$period 可选值：{ 1min, 5min, 15min, 30min, 60min, 1day, 1mon, 1week, 1year }
Market Depth	market.$symbol.depth.$type	$type 可选值：{ step0, step1, step2, step3, step4, step5 } （合并深度0-5）；step0时，不合并深度
Trade Detail	market.$symbol.trade.detail
Market Detail	market.$symbol.detail

• $symble是币种，可选值： { ethbtc, ltcbtc, etcbtc, bchbtc...... }
• 用户选择“合并深度”时，一定报价精度内的市场挂单将予以合并显示。合并深度仅改变显示方式，不改变实际成交价格。

 

6. 请求数据(req/rep)

请求数据，仅返回一次数据

请求数据的格式

{
  "req": "topic to req",
  "id": "id generate by client"
}

• ‘req‘的值为 topic 格式

正确请求数据的例子

{
  "req": "market.btcusdt.kline.1min",
  "id": "id10"
}

返回数据的例子：

{
  "status": "ok",
  "rep": "market.btcusdt.kline.1min",
  "tick": [
    {
      "amount": 1.6206,
      "count":  3,
      "id":     1494465840,
      "open":   9887.00,
      "close":  9885.00,
      "low":    9885.00,
      "high":   9887.00,
      "vol":    16021.632026
    },
    {
      "amount": 2.2124,
      "count":  6,
      "id":     1494465900,
      "open":   9885.00,
      "close":  9880.00,
      "low":    9880.00,
      "high":   9885.00,
      "vol":    21859.023500
    }
  ]
}

 

错误请求数据的例子

{
  "req": "market.invalidsymbo.kline.1min",
  "id": "id10"
}

 

返回的错误信息的例子：

{
  "status": "error",
  "id": "id10",
  "err-code": "bad-request",
  "err-msg": "invalid topic market.invalidsymbol.trade.detail",
  "ts": 1494483996521
}

 

7. 订阅数据(sub/pub)

订阅数据的格式

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

{
  "sub": "topic to sub",
  "id": "id generate by client"
}

 

正确订阅的例子

正确订阅：

{
  "sub": "market.btcusdt.kline.1min",
  "id": "id1"
}

• "sub"值为 topic 格式

订阅成功返回数据的例子：

{
  "id": "id1",
  "status": "ok",
  "subbed": "market.btcusdt.kline.1min",
  "ts": 1489474081631
}

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

{
  "ch": "market.btcusdt.kline.1min",
  "ts": 1489474082831,
  "tick": {
    "id": 1489464480,
    "amount": 0.0,
    "count": 0,
    "open": 7962.62,
    "close": 7962.62,
    "low": 7962.62,
    "high": 7962.62,
    "vol": 0.0
  }
}

tick 说明:

  "tick": {
    "id": K线id,
    "amount": 成交量,
    "count": 成交笔数,
    "open": 开盘价,
    "close": 收盘价,当K线为最晚的一根时，是最新成交价
    "low": 最低价,
    "high": 最高价,
    "vol": 成交额, 即 sum(每一笔成交价 * 该笔的成交量)
  }

 

错误订阅的例子

错误订阅（错误的 symbol）：

{
  "sub": "market.invalidsymbol.kline.1min",
  "id": "id2"
}

订阅失败返回数据的例子：

{
  "id": "id2",
  "status": "error",
  "err-code": "bad-request",
  "err-msg": "invalid topic market.invalidsymbol.kline.1min",
  "ts": 1494301904959
}

错误订阅（错误的 topic）：

{
  "sub": "market.btcusdt.kline.3min",
  "id": "id3"
}

 

订阅失败返回数据的例子：

{
  "id": "id3",
  "status": "error",
  "err-code": "bad-request",
  "err-msg": "invalid topic market.btcusdt.kline.3min",
  "ts": 1494310283622
}

 

8. 取消订阅(unsub)

取消订阅的格式

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

{
  "unsub": "topic to unsub",
  "id": "id generate by client"
}

 

正确取消订阅的例子：

{
  "unsub": "market.btcusdt.trade.detail",
  "id": "id4"
}

 

取消订阅成功返回信息的例子：

{
  "id": "id4",
  "status": "ok",
  "unsubbed": "market.btcusdt.trade.detail",
  "ts" 1494326028889
}

 

错误取消订阅的例子

错误取消订阅的例子（取消订阅一个尚未订阅的 topic）：

{
  "unsub": "market.btcusdt.trade.detail",
  "id": "id5"
}

 

返回的错误信息的例子

{
  "id": "id5",
  "status": "error",
  "err-code": "bad-request",
  "err-msg": "unsub with not subbed topic market.btcusdt.trade.detail",
  "ts": 1494326217428
}

 

错误取消订阅的例子（取消订阅一个不存在的 topic）：

{
  "unsub": "not-exists-topic",
  "id": "id5"
}

 

返回的错误信息的例子：

{
  "id": "id5",
  "status": "error",
  "err-code": "bad-request",
  "err-msg": "unsub with not subbed topic not-exists-topic",
  "ts": 1494326318809
}