交易推送概覽
WebSocket 交易推送用於在連接建立並完成鑑權後，實時接收賬戶維度的交易事件通知，適合訂單狀態變更、成交狀態變更等對時效性要求較高的場景。
WebSocket Trade 接入地址：
text
wss://webapi-trade.moomoo.com/ws能力概覽
| 事件類型 | 說明 |
|---|---|
EVENT_NEW | 下單成功。訂單已被交易所或系統受理。 |
EVENT_REPLACED | 改單成功。訂單價格或數量已按請求修改。 |
EVENT_CANCELED | 撤單成功。訂單已被撤銷。 |
EVENT_EXPIRED | 訂單過期。訂單因有效期到期被系統撤銷。 |
EVENT_FILL | 成交事件。包含全部成交和部分成交兩種情況。 |
EVENT_NEW_REJECTED | 下單失敗。訂單被交易所或系統拒絕。 |
EVENT_REPLACE_REJECTED | 改單失敗。改單請求被拒絕，原訂單不變。 |
EVENT_CANCEL_REJECTED | 撤單失敗。撤單請求被拒絕，原訂單不變。 |
EVENT_FILL_CORRECT | 成交修正。已有成交信息被更正。 |
EVENT_FILL_CANCEL | 成交撤銷。已有成交被系統撤銷。 |
EVENT_WAIT_OPEN | 訂單預埋。訂單已進入預埋狀態，等待提交。 |
EVENT_PRICE_PROTECT | 價格保護。訂單觸發價格保護。 |
EVENT_TRIGGER_WAITING | 條件單監聽。條件單已進入監聽狀態。 |
EVENT_TRIGGER | 條件單觸發。條件單已觸發。 |
推送消息的完整字段含義詳見 數據格式。
接入流程
| 步驟 | 說明 |
|---|---|
| 1. 建立連接 | 連接 WebSocket Trade 地址 wss://webapi-trade.moomoo.com/ws。 |
| 2. 登錄鑑權 | 連接建立後先完成登錄鑑權。推薦使用 OAuth 2.1 + PKCE 獲取的 Bearer Token，也兼容傳統 API Key 方式。詳見 登錄鑑權。 |
| 3. 接收推送 | 鑑權成功後即自動訂閱當前鑑權用戶的所有交易事件，無需額外發送訂閱請求。服務端在交易事件發生時主動推送 JSON 消息。詳見 訂閱機制。 |
| 4. 連接保活 | 定時 refresh token 以維持連接有效性，避免因 token 過期導致連接斷開。詳見 連接保活。 |
| 5. 斷線重連 | 連接斷開後，客戶端應重新連接並重新登錄鑑權。重連成功後會自動恢復事件推送，不要假設斷線期間的事件會被補發。 |
與 REST 的分工
| 方式 | 適合做什麼 | 注意 |
|---|---|---|
| 本推送 | 實時感知下單、改撤、成交等狀態變化 | 斷線期間事件不補發；到達順序不保證嚴格一致 |
| REST 查單 / 查成交 | 核對當前訂單與成交、補齊斷線期間的數據 | 使用 未完成訂單、歷史訂單、當日成交 等 |
建議：在線時用推送驅動界面或策略反應；需要確認最終狀態時，以 REST 查詢結果為準。重連成功後先查一次未完成訂單或近期成交，再繼續接收推送。
重要約束
- 必須先鑑權：未完成登錄鑑權時不會推送任何事件。
- 不保證補發：連接斷開期間發生的交易事件不會在重連後補發。如需補齊歷史訂單或成交數據，請使用 REST 接口查詢。
- 長連接需要容錯：網絡切換、代理超時、服務端維護都可能導致連接斷開。客戶端應實現斷線重連和重新鑑權。
- 事件不保證嚴格順序：極少數情況下，網絡抖動可能導致事件到達順序與實際發生順序不一致，請勿依賴推送順序作為唯一的狀態機驅動。
- 不支持外匯交易事件推送：暫不支持推送外匯訂單相關的交易事件。