跳至主要内容

Data Streaming API

Data Streaming API 使用 MQTT 協議（v3.1.1）透過 TCP/IP 或 WebSocket 推送即時行情數據。用於接收即時報價、快照和逐筆成交數據。

如需按需 HTTP 查詢，請參閱 Data API。

SDK 用戶

Webull SDK 會自動處理 MQTT 連接、認證和訊息解析。請參閱快速入門中的即時串流範例。以下步驟適用於不使用 SDK 的手動整合。

支援的數據​

市場標的類型
香港股票、ETF
美國股票、ETF
中國大陸A 股（滬深港通）
數據類型說明
QUOTE即時買賣盤
SNAPSHOT市場快照
TICK逐筆成交明細

步驟 1：建立 MQTT 連接​

連接端點​

環境協議端點
正式環境TCP/IPdata-api.webull.hk:1883
正式環境WebSocketwss://data-api.webull.hk:8883/mqtt
沙盒環境TCP/IPdata-api.sandbox.webull.hk:1883
沙盒環境WebSocketwss://data-api.sandbox.webull.hk:8883/mqtt

MQTT 客戶端庫​

CONNECT 封包欄位​

欄位值
ClientId您建立的唯一 session_id（也用於訂閱/取消訂閱呼叫）
User Name您的 App Key
Password任意值
連接規則
  • 不要在同一個 App Key 下的多個連接中重用相同的 session_id。使用相同 session_id 的新連接會斷開前一個連接。
  • 每個 App Key 最多支援 5 個並發連接。超過此限制將返回錯誤碼 105。
  • 斷開連接後，伺服器會保留連接狀態約 1 分鐘。如果已達到 5 個連接上限，請等待 1 分鐘後再重新連接。
  • 伺服器每個連接每秒最多推送 3 次訊息。

連接錯誤碼​

錯誤碼說明
0連接已接受
1不可接受的協議版本
2無效的 ClientId
3App Key 為空
7連接丟失
16心跳超時
100未知錯誤
101內部錯誤
102連接已認證
103認證失敗
104無效的 App Key
105超過連接限制

步驟 2：訂閱行情數據​

建立 MQTT 連接後，使用 HTTP API 管理訂閱：

  • 訂閱 — 開始接收指定標的的即時數據
  • 取消訂閱 — 停止接收指定標的的數據
警告

如果連接因網路問題斷開，之前的訂閱不會自動恢復。重新連接後必須重新訂閱。

步驟 3：解析傳入訊息​

伺服器推送的每條訊息包含：

  • 主題（Topic） — 標識數據類型
  • 負載（Payload） — 實際數據，使用 Protocol Buffers 或 JSON 序列化

主題與負載對應關係​

數據類型主題負載格式說明
QUOTEquoteProtobuf即時買賣盤
SNAPSHOTsnapshotProtobuf市場快照
TICKtickProtobuf逐筆成交明細
NOTICEnoticeJSON伺服器通知
ECHOechoNull在線檢查（心跳）

Protobuf 訊息定義​

Basic（所有類型共用）​

message Basic {
    string symbol = 1;
    string instrument_id = 2;
    string timestamp = 3;
}

Quote（即時買賣盤）​

message Quote {
    Basic basic = 1;
    repeated AskBid asks = 2;
    repeated AskBid bids = 3;
}

message AskBid {
    string price = 1;
    string size = 2;
    repeated Order order = 3;
    repeated Broker broker = 4;
}

message Order {
    string mpid = 1;
    string size = 2;
}

message Broker {
    string bid = 1;
    string name = 2;
}

Snapshot（市場快照）​

message Snapshot {
    Basic basic = 1;
    string trade_time = 2;
    string price = 3;
    string open = 4;
    string high = 5;
    string low = 6;
    string pre_close = 7;
    string volume = 8;
    string change = 9;
    string change_ratio = 10;
    string ext_trade_time = 11;
    string ext_price = 12;
    string ext_high = 13;
    string ext_low = 14;
    string ext_volume = 15;
    string ext_change = 16;
    string ext_change_ratio = 17;
    string ovn_trade_time = 18;
    string ovn_price = 19;
    string ovn_high = 20;
    string ovn_low = 21;
    string ovn_volume = 22;
    string ovn_change = 23;
    string ovn_change_ratio = 24;
}

Tick（逐筆成交明細）​

message Tick {
    Basic basic = 1;
    string time = 2;
    string price = 3;
    string volume = 4;
    string side = 5;
}

通知（JSON）​

{
  "type": "status",
  "rtt": 100,
  "drop": 0,
  "sent": 0
}

下一步​

MQTT 連接建立並完成訂閱後，您將即時接收行情數據。使用 SDK 的完整範例請參閱 Market Data API 快速入門指南。

如果遇到連接或數據傳輸問題，請參閱更多資源獲取支援渠道。