BTCMEX WebSocket API

連接

所有指令

驗證

API 密鑰

心跳

回應數據格式

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。

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

BTCMEX WebSocket API

連接

所有指令

訂閱

驗證

API 密鑰

心跳

回應數據格式

相關文章