訂閲與反訂閲

客户端完成 WebSocket 連接和登錄鑑權後，可以通過訂閲消息聲明需要接收的行情類型。訂閲成功後，服務端會在行情變化時按消息類型推送數據；不再需要某類數據時，應及時發送反訂閲消息釋放訂閲配額。

INFO

本頁說明客户端可見的訂閲協議形態。服務端內部可能會將標的代碼轉換為內部標識並附加會話、權限、配額等上下文，這些內部字段不是客户端需要傳入的參數。

請求格式

訂閲和反訂閲請求都是 JSON 對象，通過已鑑權的 WebSocket 連接發送。

json

{
  "id": "req-001",
  "action": "subscribe",
  "quote": ["US.AAPL", "HK.00700"],
  "order_book": ["US.AAPL"],
  "ticker": ["US.AAPL"],
  "kline": [
    {
      "symbol": "US.AAPL",
      "period": "1m",
      "adjust": "none"
    }
  ]
}

字段說明

字段	類型	必填	說明
`id`	string	建議填寫	客户端請求 ID。服務端應答會回傳該字段，便於客户端匹配請求與結果。
`action`	string	是	操作類型。可取 `subscribe` 或 `unsubscribe`。
`quote`	string[]	否	訂閲或反訂閲基礎報價。數組元素為標的代碼。
`order_book`	string[]	否	訂閲或反訂閲買賣盤。數組元素為標的代碼。
`ticker`	string[]	否	訂閲或反訂閲逐筆成交。數組元素為標的代碼。
`kline`	object[]	否	訂閲或反訂閲當前 K 線。每個元素由 `symbol`、`period`、`adjust` 組成。

一次請求可以同時包含多個行情類型。未出現的字段表示本次請求不處理該類型。

action

訂閲指定標的和行情類型。訂閲成功後，後續推送消息會通過同一條 WebSocket 連接返回。

json

{
  "id": "sub-quote-001",
  "action": "subscribe",
  "quote": ["US.NVDA"],
  "order_book": ["US.NVDA"]
}

unsubscribe

反訂閲指定標的和行情類型。反訂閲成功後，服務端不再為當前連接推送對應數據。

json

{
  "id": "unsub-quote-001",
  "action": "unsubscribe",
  "quote": ["US.NVDA"],
  "order_book": ["US.NVDA"]
}

反訂閲應儘量精確傳入不再需要的類型和標的。例如只關閉 K 線，不影響基礎報價：

json

{
  "id": "unsub-kline-001",
  "action": "unsubscribe",
  "kline": [
    {
      "symbol": "US.NVDA",
      "period": "1m",
      "adjust": "none"
    }
  ]
}

標的代碼格式

訂閲請求使用統一標的代碼格式：

text

{market}.{code}

常見示例：

市場	示例	說明
港股	`HK.00700`	港股代碼通常保留前導 0。
美股	`US.AAPL`	美股使用股票代碼。
A 股通	`SH.600519`、`SZ.000001`	滬深市場按交易所前綴區分。
北交所	`BJ.830799`	北交所市場。

不同市場、品類和權限檔支持的行情類型可能不同。若訂閲的標的或類型超出權限範圍，服務端可能返回權限或配額相關錯誤。

K 線參數

kline 數組中的每一項表示一個 K 線訂閲維度：同一標的的不同週期、不同復權方式是不同訂閲。

json

{
  "symbol": "US.AAPL",
  "period": "1m",
  "adjust": "none"
}

字段	類型	必填	說明
`symbol`	string	是	標的代碼，例如 `US.AAPL`。
`period`	string	是	K 線週期。
`adjust`	string	否	復權方式。未填寫時通常按 `none` 處理。

支持的週期

常用週期包括：

週期	說明
`1m`	1 分鐘
`3m`	3 分鐘
`5m`	5 分鐘
`10m`	10 分鐘
`15m`	15 分鐘
`30m`	30 分鐘
`60m`	60 分鐘
`120m`	120 分鐘
`180m`	180 分鐘
`240m`	240 分鐘
`1D`	日 K
`1W`	周 K
`1M`	月 K
`1Q`	季 K
`1Y`	年 K

部分市場或品類可能支持帶後綴的擴展週期，例如盤前盤後、夜盤等場景。是否可用以實際權限和服務端返回為準。

復權方式

值	說明
`none`	不復權。
`forward_exclude_dividend`	前復權，不包含現金分紅調整。
`forward_include_dividend`	前復權，包含現金分紅調整。
`forward`	兼容寫法，通常按 `forward_exclude_dividend` 處理。

示例

訂閲基礎報價、買賣盤和逐筆成交

json

{
  "id": "sub-realtime-001",
  "action": "subscribe",
  "quote": ["US.NVDA", "US.AAPL"],
  "order_book": ["US.NVDA"],
  "ticker": ["US.NVDA"]
}

訂閲成功後，可能收到的推送類型包括：

QUOTE：基礎報價。
ORDER_BOOK：買賣盤。
TICKER：逐筆成交。
BROKER_QUEUE：經紀隊列。該類型通常由部分港股買賣盤能力衍生，不需要單獨在請求中填寫 broker_queue 字段。
MARKET_STATE：市場狀態。該類型為市場維度狀態信息，可能由服務端基於連接、市場和權限推送，不作為普通標的訂閲字段傳入。

訂閲 K 線

json

{
  "id": "sub-kline-001",
  "action": "subscribe",
  "kline": [
    {
      "symbol": "US.NVDA",
      "period": "1m",
      "adjust": "none"
    },
    {
      "symbol": "US.NVDA",
      "period": "1D",
      "adjust": "forward_exclude_dividend"
    }
  ]
}

訂閲成功後，服務端會按 K 線維度推送 KLINE 消息。推送數據中會包含 period、adjust 和 kl_list，字段結構詳見數據格式。

切換 K 線週期

切換週期時，建議先反訂閲舊週期，再訂閲新週期，避免同時佔用多個不需要的 K 線訂閲。

json

{
  "id": "unsub-kline-1m-001",
  "action": "unsubscribe",
  "kline": [
    {
      "symbol": "US.NVDA",
      "period": "1m",
      "adjust": "none"
    }
  ]
}

json

{
  "id": "sub-kline-5m-001",
  "action": "subscribe",
  "kline": [
    {
      "symbol": "US.NVDA",
      "period": "5m",
      "adjust": "none"
    }
  ]
}

反訂閲全部常用類型

json

{
  "id": "unsub-all-001",
  "action": "unsubscribe",
  "quote": ["US.NVDA"],
  "order_book": ["US.NVDA"],
  "ticker": ["US.NVDA"],
  "kline": [
    {
      "symbol": "US.NVDA",
      "period": "1m",
      "adjust": "none"
    },
    {
      "symbol": "US.NVDA",
      "period": "1D",
      "adjust": "forward_exclude_dividend"
    }
  ]
}

應答格式

訂閲和反訂閲請求通常會返回一條應答消息，用於表示本次請求是否被接受。應答會回傳請求中的 id。

json

{
  "id": "sub-realtime-001",
  "code": 0,
  "message": ""
}

字段	類型	說明
`id`	string	對應請求中的 `id`。
`code`	number	結果碼。`0` 表示成功，非 `0` 表示失敗。
`message`	string	錯誤說明。成功時可能為空。

常見失敗原因包括：

未完成 WebSocket 登錄鑑權或會話已失效。
action 不是 subscribe 或 unsubscribe。
K 線 period 不支持或格式不正確。
標的代碼格式錯誤、標的不可訂閲或市場不支持該類型。
行情權限不足。
訂閲數量超過賬號或權限檔配額。
服務端臨時不可用或內部依賴異常。

錯誤排查詳見錯誤碼和頻率與配額。

行為說明

訂閲冪等性

客户端可以把同一標的、同一類型的重複訂閲視為冪等操作處理。為減少無效請求和配額佔用，仍建議客户端維護本地訂閲狀態，只在狀態變化時發送訂閲或反訂閲。

多類型訂閲

同一個標的可以同時訂閲 quote、order_book、ticker 和多個 kline 維度。服務端會按推送消息的 type 區分返回內容。客户端解析推送時不應假設不同類型消息按固定順序到達。

斷線重連

WebSocket 連接斷開後，不要假設原訂閲會自動恢復。客户端應按以下順序恢復：

重新建立 WebSocket 連接。
重新完成登錄鑑權。
根據本地保存的訂閲清單重新發送訂閲請求。
必要時通過 REST 實時行情接口補齊斷線期間的最新狀態。

反訂閲和配額釋放

離開頁面、切換標的、關閉不再需要的數據類型時，應主動反訂閲。訂閲配額通常按賬號、權限檔和訂閲維度管理；同一賬號在多個連接上的訂閲也可能共同影響可用配額。具體配額以賬號權限和服務端返回為準。

衍生推送類型

客户端請求字段只需要關注可訂閲類型：quote、order_book、ticker、kline。以下推送類型由服務端根據已訂閲能力、市場和權限決定是否返回：

推送類型	說明
`BROKER_QUEUE`	經紀隊列，主要與部分港股買賣盤能力相關。客户端不需要單獨傳入 `broker_queue` 訂閲字段。
`MARKET_STATE`	市場狀態，表示市場維度交易狀態。客户端應按 `type` 識別併兼容處理。

最佳實踐

為每個訂閲請求設置唯一 id，並在本地記錄請求狀態，便於超時重試和問題排查。
按頁面或業務模塊維護訂閲清單，進入時訂閲，離開時反訂閲。
建議每 5 分鐘定時重新發送一次訂閲請求，確保訂閲狀態與服務端保持同步。
切換 K 線週期或復權方式時，先反訂閲舊維度，再訂閲新維度。
對服務端推送做寬鬆解析：未知字段忽略，缺省字段按業務默認值處理。
對非 0 應答不要無限重試；權限不足、配額超限、參數錯誤應先修正請求或提示用户。
重連後重新鑑權並重新訂閲，不依賴舊連接上的訂閲狀態。

訂閲與反訂閲 ​

請求格式 ​

字段說明 ​

action ​

subscribe ​

unsubscribe ​

標的代碼格式 ​

K 線參數 ​

支持的週期 ​

復權方式 ​

示例 ​

訂閲基礎報價、買賣盤和逐筆成交 ​

訂閲 K 線 ​

切換 K 線週期 ​

反訂閲全部常用類型 ​

應答格式 ​

行為說明 ​

訂閲冪等性 ​

多類型訂閲 ​

斷線重連 ​

反訂閲和配額釋放 ​

衍生推送類型 ​

最佳實踐 ​

訂閲與反訂閲

請求格式

字段說明

action

subscribe

unsubscribe

標的代碼格式

K 線參數

支持的週期

復權方式

示例

訂閲基礎報價、買賣盤和逐筆成交

訂閲 K 線

切換 K 線週期

反訂閲全部常用類型

應答格式

行為說明

訂閲冪等性

多類型訂閲

斷線重連

反訂閲和配額釋放

衍生推送類型

最佳實踐