只保证接口数据正常输出，请勿以此作为投资唯一参考，否则后果自负，数据禁止二次分发，限个人开发者使用，接口必须在当地法律允许的条件下使用。

• 单个访问密钥允许的最大连接数为1。
• 产品和市场订阅数量以账号权限及服务限制为准。
• 单次订阅最大1次50个产品，可以多次发送或者按市场订阅。
• 不应重复订阅相同产品或市场。
• 全市场订阅的数据量较大，客户端必须持续读取并及时处理。
• 日志中不得记录完整 WebSocket 地址和访问密钥。
• WebSocket 连接必须长期响应心跳，避免被服务端断开。
• 重连与发送命令需要间隔5秒
• 注意：由于数据覆盖市场较多，不同市场之间字段有所差异，请勿严格验证所有字段的值，返回的格式一定要参数API的实际返回，而非文档参考值。我们并没有严格区分字符串和数字的格式，请在开发过程中，同时兼容字符串和数字格式。您将可以适用我们全部市场数据。总体返回内容可以参考字段内容
  本文档说明 WebSocket 服务的连接鉴权、产品订阅、市场订阅、实时行情、动态 K 线、心跳和断线重连。

接口说明

1. 开发指南

您需要在程序中完成以下功能

本文档说明 WebSocket 服务的连接鉴权、产品订阅、市场订阅、实时行情、动态 K 线、心跳和断线重连。

1. 接口信息

项目	内容
协议	WebSocket
主机	hk.psbangu.cn
端口	9017
连接地址	ws://hk.psbangu.cn:9017/websocket/json/{key}
消息编码	UTF-8
返回格式	JSON

2. 连接与鉴权

2.1 鉴权参数

参数	位置	类型	必填	实际参数	说明
key	URL Path	string	是	服务方分配的访问密钥	替换连接地址中的 {key}

不同密钥可使用的市场、产品和数据类型由账号权限决定。

2.2 连接流程

1. 使用包含访问密钥的完整地址建立 WebSocket 连接。
2. 等待 WebSocket 协议升级完成。
3. 等待服务端返回连接结果。
4. 确认连接和鉴权成功。
5. 发送产品订阅或市场订阅。
6. 持续接收行情，并维护心跳。

WebSocket 协议升级成功不代表鉴权成功。

2.3 连接结果

连接成功时，服务端返回：

只有收到 State=0 后，客户端才能发送订阅命令。

密钥无效或账号不可用时，服务端可能先完成协议升级，随后返回 State=-1 并关闭连接。

---

3. WebSocket 订阅命令

功能	命令格式
订阅产品	/sub/{symbols},{symbols}
订阅市场	/submkt/{markets},{markets}
应用层心跳	/heartbeat/PING

多个产品或市场使用英文逗号分隔。

---

4. 产品订阅

4.1 命令格式

/sub/{symbols}

4.2 请求参数

参数	类型	必填	实际参数	说明
symbols	string	是	AAPL 或 AAPL,TSLA	一个或多个产品代码

产品代码应使用产品列表接口返回的原始值。

4.3 多产品订阅

多个产品使用英文逗号分隔：

/sub/AAPL,TSLA,IBM,ACU,BTCUSDT

已验证产品：

当前产品订阅命令只包含产品代码，不包含市场代码。客户端应提前通过产品列表确认产品所属市场。

当前接口允许在同一条命令中提交不同市场的产品代码。

4.4 取消产品订阅

4.5 命令格式

/unsub/{symbols}

4.6 请求参数

参数	类型	必填	实际参数	说明
symbols	string	是	AAPL 或 AAPL,TSLA	一个或多个产品代码

产品代码应使用产品列表接口返回的原始

---

5. 市场订阅

5.1 命令格式

/submkt/{markets}

5.2 请求参数

参数	类型	必填	实际参数	说明
markets	string	是	NASDAQ 或 NASDAQ,NYSE,AMEX	一个或多个市场代码

多个市场使用英文逗号分隔：

/submkt/NASDAQ,NYSE,AMEX

市场订阅会接收该市场内账号有权限获取的实时行情，数据量通常明显高于产品订阅。

如果只需要少量产品，应优先使用产品订阅。

5.3 取消市场订阅

5.1 命令格式

/unsubmkt/{markets}

5.2 请求参数

参数	类型	必填	实际参数	说明
markets	string	是	NASDAQ 或 NASDAQ,NYSE,AMEX	一个或多个市场代码

多个市场使用英文逗号分隔：

/unsubmkt/NASDAQ,NYSE,AMEX

---

6. 订阅结果

服务端使用 bind 消息返回订阅结果。

字段	类型	说明
bind	string	订阅结果消息，实际值为 bind
Msg	array	每个产品或市场的订阅结果
Msg[].res	boolean	当前订阅是否成功
Msg[].type	string	symbol 表示产品，exchange 表示市场
Msg[].message	string	订阅结果说明

服务端会分别返回每个产品或市场的订阅结果。客户端必须逐项检查 Msg[].res。

同一批订阅中，部分项目可能成功，部分项目可能失败。

订阅失败可能由以下原因造成：

• 产品或市场代码错误；
• 账号没有相应权限；
• 订阅数量超过限制；
• WebSocket 尚未完成鉴权；
• 连接已经失效。

无效产品可能返回权限不足相关说明。客户端不能只根据错误文字判断产品不存在，还应核对产品列表和账号权限。

---

7. 实时行情

产品或市场订阅成功后，服务端开始推送实时行情。

实时行情消息的主要标识为：具体参考行情字段

常用行情字段：

字段	类型	说明
code	string	产品代码
Market	string	市场代码
price	number/string	最新价格
LP / lp	number/string/null	扩展交易时段价格或补充价格
open	number/string/null	开盘价
high	number/string/null	最高价
low	number/string/null	最低价
close	number/string/null	昨日收盘价或参考收盘价
volume	number/string/null	成交量
amount	number/string/null	成交额
change	number/string/null	涨跌额
up	number/string/null	涨跌幅
tick	integer	秒级时间戳
ticks	integer	毫秒级时间戳

不同市场的数值字段可能返回为 JSON 数字、数字字符串、空字符串或 null。客户端应先判断空值，再进行数值转换。

客户端应使用推送数据中的 Market 和 code 识别产品，不能依赖订阅顺序。

订阅成功后不一定立即收到行情。市场休市、产品没有新成交或账号未开通对应数据时，可能暂时没有推送。

---

8. 动态 K 线

账号开通动态 K 线权限后，服务端可能在产品订阅成功后推送 K 线消息。

动态 K 线消息的主要标识为：

字段	类型	实际值	说明
type	string	bars	动态 K 线消息
Msg	object	K 线数据	包含产品、市场及多个周期

支持的周期键：

周期键	周期
1	1 分钟
5	5 分钟
15	15 分钟
30	30 分钟
1h	1 小时
1d	1 日
1w	1 周
1m	1 月

K 线数据当前可能使用英文逗号拼接，字段顺序为：

时间,收盘价,开盘价,最高价,最低价,成交额,成交量

客户端解析前应确认字段是否为空，并按照周期键分别保存数据。

本次测试账号在订阅 BTCUSDT 后收到实时行情，但未观察到 bars 消息。该能力需要确认账号是否已开通动态 K 线权限。

---

9. 心跳

9.1 客户端心跳

应用层心跳命令为：

/heartbeat/PING

心跳成功时，服务端返回：

字段	实际值
Cmd	ping
Msg	ok

建议客户端每 10 秒发送一次应用层心跳。

9.2 服务端心跳

服务端没有收到心跳将会发送：

字段	实际值
Cmd	heartbeat
Msg	ping

客户端还必须处理 WebSocket 协议层 Ping 帧，并返回 Pong。

如果30秒没有收到任何数据或心跳响应，客户端应关闭旧连接并进入重连流程。

---

10. 断线与重连

连接断开后，客户端应：

1. 清理旧连接和心跳定时器。
2. 等待一段时间后重新连接。
3. 等待新的连接鉴权结果。
4. 鉴权成功后重新提交全部订阅。
5. 恢复心跳和行情处理。
6. 链接前请重新解析域名。

产品订阅和市场订阅只对当前连接有效。新连接不会自动继承旧连接的订阅状态。

建议逐步增加重连等待时间，避免在网络故障或鉴权失败时高频重试。

鉴权失败、账号停用或无权限时，应停止高频自动重连。

---

11. 使用限制

• 单个访问密钥允许的最大连接数为1。
• 产品和市场订阅数量以账号权限及服务限制为准。
• 单次订阅最大1次50个产品，可以多次发送或者按市场订阅。
• 不应重复订阅相同产品或市场。
• 全市场订阅的数据量较大，客户端必须持续读取并及时处理。
• 日志中不得记录完整 WebSocket 地址和访问密钥。
• WebSocket 连接必须长期响应心跳，避免被服务端断开。

---