加密貨幣交易推送概覽

WebSocket 加密貨幣交易推送用於在連接建立並完成鑑權後，實時接收賬戶維度的交易事件通知，適合訂單狀態變更、成交狀態變更等對時效性要求較高的場景。

WebSocket Trade 接入地址：

wss://webapi-trade.futunn.com/ws

能力概覽

事件類型	說明
EVENT_NEW	下單成功。訂單已被系統受理，進入委託隊列。
EVENT_NEW_REJECTED	下單失敗。訂單被系統拒絕（如餘額不足、價格非法、風控攔截）。
EVENT_FILL	成交事件。包含部分成交和全部成交。通過 order_info.ord_status 和 order_info.is_close 區分。
EVENT_CANCELED	撤單成功。訂單已被全部撤銷，進入終態。
EVENT_EXPIRED	訂單過期。訂單因有效期到期被系統撤銷，進入終態。

推送消息的完整字段含義詳見 數據格式。

接入流程

步驟	說明
1. 建立連接	連接 WebSocket Trade 地址 wss://webapi-trade.futunn.com/ws。
2. 登錄鑑權	連接建立後先完成登錄鑑權。推薦使用 OAuth 2.1 + PKCE 獲取的 Bearer Token，也兼容傳統 API Key 方式。詳見 登錄鑑權。
3. 接收推送	鑑權成功後即自動訂閱當前鑑權用戶的所有加密貨幣交易事件，無需額外發送訂閱請求。服務端在交易事件發生時主動推送 Protobuf 二進制消息。詳見 訂閱機制。
4. 連接保活	定時 refresh token 以維持連接有效性，避免因 token 過期導致連接斷開。詳見 連接保活。
5. 斷線重連	連接斷開後，客戶端應重新連接並重新登錄鑑權。重連成功後會自動恢復事件推送，不要假設斷線期間的事件會被補發。

重要約束

• 必須先鑑權：未完成登錄鑑權時不會推送任何事件。
• 不保證補發：連接斷開期間發生的交易事件不會在重連後補發。如需補齊歷史訂單或成交數據，請使用 REST 接口查詢。
• 長連接需要容錯：網絡切換、代理超時、服務端維護都可能導致連接斷開。客戶端應實現斷線重連和重新鑑權。
• 事件不保證嚴格順序：極少數情況下，網絡抖動可能導致事件到達順序與實際發生順序不一致，請勿依賴推送順序作為唯一的狀態機驅動。

下一步

• 登錄鑑權 — 了解 WebSocket 連接後的登錄鑑權流程。
• 訂閱機制與場景處理 — 各事件類型的處理場景、終態判斷、冪等建議與時序示例。
• 連接保活 — 了解心跳、超時、斷線重連等長連接處理建議。
• 數據格式 — 查看推送消息結構、事件類型和字段說明。
• 錯誤碼 — 排查鑑權和連接相關錯誤。