订阅与反订阅

客户端完成 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 线周期

反订阅全部常用类型

应答格式

行为说明

订阅幂等性

多类型订阅

断线重连

反订阅和配额释放

衍生推送类型

最佳实践