數據格式

WebSocket 加密貨幣交易推送使用 Protobuf 二進制編碼傳輸。每條推送消息對應一個交易事件，反序列化後對應下方描述的 CryptoTradeEvent 結構，客戶端應先按 event_type 字段區分事件類型，再解析 order_info 和 fill_infos 等具體字段。

注意

交易事件推送為 Protobuf 二進制格式，非 JSON 文本。鑒權響應（code/msg 字段）為 JSON 格式。客戶端接收消息時需設置允許接收二進制幀（如 skip_utf8_validation=True）。

INFO

交易事件中的數值字段（如價格、數量）均以字符串類型傳輸，以避免浮點精度問題。時間字段使用微秒時間戳（Unix 微秒）。解析時請按字段說明做類型處理，未知字段建議忽略以保持向前兼容。

消息結構

每條推送消息的頂層為一個 CryptoTradeEvent 對象：

json

{
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event_type": "EVENT_FILL",
  "event_time_us": 1751433600000000,
  "user_info": {
    "uid": 123456789,
    "account_id": 987654321098765432
  },
  "order_info": {
    "order_id": "FTHC2989880641155745280T",
    "version": 2,
    "symbol_pair": {
      "symbol": "BTCUSD",
      "base": "BTC",
      "quote": "USD"
    },
    "side": "BUY",
    "order_qty": "0.1",
    "price": "29500",
    "order_amount": "2950",
    "cum_qty": "0.06",
    "avg_px": "29498.50",
    "fill_amount": "1769.91",
    "ord_type": "LIMIT",
    "time_in_force": "TIF_GTC",
    "create_time": 1751433500000000,
    "update_time": 1751433600000000,
    "ord_status": "PARTIAL_FILLED",
    "order_show_id": "C2989880641155745280",
    "is_close": false,
    "trigger_price": "",
    "trigger_time": 0,
    "cash_order_qty": ""
  },
  "fill_infos": [
    {
      "order_id": "FTHC2989880641155745280T",
      "fill_id": "FILL001",
      "quantity": "0.06",
      "price": "29498.50",
      "amount": "1769.91",
      "fill_time": 1751433600000000
    }
  ]
}

CryptoTradeEvent 頂層字段

字段	類型	說明
`event_id`	string	事件唯一 ID（UUID），可用於客戶端冪等處理。
`event_type`	string	事件類型，詳見下方事件類型說明。
`event_time_us`	integer	事件發生時間，Unix 微秒時間戳。
`user_info`	object	用戶信息，詳見 user_info 字段。
`order_info`	object	訂單快照，反映事件發生時刻的最新訂單狀態，詳見 order_info 字段。
`fill_infos`	object[]	成交信息列表，詳見 fill_infos 字段。僅在 `EVENT_FILL` 事件中有值，其他事件該字段為空數組。

事件類型

event_type 字段的可選值：

值	說明
`EVENT_NEW`	下單成功事件。訂單已被系統受理，進入委託隊列。`order_info.is_close = false`。
`EVENT_NEW_REJECTED`	下單失敗事件。訂單被系統拒絕。`order_info.is_close = true`。
`EVENT_FILL`	成交事件。`fill_infos` 包含本次成交明細。通過 `order_info.ord_status` 區分部分成交（`PARTIAL_FILLED`）和全部成交（`FILLED`）。全部成交時 `order_info.is_close = true`。
`EVENT_CANCELED`	撤單成功事件。訂單已被撤銷。`order_info.is_close = true`。
`EVENT_EXPIRED`	訂單過期事件。訂單因有效期到期被系統撤銷。`order_info.is_close = true`。

user_info 字段

字段	類型	說明
`uid`	integer	用戶 ID（nnid）。
`account_id`	integer	加密貨幣賬戶 ID（uint64）。如果同一用戶持有多個加密貨幣賬戶，可通過該字段區分事件來源賬戶。

order_info 字段

每條推送消息均攜帶訂單的當前快照，反映事件發生時刻的最新訂單狀態。

關鍵字段：is_close

is_close = true 表示訂單已到達終態，不會再收到該訂單的任何後續推送。 is_close = false 表示訂單仍然活躍，後續還可能收到成交或撤單事件。

字段	類型	說明
`order_id`	string	訂單號，生命週期內不變。
`version`	uint32	訂單版本號。
`symbol_pair`	SymbolPair	交易對。
`side`	side	買賣方向。
`order_qty`	string	訂單委託數量。
`price`	string	委託價格。市價單可能為空。
`order_amount`	string	委託金額。
`cum_qty`	string	截至本事件時刻的累計已成交數量。
`avg_px`	string	截至本事件時刻的成交均價。未成交時為 `"0"`。
`fill_amount`	string	截至本事件時刻的累計成交金額。
`ord_type`	ord_type	訂單類型。
`time_in_force`	time_in_force	訂單有效期。
`create_time`	int64	訂單創建時間，Unix 微秒時間戳。
`update_time`	int64	訂單最後更新時間，Unix 微秒時間戳。
`ord_status`	ord_status	訂單當前狀態。
`order_show_id`	string	客戶端展示用訂單 ID。
`is_close`	bool	`true` 表示訂單已到達終態，不會再推送該訂單的後續事件。見上方提示。
`trigger_price`	string	條件單觸發價，非條件單為空字符串。
`trigger_time`	int64	條件單觸發時間（Unix 微秒），未觸發為 `0`。
`cash_order_qty`	string	金額下單時的委託金額，數量下單時為空字符串。

fill_infos 字段

僅在 EVENT_FILL 事件中包含有效數據，其他事件類型該字段為空數組。

字段	類型	說明
`order_id`	string	關聯的訂單 ID。
`fill_id`	string	成交 ID，可用於冪等去重。
`quantity`	string	本次成交數量。
`price`	string	本次成交價格。
`amount`	string	本次成交金額（`price × quantity`）。
`fill_time`	int64	成交時間，Unix 微秒時間戳。

兼容性建議

按 event_type 分發處理：不同事件的 fill_infos 是否有值差異較大，建議 switch/match 處理。
未知字段忽略：服務端可能新增字段，客戶端應保持向前兼容。
未知 event_type 兼容：記錄日誌後跳過，避免因新增事件類型導致處理異常。
數值字段以字符串解析：價格、數量等字段均為字符串，需自行轉換為 Decimal 或 float 處理精度。
微秒時間戳：event_time_us、create_time、update_time、fill_time 均為 Unix 微秒時間戳，注意與毫秒時間戳區分。

數據格式 ​

消息結構 ​

CryptoTradeEvent 頂層字段 ​

事件類型 ​

user_info 字段 ​

order_info 字段 ​

fill_infos 字段 ​

兼容性建議 ​

相關文檔 ​