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