行情推送 API

行情推送 API 使用 MQTT 協議進行數據推送，協議版本為 V3.1.1。MQTT 協議需要底層傳輸層提供有序、無丟失的字節流，從客戶端到伺服器、以及伺服器到客戶端。Webull 目前提供 TCP/IP 及 WebSocket 傳輸協議。透過使用此 API，您可以即時接收最新的市場資訊，協助您的交易策略即時應對特定的市場變化。

支援的市場及類別：

市場	資料類別
美國	Stocks, ETFs
香港	Stocks, ETFs
中国大陆	Stocks

支援的數據類型：

數據類型	說明
QUOTE	即時委託簿
SNAPSHOT	市場快照
TICK	成交明細

以下將介紹如何在不使用 Webull SDK 的情況下使用行情推送 API。

提示

如果您希望簡化獲取即時市場行情的流程，可以利用 Webull 提供的 SDK。請參考 SDK 使用者指南以及即時報價推送範例。

使用行情推送 API 的步驟

建立連線

MQTT 開源客戶端函式庫：

連線端點：

正式環境

// TCP/IP 協議: 
data-api.webull.hk:1883

// Websocket 協議:
wss://data-api.webull.hk:8883/mqtt

沙盒環境

// TCP/IP 協議: 
data-api.sandbox.webull.hk:1883

// Websocket 協議:
wss://data-api.sandbox.webull.hk:8883/mqtt

由於 MQTT 協議要求每個連線都需要唯一的客戶端識別碼（Client Identifier，ClientId），請建立一個 session_id 作為 MQTT CONNECT 封包中的 ClientId，這個識別碼也將會被用於後續的市場數據訂閱/取消訂閱操作。

注意

請不要在同一個 App Key 下，使用相同的 session_id 來建立多條連線。如果你嘗試使用相同的 session_id 進行連線，先前的連線將會被斷開，新的連線會取代原有連線。

若同一個 App Key 需要建立多條連線，請為每條連線使用不同的 session_id。另外請注意，每個 App Key 最多只能同時建立 5 條連線。如果超過限制，當嘗試建立新連線時，伺服器會回傳 105 錯誤碼。

連線關閉後，伺服器會保留連線的狀態資訊約 1 分鐘。如果在已建立 5 條連線後立即斷線並馬上嘗試重連，客戶端可能會收到 105 錯誤碼。此情況下，請等待 1 分鐘再嘗試重新連線。

當客戶端與伺服器建立網路連線後，客戶端發送給伺服器的第一個封包必須是 CONNECT 封包。CONNECT 封包需包含以下欄位與對應值:

ClientId： 事先產生的 session_id
User Name： 您的 App Key
Password： 任何值

如果伺服器收到格式正確的 CONNECT 封包，但因某些原因無法處理，伺服器將嘗試回傳一個 CONNACK 封包，並在其中包含下表中的非零連線回應碼。

回應碼	說明
0	連線成功
1	連線被拒絕，不支援的協議
2	連線被拒絕，`ClientId` 無效
3	`App Key` 為空
7	連線中斷
16	心跳逾時
100	未知錯誤
101	內部錯誤
102	已完成連線認證
103	連線認證失敗
104	`App Key` 無效
105	連線數量超出限制

訂閱／取消訂閱

成功建立 MQTT 連線後，客戶端應使用 HTTP API 來訂閱或取消訂閱即時行情資料。只有在訂閱成功後，伺服器才會開始向客戶端推送即時行情資料。

訂閱相關的 HTTP API，請參考：訂閱

取消訂閱的 HTTP API，請參考：取消訂閱

注意

由於網路問題，客戶端與伺服器之間的連線可能會被動中斷。重新連線後，先前的行情資料訂閱不會自動恢復，客戶端需要再次使用訂閱 API，才能恢復資料串流。

解析訊息

訂閱請求成功後，MQTT 客戶端的數據回調方法會被觸發。伺服器推送的數據包包含兩個部分：。

Topic（主題）： 用於標識推送的是哪種類型的數據。
Payload（數據體）： 即正在推送的即時數據。

Payload 數據採用 Protocol Buffers 協議或 JSON 格式進行序列化。請根據 Topic 解析對應的 Payload 數據。

各 Topic 對應的 Payload 如下

資料類型	topic	資料傳輸協議	說明
QUOTE	quote	即時委託簿 Proto	即時委託簿
SNAPSHOT	snapshot	行情快照 Proto	行情快照
TICK	tick	逐筆成交明細 Proto	逐筆成交明細
NOTICE	notice	通知 JSON	伺服器發送給用戶端的通知數據，用於伺服器向用戶端推送通知
ECHO	echo	空封包	伺服器發送給用戶端的空封包，用於驗證用戶端是否在線

Payload 資料格式定義

基礎 Proto

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

即時擺盤 Proto

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;
}

行情快照 Proto

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;
}

逐筆明細 Proto

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

通知 JSON

// Status Notification
{
  "type": "status",      // Notification type
  "rtt": 100,            // RTT to server
  "drop": 0,             // Number of packets dropped by server
  "sent": 0,             // Number of packets sent by server
}

使用行情推送 API 的步驟

建立連線​

訂閱／取消訂閱​

解析訊息​

Payload 資料格式定義​

基礎 Proto​

即時擺盤 Proto​

行情快照 Proto​

逐筆明細 Proto​

通知 JSON​