火幣Huobi API Websocket

本文轉載自查看原文 2018-11-08 18:11 5890 API

本文介紹火幣Huobi API Websocket

WebSocket API簡介

WebSocket協議是基於TCP的一種新的網絡協議。它實現了客戶端與服務器之間在單個 tcp 連接上的全雙工通信，由服務器主動發送信息給客戶端，減少了頻繁的身份驗證等不必要的開銷。其最大優點有兩個：

兩方請求的 header 數據很小，大概只有2 Bytes。
服務器不再是被動的接到客戶端的請求后才返回數據，而是有了新數據后主動推送給客戶端。

以上 WebSocket 協議帶來的優點使得其十分適用於數字貨幣行情和交易這種實時性強的接口。

WebSocket 只支持行情查詢、訂單和資產推送，交易接口將在后續提供。在使用中如果遇到問題，請加技術討論 QQ 群: 火幣網API交流群(7) 794370631，我們將盡力幫您答疑解惑（加群時請注明uid和編程語言）。

請求與訂閱說明

1. 訪問地址

注意：HADAX和Pro是兩個不同的交易站，所以行情信息也不一樣，請通過 Pro symbols 和 HADAX symbols 查詢相應的交易對信息

Pro 站行情請求地址為：wss://api.huobi.pro/ws
HADAX 站行情請求地址為：wss://api.hadax.com/ws
Pro 站和 HADAX 站資產和訂單推送統一服務地址為：wss://api.huobi.pro/ws/v1

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發送最近2次心跳message中的其中一個ping的值，WebSocket Server都會保持WebSocket連接。

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

注：WebSocket Client 發送最近2次心跳 message 中的其中一個 "ping" 的值，WebSocket Server 都會保持 WebSocket 連接

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

注：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" 的值

錯誤信息返回格式

{
  "id": "id generate by client",
  "status": "error",
  "err-code": "err-code",
  "err-msg": "err-message",
  "ts": 1487152091345
}

注：ts為錯誤信息生成的時間戳，單位：毫秒

5. topic格式

訂閱數據和請求數據都要使用 topic，topic 的語法如下：

topic 類型	topic 語法	sub/req	描述	是否需要驗簽
KLine	market.$symbol.kline.$period	sub/req	K線數據，包含單位時間區間的開盤價、收盤價、最高價、最低價、成交量、成交額、成交筆數等數據 $period 可選值：{ 1min, 5min, 15min, 30min, 60min, 4hour,1day, 1mon, 1week, 1year }	N
Market Depth	market.$symbol.depth.$type	sub/req	盤口深度，按照不同 step 聚合的買一、買二、買三等和賣一、賣二、賣三等數據 $type 可選值：{ step0, step1, step2, step3, step4, step5, percent10 } （合並深度0-5）；step0時，不合並深度	N
Trade Detail	market.$symbol.trade.detail	sub/req	成交記錄，包含成交價格、成交量、成交方向等信息	N
Market Detail	market.$symbol.detail	sub/req	最近24小時成交量、成交額、開盤價、收盤價、最高價、最低價、成交筆數等	N
Market Tickers	market.tickers	sub	所有對外公開交易對的日K線、最近24小時成交量等信息	N
Accounts	accounts	sub, unsub	訂閱賬戶資產變更	Y
Orders	orders.$symbol	sub,unsub	訂閱訂單變更	Y
Accounts list	accounts.list	req	請求賬戶資產信息	Y
Order list	accounts.list	req	請求訂單信息	Y
order detail	orders.detail	req	請求某個訂單明細	Y

$symbol 為交易對，可選值： { ethbtc, ltcbtc, etcbtc, bchbtc...... }
用戶選擇“合並深度”時，一定報價精度內的市場掛單將予以合並顯示。合並深度僅改變顯示方式，不改變實際成交價格。

6. 請求數據(req/rep)

請求數據，僅返回一次數據

請求數據的格式

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

"req" 的值為 topic ，請參考 "5. topic格式" 的 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)

訂閱數據(sub)以及接收訂閱數據的大致流程

┌────────┐                         ┌────────┐ 
│ Client │                         │ Server │
└───┬────┘                         └───┬────┘
    │ {"sub": "topic"}                 │
    ├─────────────────────────────────>│
    │                                  │
    │              {"subbed": "topic"} │
    │<┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤
    │                                  │
    │        {"tick": "data of topic"} │
    │<┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤
    │                                  │
    │        {"tick": "data of topic"} │
    │<┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤
    │                                  │

注：訂閱 topic 成功之后，當 topic 對應的數據有更新時，Server 按一定的頻率把 topic 對應的新數據推送給 Client

訂閱數據的格式

成功建立和 WebSocket API 的連接之后，向 Server 發送如下格式的數據來訂閱數據：

{
   "id": "id generate by client",
  "sub": "topic to sub",
  "freq-ms": 1000
}

注：id 參數是可選的注：freq-ms 參數是可選的，可選值為 { 1000, 2000, 3000, 4000, 5000}，不傳 freq-ms 時默認為0也就是有新的數據就馬上推送到 Client，freq-ms 決定 Server 推送的頻率 正確訂閱的例子

正確訂閱：

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

"sub" 的值為 topic ，請參考 "5. topic格式" 的 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
}

9. 鑒權（Authentication）

用戶自己在火幣網生成Access Key和Secret Key，Secret Key由用戶自己保存，用戶需提供Access Key。目前關於 apikey 申請和修改，請在“賬戶 - API 管理 ” 創建新API Key 填寫備注（可選擇綁定ip）點擊創建。其中 Access Key 為 API 訪問密鑰，Secret Key 為用戶對請求進行簽名的密鑰（僅申請時可見）。用戶按規則生成簽名(Signature)。Pro 站和 HADAX 站 apikey 通用。

交易功能 websocket 版本接口建立連接時首先要做鑒權操作，具體格式如下，

重要提示：這兩個密鑰與賬號安全緊密相關，無論何時都請勿向其它人透露。

鑒權請求數據格式

{
  "op": "auth",
  "AccessKeyId": "e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx", 
  "SignatureMethod": "HmacSHA256",
  "SignatureVersion": "2",
  "Timestamp": "2017-05-11T15:19:30",
  "Signature": "4F65x5A2bLyMWVQj3Aqp+B4w+ivaA7n5Oi2SuYtCJ9o=",
}

鑒權請求數據格式說明

字段名稱	類型	說明
op	string	必填；操作名稱，鑒權固定值為 auth；
cid	string	選填；Client 請求唯一 ID
AccessKeyId	string	必填；API 訪問密鑰, 您申請的 APIKEY 中的 AccessKey
SignatureMethod	string	必填；簽名方法, 用戶計算簽名的基於哈希的協議，此處使用 HmacSHA256
SignatureVersion	string	必填；簽名協議的版本，此處使用 2
Timestamp	string	必填；時間戳, 您發出請求的時間 (UTC 時區) (UTC 時區) (UTC 時區) 。在查詢請求中包含此值有助於防止第三方截取您的請求。如：2017-05-11T16:22:06。再次強調是 (UTC 時區)
Signature	string	必填；簽名, 計算得出的值，用於確保簽名有效和未被篡改

注意：

為了減少已有用戶的接入工作量，此處使用了與 REST 接口同樣的簽名算法進行鑒權，詳細請參考 REST_authentication#簽名運算。

請注意大小寫

參數 op，cid, Signature 不參加簽名計算

此處簽名計算中請求方法固定值為GET，其余值請參考 REST 接口簽名算法文檔

步驟：

示例參數簽名（Signature）計算過程如下，

規范要計算簽名的請求因為使用 HMAC 進行簽名計算時，使用不同內容計算得到的結果會完全不同。所以在進行簽名計算前，請先對請求進行規范化處理。
請求方法，后面添加換行符\n。

GET\n

添加小寫的訪問地址，后面添加換行符 \n

api.huobipro.com\n

訪問方法的路徑，后面添加換行符 \n。

/ws/v1\n

按照ASCII碼的順序對參數名進行排序(使用 UTF-8 編碼，且進行了 URI 編碼，十六進制字符必須大寫，如‘:’會被編碼為'%3A'，空格被編碼為'%20')。例如，下面是請求參數的原始順序，進行過編碼后。

AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx&Signature
Method=HmacSHA256&SignatureVersion=2&Timestamp=2017-05-11T15%
3A19%3A30

按照以上順序，將各參數使用字符’&’連接。
- 組成最終的要進行簽名計算的字符串如下：
  - 計算簽名，將以下兩個參數傳入加密哈希函數：要進行簽名計算的字符串，進行簽名的密鑰（SecretKey）
  - 得到簽名計算結果並進行 Base64編碼
將上述值作為參數Signature的取值添加到 API 請求中。將此參數添加到請求時，必須將該值進行 URI 編碼。

鑒權應答數據格式說明

名稱	類型	說明
op	string	必填；操作名稱，鑒權固定值為 auth
err-code	integer	成功返回 0, 失敗為其他值，詳細響應碼列表請參考附錄
err-msg	string	可選，若出錯表示詳細錯誤信息
ts	long	服務端應答時間戳
user-id	long	用戶 id

鑒權成功應答數據示例

{
  "op": "auth",
  "ts": 1489474081631,
  "err-code": 0,
  "data": {
    "user-id": 1000
  }
}

鑒權失敗應答返回數據

{
  "op": "auth",
  "ts": 1489474081631,
  "err-code": 1010，
  "err-msg": ”詳細的錯誤信息“
}

若用戶上一次鑒權還未應答，用戶連續發送鑒權請求，會返回重復鑒權的錯誤應答：

{
  "op": "auth",
  "ts": 1489474081631,
  "err-code": 1022，
  "err-msg": ”詳細的錯誤信息“
}

WebSocket API Reference

訂閱 KLine 數據 market.$symbol.kline.$period

成功建立和 WebSocket API 的連接之后，向 Server 發送如下格式的數據來訂閱數據：

{
  "sub": "market.$symbol.kline.$period",
  "id": "id generate by client"
}

參數名稱	是否必須	類型	描述	默認值	取值范圍
symbol	true	string	交易對		ethbtc, ltcbtc, etcbtc, bchbtc......以下新的symbol會在生效日當天可以請求：huobi10 - 指數，hb10 - ETF凈值
period	true	string	K線周期		1min, 5min, 15min, 30min, 60min, 1day, 1mon, 1week, 1year

正確訂閱的例子

正確訂閱

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

訂閱成功返回數據的例子

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

請求 KLine 數據 market.$symbol.kline.$period

{
  "req": "market.$symbol.kline.$period",
  "id": "id generated by client",
  "from": 1533536947, //optional, type: long, 2017-07-28T00:00:00+08:00 至 2050-01-01T00:00:00+08:00 之間的時間點，單位：秒
  "to": 1533536947 //optional, type: long, 2017-07-28T00:00:00+08:00 至 2050-01-01T00:00:00+08:00 之間的時間點，單位：秒，必須比 from 大
}

參數名稱	是否必須	類型	描述	默認值	取值范圍
symbol	true	string	交易對		btcusdt, ethusdt, ltcusdt, etcusdt, bchusdt, ethbtc, ltcbtc, etcbtc, bchbtc... 以下新的symbol會在生效日當天可以請求：huobi10 - 指數，hb10 - ETF凈值
period	true	string	K線周期		1min, 5min, 15min, 30min, 60min, 1day, 1mon, 1week, 1year

關於ETF請求參數的說明

Symbol	說明
huobi10	指數
hb10	ETF凈值

其他請求參數period,from,to保持不變。

響應結果

響應結果的結構保持不變，唯一的區別是響應結果中的amount, count 和 vol都是0，因為在這里的amount, count 和 vol是交易的相關的值，而指數和ETF凈值沒有相應的數據。Houbi10 指數和 Hb10凈值每15秒更新一次。

[t1, t5] 假設有 t1 ~ t5 的K線.

from: t1, to: t5, return [t1, t5].
from: t5, to: t1, which t5 > t1, return [].
from: t5, return [t5].
from: t3, return [t3, t5].
to: t5, return [t1, t5].
from: t which t3 < t <t4, return [t4, t5].
to: t which t3 < t <t4, return [t1, t3].
from: t1 and to: t2, should satisfy 1501171200 < t1 < t2 < 2524579200.

一次最多300條

請求 KLine 數據的例子

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

返回數據的例子

{
  "rep": "market.btcusdt.kline.1min",
  "status": "ok",
  "id": "id10",
  "tick": [
    {
      "amount": 17.4805,
      "count":  27,
      "id":     1494478080,
      "open":   10050.00,
      "close":  10058.00,
      "low":    10050.00,
      "high":   10058.00,
      "vol":    175798.757708
    },
    {
      "amount": 15.7389,
      "count":  28,
      "id":     1494478140,
      "open":   10058.00,
      "close":  10060.00,
      "low":    10056.00,
      "high":   10065.00,
      "vol":    158331.348600
    },
    // more KLine data here
  ]
}

訂閱 Market Depth 數據 market.$symbol.depth.$type

成功建立和 WebSocket API 的連接之后，向 Server 發送如下格式的數據來訂閱數據：

{
  "sub": "market.$symbol.depth.$type",
  "id": "id generated by client"
}

參數名稱	是否必須	類型	描述	默認值	取值范圍
symbol	true	string	交易對		btcusdt, ethusdt, ltcusdt, etcusdt, bchusdt, ethbtc, ltcbtc, etcbtc, bchbtc...
type	true	string	Depth 類型		step0, step1, step2, step3, step4, step5（合並深度0-5）；step0時，不合並深度

用戶選擇“合並深度”時，一定報價精度內的市場掛單將予以合並顯示（具體合並規則見GET /market/symbols）。合並深度僅改變顯示方式，不改變實際成交價。

正確訂閱例子

{
  "sub": "market.btcusdt.depth.step0",
  "id": "id1"
}

訂閱成功返回數據的例子

{
  "id": "id1",
  "status": "ok",
  "subbed": "market.btcusdt.depth.step0",
  "ts": 1489474081631
}

之后每當 depth 有更新時，client 會收到數據，例子

{
  "ch": "market.btcusdt.depth.step0",
  "ts": 1489474082831,
  "tick": {
    "bids": [
    [9999.3900,0.0098], // [price, amount]
    [9992.5947,0.0560],
    // more Market Depth data here
    ]
    "asks": [
    [10010.9800,0.0099]
    [10011.3900,2.0000]
    //more data here
    ]
  }
}

tick 說明

  "tick": {
    "bids": [
    [買1價,買1量]
    [買2價,買2量]
    //more data here
    ]
    "asks": [
    [賣1價,賣1量]
    [賣2價,賣2量]
    //more data here
    ]
  }

請求 Market Depth 數據 market.$symbol.depth.$type

{
  "req": "market.$symbol.depth.$type",
  "id": "id generated by client"
}

請求 Market Depth 數據的例子

{
  "req": "market.btcusdt.depth.step0",
  "id": "id10"
}

返回數據的例子：

{
  "rep": "market.btcusdt.depth.step0",
  "status": "ok",
  "id": "id10",
  "tick": {
    "bids": [
    [9999.3900,0.0098], // [price, amount]
    [9992.5947,0.0560],
    // more Market Depth data here
    ]
    "asks": [
    [10010.9800,0.0099]
    [10011.3900,2.0000]
    //more data here
    ]
  }
}

訂閱 Trade Detail 數據 market.$symbol.trade.detail

{
  "sub": "market.$symbol.trade.detail",
  "id": "id generated by client"
}

參數名稱	是否必須	類型	描述	默認值	取值范圍
symbol	true	string	交易對		btcusdt, ethusdt, ltcusdt, etcusdt, bchusdt, ethbtc, ltcbtc, etcbtc, bchbtc...

正確訂閱例子：

{
  "sub": "market.btcusdt.trade.detail",
  "id": "id1"
}

訂閱成功返回數據的例子：

{
  "id": "id1",
  "status": "ok",
  "subbed": "market.btcusdt.trade.detail",
  "ts": 1489474081631
}

之后每當 Trade Detail 有更新時，client 會收到數據，例子：

{
  "ch": "market.btcusdt.trade.detail",
  "ts": 1489474082831,
  "tick": {
        "id": 14650745135,
        "ts": 1533265950234,
        "data": [
            {
                "amount": 0.0099,
                "ts": 1533265950234,
                "id": 146507451359183894799,
                "price": 401.74,
                "direction": "buy"
            },
            // more Trade Detail data here
        ]
    }
  
  ]
  }
}

data 說明：

  "data": [
    {
      "id":        消息ID,
      "price":     成交價,
      "time":      成交時間,
      "amount":    成交量,
      "direction": 成交方向,
      "tradeId":   成交ID,
      "ts":        時間戳
    }
  ]

請求 Trade Detail 數據 market.$symbol.trade.detail

{
  "req": "market.$symbol.trade.detail",
  "id": "id generated by client"
}

僅能獲取最近 300 個 Trade Detail 數據

請求 Trade Detail 數據的例子

{
  "req": "market.btcusdt.trade.detail",
  "id": "id11"
}

返回數據的例子：

{
  "rep": "market.btcusdt.trade.detail",
  "status": "ok",
  "id": "id11",
  "data": [
    {
      "id":        601595424,
      "price":     10195.64,
      "time":      1494495766,
      "amount":    0.2943,
      "direction": "buy",
      "tradeId":   601595424,
      "ts":        1494495766000
    },
    {
      "id":        601595423,
      "price":     10195.64,
      "time":      1494495711,
      "amount":    0.2430,
      "direction": "buy",
      "tradeId":   601595423,
      "ts":        1494495711000
    },
    // more Trade Detail data here
  ]
}

請求 Market Detail 數據 market.$symbol.detail

{
  "req": "market.$symbol.detail",
  "id": "id generated by client"
}

僅返回當前 Market Detail

請求 Market Detail 數據的例子

{
  "req": "market.btcusdt.detail",
  "id": "id12"
}

返回數據的例子：

{
  "rep": "market.btcusdt.detail", "status": "ok", "id": "id12", "tick": { "amount": 12224.2922, "open": 9790.52, "close": 10195.00, "high": 10300.00, "ts": 1494496390000, "id": 1494496390, "count": 15195, "low": 9657.00, "vol": 121906001.754751 } }

訂閱accounts

訂閱accounts資產變動更新。

訂閱請求數據格式說明

字段名稱	類型	說明
op	string	必填；操作名稱，訂閱固定值為 sub；
cid	string	選填；Client 請求唯一 ID
topic	string	必填；訂閱主題名稱，詳細主題列表請參考附錄；

訂閱請求示例

正確的訂閱請求

{
  "op": "sub",
  "cid": "40sG903yz80oDFWr",
  "topic": "accounts"
 
}

訂閱成功返回數據示例

{
  "op": "sub",
  "cid": "40sG903yz80oDFWr",
  "err-code": 0,
  "ts": 1489474081631,
  "topic": "accounts"
}

之后每當 Account 有更新時，Client 會收到數據，比如，

{
  "op": "notify",
  "ts": 1522856623232,
  "topic": "accounts",
  "data": {
    "event": "order.match|order.place|order.refund|order.cancel|order.fee-refund|margin.transfer|margin.loan|margin.interest|margin.repay|other",
    "list": [
      {
        "account-id": 419013,
        "currency": "usdt",
        "type": "trade",
        "balance": "500009195917.4362872650"
      },
      {
        "account-id": 419013,      
        "currency": "btc",
        "type": "frozen",
        "balance": "9786.6783000000"
      }
    ]
  }
}

Accounts變化通知數據格式說明

名稱	類型	說明
event	string	資產變化通知相關事件說明，比如訂單創建(order.place) 、訂單成交(order.match)、訂單成交退款（order.refund)、訂單撤銷(order.cancel) 、點卡抵扣交易手續費（order.fee-refund)、杠桿賬戶划轉（margin.transfer)、借貸本金（margin.loan)、借貸計息（margin.interest)、歸還借貸本金利息(margin.repay)、其他資產變化(other)
account-id	long	賬戶 id
currency	string	幣種
type	string	賬戶類型, 比如交易可用賬戶(trade)，交易凍結賬戶(frozen)
balance	string	賬戶余額

訂閱orders.$symbol

訂閱訂單更新

訂閱請求數據格式說明

字段名稱	類型	說明
op	string	必填；操作名稱，訂閱固定值為 sub；
cid	string	選填；Client 請求唯一 ID
topic	string	必填；訂閱主題名稱，詳細主題列表請參考附錄；

正確的訂閱請求

{
  "op": "sub",
  "cid": "40sG903yz80oDFWr",
  "topic": "orders.htusdt"
 
}

訂閱成功返回數據示例

{
  "op": "sub",
  "cid": "40sG903yz80oDFWr",
  "err-code": 0,
  "ts": 1489474081631,
  "topic": "orders.htusdt"
}

之后每當 Order 有更新時，Client 會收到數據，比如，

{
  "op": "notify",
  "topic": "orders.htusdt",
  "ts": 1522856623232,
  "data": {
    "seq-id": 94984,
    "order-id": 2039498445,
    "symbol": "htusdt",
    "account-id": 100077,
    "order-amount": "5000.000000000000000000",
    "order-price": "1.662100000000000000",
    "created-at": 1522858623622,
    "order-type": "buy-limit",
    "order-source": "api",
    "order-state": "filled",
    "role": "taker|maker",
    "price": "1.662100000000000000",
    "filled-amount": "5000.000000000000000000",
    "unfilled-amount": "0.000000000000000000",
    "filled-cash-amount": "8301.357280000000000000",
    "filled-fees": "8.000000000000000000"
  }
}

訂單變化通知數據格式說明

名稱	類型	說明
seq-id	long	流水號(不連續)
order-id	long	訂單 id
symbol	string	交易對
account-id	long	賬戶 id
order-amount	string	訂單數量
order-price	string	訂單價格
created-at	long	訂單創建時間
order-type	string	訂單類型，請參考訂單類型說明
order-source	string	訂單來源，請參考訂單來源說明
order-state	string	訂單狀態，請參考訂單狀態說明
role	string	maker, taker
price	string	成交價格
filled-amount	string	單次成交數量
unfilled-amount	string	單次未成交數量
filled-cash-amount	string	單次成交金額
filled-fees	string	單次成交手續費（買入為幣，賣出為錢）

錯誤訂閱請求示例（錯誤的 topic）

{
  "op": "sub",
  "topic": "foo.bar",
  "cid": "40sG903yz80oDFWr"
}

訂閱失敗會返回下面示例數據

{
  "op": "sub",
  "topic": "foo.bar",
  "cid": "40sG903yz80oDFWr",
  "err-code": 1001, //具體編碼請參考響應碼表
  "err-msg": “詳細的錯誤信息”，
  "ts": 1489474081631
}

取消訂閱數據(unsub)

成功建立和 WebSocket API 的連接之后，向 Server 發送如下格式的數據來取消訂閱數據：

取消訂閱請求數據格式

{
  “op”: “unsub”,
  “topic": "topic to unsub”,
  "cid": "id generated by client”,
}

取消訂閱請求數據格式說明

字段名稱	類型	說明
op	string	必填；操作名稱，訂閱固定值為 unsub；
cid	string	選填；Client 請求唯一 ID
topic	string	必填；待取消訂閱主題名稱，詳細主題列表請參考附錄；

取消訂閱請求示例

正確的取消訂閱請求

{
  "op": "unsub",
  "topic": "accounts",
  "cid": "40sG903yz80oDFWr"
}

取消訂閱成功返回數據示例

{
  "op": "unsub",
  "topic": "accounts",
  "cid": "id generated by client",
  "err-code": 0,
  "ts": 1489474081631
}

訂閱與取消訂閱規則說明

訂閱(sub)	取消訂閱(unsub)	規則
accounts	accounts	允許
orders.*	orders.*	允許
orders.symbol1	orders.*	允許
orders.symbol1	orders.symbol1	允許
orders.symbol1	orders.symbol2	不允許
orders.*	orders.symbol1	不允許

請求用戶資產 - accounts.list

查詢當前用戶的所有賬戶余額數據

成功建立和 WebSocket API 的連接之后，向 Server發送如下格式的數據來查詢賬戶數據：

賬戶查詢請求數據格式說明

字段名稱	類型	說明
op	string	必填；操作名稱，固定值為 req；
cid	string	選填；Client 請求唯一 ID
topic	string	必填；固定值為accounts.list，詳細主題列表請參考附錄；

賬戶查詢請求示例

請求內容

{
  "op": "req",
  "topic": "accounts.list",
  "cid": "40sG903yz80oDFWr"
}

調用成功返回數據

{
  "op": "req",
  "topic": "accounts.list",
  "cid": "40sG903yz80oDFWr"
  "err-code": 0,
  "ts": 1489474082831,
  "data": [
    {
      "id": 419013,
      "type": "spot",
      "state": "working",
      "list": [
        {
          "currency": "usdt",
          "type": "trade",
          "balance": "500009195917.4362872650"
        },
        {
          "currency": "usdt",
          "type": "frozen",
          "balance": "9786.6783000000"
        }
      ]
    },
    {
      "id": 35535,
      "type": "point",
      "state": "working",
      "list": [
        {
          "currency": "eth",
          "type": "trade",
          "balance": "499999894616.1302471000"
        },
        {
          "currency": "eth",
          "type": "frozen",
          "balance": "9786.6783000000"
        }
      ]
    }
  ]
}

調用失敗應答數據示例

{
  "op": "req",
  "topic": "foo.bar",
  "cid": "40sG903yz80oDFWr"
  "err-code": 12001, //具體編碼需要參考響應碼表
  “err-msg": "詳細的錯誤信息”，
  "ts": 1489474081631
}

請求交易訂單 - orders.list

查詢當前委托、歷史委托

成功建立和 WebSocket API 的連接之后，向 Server發送如下格式的數據來查詢委托數據：

訂單列表查詢請求數據格式

{
  "op": "req",
  "topic": "orders.list",
  "cid": "40sG903yz80oDFWr",
  "account-id": "$account-id",
  "symbol": "$symbol",
  "types": "$order-type",
  "start-date": "$start-date",
  "end-date": "$end-date",  
  "states": "$order-state",
  "from": "$from",
  "direct": "$direct",
  "size": "$size"
}

訂單查詢請求數據格式說明

參數名稱	是否必須	類型	描述	取值范圍
op	true	string	操作名稱，固定值為 req
cid	false	string	Client 請求唯一 ID
topic	true	string	固定值為 orders.list，詳細主題列表請參考附錄
account-id	true	long	賬戶 id
symbol	true	string	交易對	btcusdt, ltcbtc, etcbtc, htusdt......
types	false	string	查詢的訂單類型組合，使用','分割	參考訂單類型說明
start-date	false	string	查詢開始日期, 日期格式yyyy-mm-dd
end-date	false	string	查詢結束日期, 日期格式yyyy-mm-dd
states	true	string	查詢的訂單狀態組合，使用','分割
from	false	string	查詢起始 ID
direct	false	string	查詢方向	prev 向前，next 向后
size	false	string	查詢記錄大小

訂單列表查詢請求示例

{
  "op": "req",
  "topic": "orders.list",
  "cid": "40sG903yz80oDFWr",
  "symbol": "htusdt",
  "states": "submitted,partial-filled"
}

調用成功返回數據

{
  "op": "req",
  "topic": "orders.list",
  "cid": "40sG903yz80oDFWr",
  "err-code": 0,
  "ts": 1522856623232,
  "data": [
    {
      "id": 2039498445,
      "symbol": "htusdt",
      "account-id": 100077,
      "amount": "5000.000000000000000000",
      "price": "1.662100000000000000",
      "created-at": 1522858623622,
      "type": "buy-limit",
      "filled-amount": "5000.000000000000000000",
      "filled-cash-amount": "8301.357280000000000000",
      "filled-fees": "8.000000000000000000",
      "finished-at": 1522858624796,
      "source": "api",
      "state": "filled",
      "canceled-at": 0
    }
  ]
}

應答數據格式說明，

名稱	類型	說明
id	long	訂單ID
symbol	string	交易對
account-id	long	賬戶ID
amount	string	訂單數量
price	string	訂單價格
created-at	long	訂單創建時間
type	string	訂單類型，請參考訂單類型說明
filled-amount	string	已成交數量
filled-cash-amount	string	已成交總金額
filled-fees	string	已成交手續費
finished-at	string	最后成交時間
source	string	訂單來源，請參考訂單來源說明
state	string	訂單狀態，請參考訂單狀態說明
cancel-at	long	撤單時間

請求某個訂單詳情 - orders.detail

查詢某個訂單詳情

成功建立和 WebSocket API 的連接之后，向 Server發送如下格式的數據來查詢某個訂單詳情數據：

訂單詳情查詢請求數據格式

{
  "op": "req",
  "topic": "orders.detail",
  "order-id": "$order-id"
  "cid": "40sG903yz80oDFWr"
}

訂單詳情查詢請求數據格式說明

參數名稱	是否必須	類型	描述
op	true	string	操作名稱，固定值為 req
cid	true	string	Client 請求唯一 ID
topic	false	string	固定值為 orders.detail，詳細主題列表請參考附錄
order-id	true	string	訂單ID

訂單詳情查詢請求示例

請求內容

{
  "op": "req",
  "topic": "orders.detail",
  "order-id": "2039498445"
  "cid": "40sG903yz80oDFWr"
}

調用成功返回數據示例

{
  "op": "req",
  "topic": "orders.detail",
  "cid": "40sG903yz80oDFWr"
  "err-code": 0,
  "ts": 1522856623232,
  "data": {
    "id": 2039498445,
    "symbol": "htusdt",
    "account-id": 100077,
    "amount": "5000.000000000000000000",
    "price": "1.662100000000000000",
    "created-at": 1522858623622,
    "type": "buy-limit",
    "filled-amount": "5000.000000000000000000",
    "filled-cash-amount": "8301.357280000000000000",
    "filled-fees": "8.000000000000000000",
    "finished-at": 1522858624796,
    "source": "api",
    "state": "filled",
    "canceled-at": 0
  }
}

請求數據（req)限流策略

為鼓勵用戶使用訂閱接收數據推送，對查詢請求做了限流策略，規則如下：

accounts.list 查詢請求，同一個用戶(不論幾個連接），每2次請求間隔不能小於25秒（此數字可能發生變化），否則會接收到“too many request"的錯誤應答。
orders.list 和 orders.detail 查詢請求，同一個用戶（不論幾個連接），每2次請求間隔不能小於5秒（此數字可能發生變化），否則會接收到“too many request"的錯誤應答。

附錄

操作類型（OP ）說明

類型	描述
ping	心跳發起(server)
pong	心跳應答
auth	鑒權
sub	訂閱消息
unsub	取消訂閱消息
req	請求數據
notify	推送訂閱消息(server)

主題 (Topic) 類型說明

類型	適用操作類型	描述
accounts	sub, unsub	訂閱、取消訂閱所有資產變更消息
orders.$symbol	sub, unsub	訂閱、取消訂閱指定交易對的訂單變更消息，當 $symbol值為 `*`時代表訂閱所有交易對
accounts.list	req	賬戶數據請求
orders.list	req	訂單列表查詢請求
orders.detail	req	訂單詳情查詢請求

響應碼（Err-Code）說明

具體碼表請參照error.json

訂單類型（Order Type）說明

類型	描述
buy-market	市價買
sell-market	市價賣
buy-limit	限價買
sell-limit	限價賣
buy-ioc	買入立即執行或撤銷
sell-ioc	賣出立即執行或撤銷
buy-limit-maker	限價買入(只能成為maker)
Sell-limit-maker	限價賣出(只能成為maker)

訂單狀態（Order State）說明

類型	描述
submitted	已提交
partial-filled	部分成交
partial-canceled	部分成交撤銷(終態)
filled	完全成交(終態)
canceled	已撤銷(終態)

訂單來源（Order Source）說明

類型	描述
spot-web	現貨 Web 交易單
spot-api	現貨 Api 交易單
spot-app	現貨 App 交易單
margin-web	借貸 Web 交易單
margin-api	借貸 Api 交易單
margin-app	借貸 App 交易單
fl-sys	借貸強制平倉單（爆倉單）

免責聲明！

本站轉載的文章為個人學習借鑒使用，本站對版權不負任何法律責任。如果侵犯了您的隱私權益，請聯系本站郵箱yoyou2525@163.com刪除。

猜您在找 火幣Huobi API 火幣網API文檔——WebSocket API Reference 火幣網API文檔——WebSocket API錯誤碼火幣網API文檔——WebSocket API簡介火幣網API文檔——Websocket 請求與訂閱示例幣安Binance API Websocket 火幣網API文檔——REST API 錯誤碼火幣網行情獲取的websocket客戶端火幣網API文檔——REST API 簽名認證火幣網API文檔——REST 行情、交易API簡介