火幣網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
}