火币网API文档——Websocket 请求与订阅示例

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
}