BTCMEX WebSocket API
BTCMEX 通過 WebSocket 提供 pub/sub API。 您可以訂閱即時數據。我們提供一個示例可以讓您迅速開始接收我們的數據。
連接
將您的 WebSocket 客戶端連接到 wss://www.btcmex.com/realtime。
通過發送 "help",你可以基本瞭解如何使用我們的 WebSocket API 。
所有指令
基本的命令發送的格式︰
{"op": "<command>", "args": ["arg1", "arg2", "arg3"]}
在某些命令上,參數數組是可選的。 如果您只發送一個參數,則數組不是必需的。
WebSocket 不支持新增和取消委託。 此功能請使用 REST API。
訂閱
BTCMEX 允許訂閱即時數據。 一旦連接成功,該訪問方式沒有頻率限制,它是獲取最新數據的最好方法。
要訂閱主題,請發送逗號分隔的主題列表。例如︰
wss://www.btcmex.com/realtime?subscribe=instrument:XBTUSD,order:XBTUSD,orderBookL2:XBTUSD,trade:XBTUSD,liquidation:XBTUSD
如果您已連接,並且想要訂閱一個新主題,請發送以下格式的請求︰
{"op": "subscribe", "args": [<SubscriptionTopic>]}
通過發送訂閱主題數組,您可以一次訂閱多個主題。
下列訂閱主題無需身份驗證:
"orderBookL2_25", // 前25層的Level2委託列表
"orderBookL2", // 完整的level2委託列表
"orderBook10", // 前10層的委託列表,傳統的完整委託列表推送
"trade", // 即時交易,對應UI近期交易列表
"instrument", // 產品更新,包括交易量以及報價
"liquidation", // 進入委託列表的強平委託
下列主題要求進行身份驗證︰
"order", // 你的委託更新
"margin", // 你帳戶的餘額和保證金要求的更新
"position", // 你倉位的更新
"execution", // 獲取您帳戶所有的原始執行
如果您想獲得即時委託列表數據,建議您使用 orderBookL2_25 訂閱。
orderBook10 在任何數據變動時都推送完整的 10 個深度列表,這意味著更多的數據量。
orderBookL2 推送完整的 L2 委託列表,但有效載荷可能變得非常大。
orderbookL225 提供完整 L2 委託列表的子集。 如果對延時有較高要求,請使用 orderBookL2。在 orderBookL225 或 orderBookL2 中的 id 字段是根據價格和合約符號計算的,因此對於任何價格,它是唯一的,被用於 update 和 delete 操作。
使用時,訂閱可以在主題後加冒號進行篩選。 例如,trade:XBTUSD 將只訂閱 XBTUSD 的消息。
示例數據:
> {"op": "subscribe", "args": ["orderBookL2_25:XBTUSD"]}
< {"success":true,"subscribe":"orderBookL2_25:XBTUSD","request":{"op":"subscribe","args":["orderBookL2_25:XBTUSD"]}}
< { "table":"orderBookL2_25", "keys":["symbol","id","side"], "types":{"id":"long","price":"float","side":"symbol","size":"long","symbol":"symbol"} "foreignKeys":{"side":"side","symbol":"instrument"}, "attributes":{"id":"sorted","symbol":"grouped"}, "action":"partial", "data":[
{"symbol":"XBTUSD","id":17999992000,"side":"Sell","size":100,"price":80},
{"symbol":"XBTUSD","id":17999993000,"side":"Sell","size":20,"price":70},
{"symbol":"XBTUSD","id":17999994000,"side":"Sell","size":10,"price":60},
{"symbol":"XBTUSD","id":17999995000,"side":"Buy","size":10,"price":50},
{"symbol":"XBTUSD","id":17999996000,"side":"Buy","size":20,"price":40},
{"symbol":"XBTUSD","id":17999997000,"side":"Buy","size":100,"price":30}
]
}
< { "table":"orderBookL2_25", "action":"update", "data":[
{"symbol":"XBTUSD","id":17999995000,"side":"Buy","size":5}
]
}
< { "table":"orderBookL2_25", "action":"delete", "data":[
{"symbol":"XBTUSD","id":17999995000,"side":"Buy"}
]
}
< { "table":"orderBookL2_25", "action":"insert", "data":[
{"symbol":"XBTUSD","id":17999995500,"side":"Buy","size":10,"price":45},
]
}
訂閱後,您將收到現有數據的鏡像,這通過 partial 實現。
您可能會在 partial 到達之前收到其他消息。 在這種情況下,請忽略收到的消息,直到收到 partial 。
對於數據回應的一些注意事項:
- 訂閱確認後,您將收到一條消息,其中包含 “action”:“partial” 。 該資訊是您訂閱數據的當前鏡像,在這之後,您可以收到基於它使用增量變化資訊。
-
如果您在 partial 消息之前收到任何其他消息,請忽略它們。
- partial 還包含一些表格資訊,如 keys ,types 和 foreignKeys 。 根據您的應用程式,這些數據可能會很有用。
- 在keys中的列總是返回一個插入 ,刪除 ,或更新。 使用它們查找要在存儲中修改哪些專案。
您可以使用'取消訂閱'操作,格式與 "訂閱" 相同。
驗證
許多數據流是公開的(見下文)。如果您希望訂閱用戶的私有數據流,則必須先進行身份驗證。請注意,無效身份驗證將關閉連接。
API 密鑰
BTCMEX API 的使用需要 API 密鑰。
API 密鑰可以被鎖定到某個 IP 地址的範圍,撤銷該密鑰並不影響您的身份驗證資訊。
若要使用 API 密鑰身份驗證,您必須 生成一個 API 密鑰。
若要使用 WebSocket API 密鑰,您可以︰
* 簽署最初的申請請求,與簽署 REST 調用類似(即利用 `api-*` 標頭),
或者
* 在連接建立後,發送 `"authKeyExpires"`。
無論哪種方式,請使用簽署 GET/api/v1/signature 的簽名。
//簽名是十六進制的 hex(HMAC_SHA256(secret, 'GET/api/v1/signature' + expires)) // expires 必須是一個數字,而不是一個字串。 {"op": "authKeyExpires", "args": ["<APIKey>", <expires>, "<signature>"]}
心跳
某些 WebSocket 代碼庫比其他庫能更好地檢測連接斷開。 如果你的 WebSocket 庫支持 hybi-13 或 ping/pong,你可在任何時間發送 ping ,伺服器就會返回pong。
如果你擔心你的連接被默默地終止,我們推薦你採用以下流程:
-
在接收到每條消息後,設置一個30秒鐘的定時器。
-
如果在定時器觸發收到任何新消息,則重置定時器。
-
如果定時器被觸發了(意味著30秒內沒有收到新消息),發送一個 ping 數據幀(如果支持的話),或者發送字串 'ping'。
-
等待 WebSocket 協議的 pong 數據幀或文字字串 'pong' 作為回應。 如果在30秒內未收到,請發出錯誤或重新連接。
說明:對於位於中國大陸的用戶,推薦發送應用層的字串 'ping',使用 WebSocket 協議本身的 ping 數據幀,可能會收不到 相應的 pong 數據幀。
回應數據格式
WebSocket 的回應可能有以下三種類型:
Success:(成功訂閱一個主題後發出)
{"subscribe": subscriptionName, "success": true}
Error: (格式錯誤的請求或試圖請求鎖定的資源時發出)
{"error": errorMessage}
数据:(當數據可用或被請求時發出)
此定義遵循 FlowType 和 TypeScript 中使用的輸入約定。 尾碼為 ?的字段並不總是存在。
{
// 數據表名 / 訂閱主題
// 可以是 "trade","order","instrument" 等等
"table": string, // 消息類型。
類型:
// 'partial': 這是數據表鏡像,將完全替換你的數據。
// 'update': 單行更新
// 'insert': 插入一個新行
// 'delete': 刪除一行
"action": 'partial' | 'update' | 'insert' | 'delete',
// 這裏是一組數據,在結構上與 REST API 返回的數據相同。
"data": Object[],
//
// 以下字段定義了數據表,僅在`partial`中發送
//
// 每個數據對象的特徵名稱是唯一的
// 如果提供多個,則採用複合鍵名(key)。
// 使用這些 key 的名稱來唯一地標識數據列。
// 你接收的左右數據均包含 key 列。
"keys"?: string[],
// 這裏列出了與其他數據表的數據鍵之間的關係。
// 例如,`quote`的外部鍵是{"symbol": "instrument"}
"foreignKeys"?: {[key: string]: string},
// 這裏列舉了數據表的數據類型。 可能的類型為:
// "symbol" - 在大多數語言中類似於 "string" Similar to "string" in most languages
// "guid"
// "timestamp"
// "timespan"
// "float"
// "long"
// "integer"
// "boolean"
"types"?: {[key: string]: string},
// 如果存在對於同一數據表的多個訂閱,請使用 `filter` 來指明不同的訂閱
// 所包含的數據,這是因為 `table` 屬性並不包括某一訂閱的合約標記。
"filter"?: {account?: number, symbol?: string},
// 這些是我們內部的特徵名稱,用來代表這些數據是如何被排序。
"attributes"?: {[key: string]: string},
}
評論
0 條評論
請登入寫評論。