數據格式

WebSocket 加密貨幣交易推送使用 Protobuf 二進制編碼傳輸。每條推送消息對應一個 ReportMsg 結構，客戶端應先按 report_type 字段區分報告類型，再解析 new_rpt、cancel_rpt、fill_rpt、expire_rpt 等具體子報告字段。

注意

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

INFO

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

Proto 定義

proto

message Order {
    optional string order_id      = 1;  // 訂單ID
    optional uint32 side          = 2;  // 買賣方向 1：BUY  2：SELL
    optional string coin          = 3;  // 交易對的基礎資產，如 BTC、ETH
    optional string currency      = 4;  // 交易對的計價資產，如 USD
    optional string price         = 5;  // 訂單價格
    optional string order_qty     = 6;  // 訂單數量
    optional uint32 ord_type      = 7;  // 訂單類型 1：Limit 2：Market 3：TAKE_PROFIT_LIMIT 4：TAKE_PROFIT_MARKET 5：STOP_LOSS_LIMIT 6：STOP_LOSS_MARKET
    optional uint32 time_in_force = 8;  // 訂單有效期 2：TIF_GTC 3：TIF_IOC
    optional int64 create_time    = 11; // 訂單創建時間戳，微秒
    optional bool is_close        = 12; // 訂單是否完結
    optional string cum_qty       = 13; // 累計成交數量
    optional string avg_px        = 14; // 平均成交價格
}

// 下單報告
message OrderNewRpt {
    optional int32 result    = 1; // 0 成功，非 0 失敗
    optional string err_msg  = 2; // 錯誤信息
    optional string order_id = 3; // 訂單ID
}

// 撤單報告
message OrderCancelRpt {
    optional int32 result    = 1; // 0 成功，非 0 失敗
    optional string err_msg  = 2; // 錯誤信息
    optional string order_id = 3; // 訂單ID
}

// 成交報告
message OrderFillRpt {
    optional string order_id    = 1;  // 訂單ID
    optional string fill_id     = 2;  // 成交ID
    optional string last_px     = 3;  // 本次成交價格
    optional string last_qty    = 4;  // 本次成交數量
    optional string leave_qty   = 5;  // 剩餘未成交數量
    optional uint32 fill_status = 6;  // 成交狀態 1：部分成交 2：完全成交
    optional string last_amount = 9;  // 成交金額
    optional string biz_flow_id = 10; // 業務流水唯一ID
}

// 訂單過期報告
message OrderExpireRpt {
    optional string order_id = 1; // 訂單ID
}

// 交易報告
message ReportMsg {
    optional string report_id          = 1;  // 事件唯一 ID（UUID），用於客戶端冪等處理
    optional Order order               = 4;  // 訂單信息
    optional uint32 report_type        = 6;  // 報告類型 1：下單報告 3：撤單報告 4：成交報告 5：訂單過期報告
    optional OrderNewRpt new_rpt       = 7;  // 下單結果報告
    optional OrderCancelRpt cancel_rpt = 9;  // 撤單結果報告
    optional OrderFillRpt fill_rpt     = 10; // 成交報告
    optional OrderExpireRpt expire_rpt = 11; // 訂單過期報告
}

ReportMsg 頂層字段

字段	類型	說明
`report_id`	string	事件唯一 ID（UUID），可用於客戶端冪等處理。
`order`	Order	訂單信息快照，詳見 Order 字段。
`report_type`	uint32	報告類型，詳見下方報告類型說明。
`new_rpt`	OrderNewRpt	下單結果報告，僅 `report_type=1` 時有值，詳見 OrderNewRpt 字段。
`cancel_rpt`	OrderCancelRpt	撤單結果報告，僅 `report_type=3` 時有值，詳見 OrderCancelRpt 字段。
`fill_rpt`	OrderFillRpt	成交報告，僅 `report_type=4` 時有值，詳見 OrderFillRpt 字段。
`expire_rpt`	OrderExpireRpt	訂單過期報告，僅 `report_type=5` 時有值，詳見 OrderExpireRpt 字段。

報告類型

report_type 字段的可選值：

值	說明
`1`	下單報告。通過 `new_rpt.result` 判斷下單成功（`0`）或失敗（非 `0`）。下單成功時 `order.is_close = false`，下單失敗時 `order.is_close = true`。
`3`	撤單報告。通過 `cancel_rpt.result` 判斷撤單成功（`0`）或失敗（非 `0`）。撤單成功時 `order.is_close = true`。
`4`	成交報告。通過 `fill_rpt.fill_status` 區分部分成交（`1`）和完全成交（`2`）。完全成交時 `order.is_close = true`。
`5`	訂單過期報告。訂單因有效期到期被系統撤銷。`order.is_close = true`。

Order 字段

每條推送消息均攜帶訂單的當前信息快照。

關鍵字段：is_close

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

字段	類型	說明
`order_id`	string	訂單 ID，生命週期內不變。
`side`	uint32	買賣方向。`1`=BUY，`2`=SELL。
`coin`	string	交易對的基礎資產，如 `BTC`、`ETH`。
`currency`	string	交易對的計價資產，如 `USD`。
`price`	string	訂單價格。市價單可能為空。
`order_qty`	string	訂單數量。
`ord_type`	uint32	訂單類型。`1`=Limit，`2`=Market，`3`=TAKE_PROFIT_LIMIT，`4`=TAKE_PROFIT_MARKET，`5`=STOP_LOSS_LIMIT，`6`=STOP_LOSS_MARKET。
`time_in_force`	uint32	訂單有效期。`2`=TIF_GTC，`3`=TIF_IOC。
`create_time`	int64	訂單創建時間，Unix 微秒時間戳。
`is_close`	bool	`true` 表示訂單已到達終態，不會再推送該訂單的後續事件。
`cum_qty`	string	累計成交數量。
`avg_px`	string	平均成交價格。未成交時為 `"0"`。

OrderNewRpt 字段

僅 report_type=1 時存在。

字段	類型	說明
`result`	int32	`0` 表示下單成功，非 `0` 表示下單失敗。
`err_msg`	string	失敗原因。`result=0` 時為空。
`order_id`	string	訂單 ID。

OrderCancelRpt 字段

僅 report_type=3 時存在。

字段	類型	說明
`result`	int32	`0` 表示撤單成功，非 `0` 表示撤單失敗。
`err_msg`	string	失敗原因。`result=0` 時為空。
`order_id`	string	訂單 ID。

OrderFillRpt 字段

僅 report_type=4 時存在。

字段	類型	說明
`order_id`	string	訂單 ID。
`fill_id`	string	成交 ID，可用於冪等去重。
`last_px`	string	本次成交價格。
`last_qty`	string	本次成交數量。
`leave_qty`	string	剩餘未成交數量。
`fill_status`	uint32	成交狀態。`1`=部分成交，`2`=完全成交。
`last_amount`	string	本次成交金額。
`biz_flow_id`	string	業務流水唯一 ID。

OrderExpireRpt 字段

僅 report_type=5 時存在。

字段	類型	說明
`order_id`	string	訂單 ID。

兼容性建議

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

數據格式 ​

Proto 定義 ​

ReportMsg 頂層字段 ​

報告類型 ​

Order 字段 ​

OrderNewRpt 字段 ​

OrderCancelRpt 字段 ​

OrderFillRpt 字段 ​

OrderExpireRpt 字段 ​

兼容性建議 ​

相關文檔 ​