行情推送概覽

WebSocket 行情推送用於在連接建立後持續接收實時行情變化，適合報價看板、行情監控、策略觸發、成交明細流等對時效性要求較高的場景。

WebSocket Quote 接入地址：

wss://webapi-quote.moomoo.com

能力概覽

分類	說明
基礎報價	推送標的的最新價、開盤價、最高價、最低價、昨收價、成交量、成交額、證券狀態等 Quote 基礎報價字段。
買賣盤	推送標的的實時買賣盤擺盤。返回檔數與盤口形態由用户行情權限檔（LV1/LV2/LV3）與品類共同決定。
逐筆成交	推送成交明細，包含成交時間、序號、買賣方向、價格、成交量、成交額、成交類型等信息。
K 線	推送當前 K 線更新，支持分鐘/日/周/月/季/年等週期，具體週期與復權方式以訂閲接口和數據格式頁說明為準。
經紀隊列	部分港股品類可能隨買賣盤能力返回經紀席位隊列，具體可用性取決於市場、品類和權限。
市場狀態	推送市場維度的交易狀態信息，例如市場、狀態、交易日等。

WebSocket 推送的消息結構、事件類型和字段含義詳見 數據格式。

接入流程

步驟	說明
1. 建立連接	連接 WebSocket Quote 地址 wss://webapi-quote.moomoo.com。
2. 登錄鑑權	連接建立後先完成登錄鑑權。推薦使用 OAuth 2.1 + PKCE 獲取的 Bearer Token，也兼容傳統 API Key 方式。詳見 登錄鑑權。
3. 訂閲數據	按標的代碼和數據類型發起訂閲，例如基礎報價、買賣盤、逐筆成交、K 線等。詳見 訂閲與反訂閲。
4. 接收推送	服務端在行情變化時通過 WebSocket 返回 JSON 消息。客户端應按 type 區分 QUOTE、ORDER_BOOK、TICKER、KLINE 等消息類型。
5. 連接保活	定時 refresh token 以維持連接有效性，避免因 token 過期導致連接斷開。詳見 連接保活。
6. 斷線重連	連接斷開後，客户端應重新連接、重新登錄鑑權，並重新訂閲所需標的。不要假設斷線後訂閲狀態會自動恢復。

訂閲與推送類型

客户端可顯式訂閲的行情類型通常包括：

• quote — 基礎報價，對應推送消息 QUOTE。
• order_book — 買賣盤，對應推送消息 ORDER_BOOK。
• ticker — 逐筆成交，對應推送消息 TICKER。
• kline — 當前 K 線，對應推送消息 KLINE。

服務端也可能基於已訂閲的標的和權限推送衍生消息：

• BROKER_QUEUE — 經紀隊列，主要與部分港股買賣盤能力相關。
• MARKET_STATE — 市場狀態，按市場維度推送，不綁定單一標的。

標的代碼

訂閲請求面向開發者使用統一的標的代碼格式 {market}.{code}，例如 HK.00700、US.AAPL。不同市場、品類和行情權限支持的數據類型可能不同，請以具體接口說明和權限結果為準。

與 REST 實時行情的關係

WebSocket 推送和 REST 實時行情都用於獲取實時市場數據，但適用場景不同：

場景	推薦方式
需要持續接收變化	使用 WebSocket 行情推送，訂閲後由服務端主動推送。
只需要一次性查詢	使用 REST 實時行情接口，例如行情快照、實時報價、買賣盤、當前 K 線、逐筆成交等。
少量標的低頻刷新	可使用 REST 輪詢，邏輯簡單，便於按需獲取。
多標的高頻更新	優先使用 WebSocket 推送，避免頻繁輪詢 REST 接口。
連接中斷後的補齊	可在重連後使用 REST 查詢最新快照，再恢復 WebSocket 訂閲。

相關 REST 接口：

• 行情快照 — 批量獲取標的的行情快照（實時）。
• 實時報價 — 批量獲取標的的實時股票報價（輕量版快照），對齊推送時的 Quote 基礎報價。
• 買賣盤 — 獲取標的的實時買賣盤擺盤。
• 當前 K 線 — 獲取標的當前 K 線數據。
• 逐筆成交 — 獲取標的的逐筆成交數據。

重要約束

• 必須先鑑權再訂閲：未完成登錄鑑權或權限不足時，訂閲或推送可能失敗。
• 權限影響返回內容：市場權限、品類權限和行情權限檔（LV1/LV2/LV3）會影響可訂閲的數據類型、買賣盤檔數和深度數據可用性。
• 訂閲佔用配額：訂閲標的和數據類型會消耗對應配額。請按需訂閲，離開頁面或不再使用時及時反訂閲。詳見 頻率與配額。
• 長連接需要容錯：網絡切換、代理超時、服務端維護都可能導致連接斷開。客户端應實現斷線重連、重新登錄鑑權和重新訂閲。
• 不要依賴消息順序補歷史：推送用於實時增量通知。如需拉取某一時點的完整狀態或斷線期間的最新狀態，請結合 REST 實時行情接口查詢。
• 字段可能按品類缺省：不適用品類的字段可能缺省、置 0 或為空。解析時請按 數據格式 做兼容處理。

下一步

• 快速開始 — 獲取訪問憑證並瞭解 API Host、認證方式和通用約定。
• 登錄鑑權 — 瞭解 WebSocket 連接後的登錄鑑權流程。
• 訂閲與反訂閲 — 瞭解如何訂閲、反訂閲和管理訂閲狀態。
• 連接保活 — 瞭解心跳、超時、斷線重連等長連接處理建議。
• 數據格式 — 查看推送消息結構、消息類型和字段說明。
• 錯誤碼 — 排查鑑權、訂閲、權限和配額相關錯誤。
• 頻率與配額 — 瞭解訂閲配額、調用頻率和重試建議。