Open API

繁體中文

English
简体中文

繁體中文

English
简体中文

Appearance

登錄鑑權 ​

WebSocket 交易推送連接建立後，需要先發送登錄鑑權幀。鑑權成功前不會推送任何交易事件；鑑權失敗、連接關閉或超時未返回鑑權結果時，應關閉當前連接，修正憑證後重新連接並重新鑑權。

INFO

本文描述的是當前 WebSocket 接入層支持的鑑權幀形態。後端交易推送服務本身不直接校驗公網訪問憑證，而是接收接入層完成鑑權後的會話上下文。因此，開發者只需要關注 WebSocket 連接後的首幀鑑權、鑑權結果處理和後續事件接收，不需要也不應傳入內部會話字段。

前置條件 ​

開始前請確認已經完成以下準備：

  1. 已根據 快速開始 獲取可用的訪問憑證。
  2. 已連接 WebSocket Trade 地址：
text
wss://webapi-trade.moomoo.com
  1. 當前賬號已具備交易權限。權限會影響實際能接收到的事件範圍。

鑑權方式 ​

WebSocket 交易推送支持兩類接入方式：

方式推薦程度適用場景說明
OAuth 2.1 + PKCE推薦第三方應用、桌面應用、移動端應用、Web 應用等需要用戶授權的場景使用 access_token 作為 Bearer Token 完成 WebSocket 登錄鑑權。
API Key兼容服務端自有系統、後端任務、內部工具等由開發者自行管理密鑰的場景使用 AppKey、時間戳、隨機串和簽名完成 WebSocket 登錄鑑權。

推薦使用 OAuth

OAuth 方式無需在客戶端保存 API 私鑰，也無需為每次接入手工管理簽名材料。除非已有服務端 API Key 接入或有明確兼容需求，建議優先使用 OAuth 2.1 + PKCE。

鑑權幀格式 ​

連接建立後，客戶端應將鑑權幀作為首個業務消息發送：

字段類型必填說明
actionstring是固定為 auth。
data.auth_typestring是鑑權類型。OAuth 使用 oauth2，API Key 使用 appkey。
data.authorizationstring是OAuth 場景傳 Bearer {access_token}；API Key 場景傳簽名結果。

OAuth 鑑權示例 ​

先按 快速開始：OAuth 2.1 + PKCE 獲取 access_token，再在 WebSocket 連接打開後發送以下 JSON：

json
{
  "action": "auth",
  "data": {
    "auth_type": "oauth2",
    "authorization": "Bearer {access_token}"
  }
}

說明：

  • authorization 必須包含 Bearer 前綴。
  • access_token 過期或無效時，鑑權會失敗。請使用 refresh_token 刷新後重新建立 WebSocket 連接並重新鑑權。
  • 請確認用戶授權範圍覆蓋交易事件讀取能力；權限不足時，連接後可能無法收到交易事件推送。

Token 安全

不要把 access_token、refresh_token 寫入前端可公開訪問的靜態配置、日誌或錯誤上報。服務端應用應使用安全存儲；桌面或移動端應用應使用系統密鑰鏈、加密存儲等機制。

API Key 鑑權示例 ​

API Key 方式適合服務端持有私鑰的場景。請先按 快速開始：傳統 API Key 創建 AppKey、上傳公鑰並安全保存私鑰。

WebSocket 鑑權幀的高層結構如下：

json
{
  "action": "auth",
  "data": {
    "auth_type": "appkey",
    "credential_id": "{app_key}",
    "authorization": "{signature_base64}",
    "timestamp_ms": 1782357937000,
    "nonce": "{nonce}"
  }
}

字段說明：

字段類型必填說明
credential_idstring是AppKey ID。
authorizationstring是使用 AppKey 私鑰生成的簽名結果，通常為 Base64 編碼後的簽名字符串。
timestamp_msint64是客戶端當前毫秒時間戳。
noncestring是客戶端隨機字符串，用於防重放。

API Key 簽名規則

WebSocket API Key 鑑權與 REST API Key 調用使用同一套 AppKey / 公鑰 / 私鑰身份體系，但簽名原文格式與 REST 不同。

WebSocket 鑑權簽名原文格式（字段間用 \n 分隔）：

text
{timestamp_ms}\n{nonce}\nWEBSOCKET\nws/auth

不要直接復用 REST 請求的簽名原文。

私鑰安全

API Key 私鑰只應保存在開發者自己的安全服務端或受控運行環境中。不要把私鑰下發到瀏覽器、移動端安裝包、客戶端配置文件或代碼倉庫。

鑑權結果處理 ​

客戶端發送鑑權幀後，應等待服務端返回鑑權結果，再期待接收交易事件推送。

建議按以下方式處理：

場景處理建議
鑑權成功記錄連接進入已鑑權狀態，等待服務端主動推送交易事件。
返回錯誤根據錯誤信息檢查 Token、AppKey、簽名、時間戳、權限等配置。
服務端關閉連接視為當前連接不可用。修正憑證或等待退避時間後重新連接、重新鑑權。
等待超時主動關閉連接並重試。避免在未知鑑權狀態下等待事件。

鑑權成功響應 ​

鑑權成功時，服務端返回以下 JSON：

json
{
  "id": "req-001",
  "session_id": "123456789",
  "server_time": 1782357937000000
}
字段類型說明
idstringEcho 請求 ID，請求未傳時省略。
session_idstring服務端分配的會話 ID。
server_timeint64服務器時間，微秒級時間戳。

當前接入層在鑑權成功後會建立後續事件推送所需的會話上下文。客戶端無需解析或傳遞內部路由字段，例如 uid、session_id、conn_id 等；這些字段由接入層和後端服務內部處理。

通道刷新 ​

鑑權成功後，可在已建立的連接上發送刷新幀以更新會話票據。刷新成功後，交易事件推送不中斷，繼續正常接收。

刷新頻率要求

客戶端應至少每 10 分鐘發送一次刷新幀。若超過 10 分鐘未主動刷新，服務端將主動斷開連接。建議以 5 分鐘為週期定時發送刷新幀，預留容錯次數。

OAuth 刷新 ​

使用 refresh_token 在後台換取新的 access_token 後，發送以下刷新幀：

json
{
  "action": "refresh",
  "data": {
    "authorization": "Bearer {new_access_token}"
  }
}

說明：

  • 建議在 Token 過期前主動刷新，避免因 Token 失效導致會話中斷。
  • authorization 必須包含 Bearer 前綴。

API Key 刷新 ​

json
{
  "action": "refresh",
  "data": {
    "credential_id": "{app_key}",
    "authorization": "{new_signature_base64}",
    "timestamp_ms": 1782357938000,
    "nonce": "{new_nonce}"
  }
}

說明：

  • timestamp_ms 和 nonce 必須使用與上次鑑權不同的新值，不能重複使用。
  • 簽名原文格式與初始鑑權相同：{timestamp_ms}\n{nonce}\nWEBSOCKET\nws/auth。

刷新成功響應 ​

刷新成功時，服務端返回與初始鑑權相同格式的響應：

json
{
  "id": "req-002",
  "session_id": "123456789",
  "server_time": 1782357938000000
}

session_id 保持不變，server_time 更新為當前服務器時間。

如果刷新失敗，請檢查新憑證是否有效；連續刷新失敗時，可關閉連接後用新憑證重新建立連接並重新鑑權。

連接生命週期建議 ​

  • 先鑑權再等待事件：每次新建 WebSocket 連接後，都應先發送鑑權幀，等待成功後再期待接收事件推送。
  • 斷線後重新鑑權：連接斷開後不要假設原連接的鑑權狀態仍然有效。請重新連接、重新鑑權。
  • 定時發送刷新幀：鑑權成功後，客戶端須每隔不超過 10 分鐘發送一次刷新幀，建議週期為 5 分鐘。超過 10 分鐘未刷新，服務端將主動斷開連接。OAuth 場景同時也應在 Token 過期前完成刷新；API Key 場景同樣需要定時刷新以維持會話。詳見 通道刷新。
  • 不要復用內部會話字段：服務端返回或日誌中可能出現的會話標識僅用於接入層和後端路由，不應作為公開參數持久化或復用。
  • 做好退避重試：連續鑑權失敗時，應檢查憑證配置並採用指數退避，避免高頻重連。

常見問題 ​

可以在一個連接上重新發送鑑權幀切換用戶嗎？ ​

不建議。一個 WebSocket 連接應對應一次明確的登錄鑑權上下文。如需切換用戶、賬號或憑證，請關閉舊連接，使用新憑證重新連接並重新鑑權。

OAuth 和 API Key 可以混用嗎？ ​

單次連接請選擇一種鑑權方式。OAuth 方式使用 auth_type=oauth2 和 Bearer Token；API Key 方式使用 auth_type=appkey 和簽名材料。不要在同一條鑑權幀中同時傳兩套憑證。

鑑權成功後為什麼收不到任何事件？ ​

鑑權成功僅代表連接合法，不代表賬戶有待處理的事件。交易事件推送是被動觸發的，有事件發生時服務端才會推送。如長時間未收到任何消息，可結合 連接保活 檢查連接是否仍然健康。

下一步 ​

  • 交易推送概覽 — 了解 WebSocket 交易推送能力和接入流程。
  • 訂閱機制 — 了解鑑權後事件推送的覆蓋範圍和行為說明。
  • 連接保活 — 處理 ping/pong、超時、斷線重連。
  • 數據格式 — 查看推送消息結構和字段說明。
  • 錯誤碼 — 排查鑑權和連接相關錯誤。