T&Q行情(深度)-ws - 长尾猴量化 API

快速开始

确认权限与订阅上限：GET https://rest.vvtr.com/v1/my/permissions?mobile={手机号}&apikey={apiKey}

建立 WebSocket 连接（必须启用 permessage-deflate 压缩）

每 50 秒发送文本 ping 保活，持续接收推送

接口说明

协议类型: WebSocket（wss），URL 参数 apiKey 鉴权

连接限制: 每个 apiKey 仅允许维持 1 个有效连接

心跳机制: 文本 ping 续命 + Ping/Pong 探活，详见下方"心跳与连接探测"

推送频率: 实时推送成交/盘口有变化的标的

推送范围: 交易日集合竞价开始推送；美股等有盘前盘后时段的品种，盘前/盘中/盘后持续推送

压缩协议: 强制 permessage-deflate（RFC 7692）

握手必须携带 Sec-WebSocket-Extensions: permessage-deflate，否则返回 HTTP 400，不建立连接

协商结果统一为 permessage-deflate; server_no_context_takeover; client_no_context_takeover

400 响应示例：

{
  "code": 400,
  "msg": "WebSocket连接必须启用permessage-deflate压缩",
  "detail": "请使用支持RFC 7692的客户端，并在握手中提供兼容的Sec-WebSocket-Extensions",
  "required_extension": "permessage-deflate"
}

心跳与连接探测

服务端 60 秒内未收到任何消息会自动断开连接。心跳分两种，作用不同，必须配合使用：

方式	客户端动作	服务端行为	用途
续命心跳	每 50 秒发送文本 `ping`	刷新读超时与连接有效期，不回复	保活，必须
探活（协议层）	发送 WebSocket 协议 Ping 帧	自动回复 Pong 帧	检测连接与网络是否存活
探活（应用层）	发送 `{"type":"ping"}`	回复 `{"type":"pong"}`	同上，适合 JSON 客户端

文本 ping 没有任何回复，客户端不应等待回复来判断连接状态

探活超时未收到 Pong / pong（建议 20 秒），应主动断开并重连

协议层 Ping 不会延长连接有效期，不能替代文本 ping 续命

订阅规则

订阅在建立连接时通过 URL 参数 type、symbols 指定，连接后不支持动态订阅/退订

symbols 多个用 , 分隔；* 表示订阅该品种全部 symbols（需开通对应权限）

同时订阅多个品种时，symbols 用 [...] 分组并与 type 顺序一一对应：
type=11,22&symbols=[000001,600000],[AAPL,TSLA]

单连接最多订阅 2000 个标的，或单个品种全部 symbols（以套餐 limit 为准）

支持的品种类型

type	品种
11	A股
12	基金（上证）
13	债券（上证）
14	国内期货
16	指数（上证）
21	美股票
22	美股 ETF
24	CME 期货
31	加密币
32	外汇

type=23（美期权）当前无 WebSocket 推送，请勿订阅。

请求

wss://rest.vvtr.com/v2/connect?apiKey={apiKey}&type={type}&symbols={symbols}

请求参数

参数	类型	必填	说明
apiKey	string	是	你的 apiKey
type	string	是	产品类型代码，多个用 `,` 隔开，如 `11,22`
symbols	string	是	证券代码，多个用 `,` 分隔，`*` 表示全部；多 type 时用 `[a,b,c],[d,e,f]` 分组且顺序与 type 一致

客户端示例（均已启用压缩）

Python（websockets 库）

Java（Java-WebSocket）

wscat

# 较新版本的 wscat（基于 Node ws）默认启用压缩
# 若连接返回 400，请先升级 wscat：npm install -g wscat@latest
wscat -c "wss://rest.vvtr.com/v2/connect?apiKey=abcdefg&type=11&symbols=*"

Go（gorilla/websocket）

浏览器

浏览器自动协商压缩，无需配置：

返回数据结构说明

推送为对象数组，即使只有一条数据也是数组。不同品种的返回字段不同，请查看对应返回结构文档：

type	返回结构文档
11 / 12 / 13 / 16（A股、基金、债券、指数）	https://doc.vvtr.com/7174672m0
14（国内期货 5 档）	https://doc.vvtr.com/7894191m0
21 / 22（美股 / ETF）	https://doc.vvtr.com/8947414m0
24（CME 期货）	https://doc.vvtr.com/8947558m0
31（加密币）	https://doc.vvtr.com/8964478m0
32（外汇）	https://doc.vvtr.com/8964156m0

注意事项

🔔 心跳组合：文本 ping 每 50 秒续命（服务端不回复）+ 探活心跳检测死链，两者缺一不可，详见"心跳与连接探测"

📌 订阅仅在连接时生效：如需更换订阅，请断开后用新参数重连（每个 apiKey 同时只允许 1 个连接）

⏳ 无历史快照：连接建立后不会推送历史或当前快照，该标的第一条推送需等待下一次行情变化

🛡️ 权限：超出套餐权限或 limit 上限时连接会被拒绝或断开，请先通过 /v1/my/permissions 确认

🗜️ 压缩开关速查：Python websockets、Node ws、浏览器默认已开启；Go 必须设 EnableCompression=true；Java 必须使用 PerMessageDeflateExtension

✅ 验证协商结果：连接成功后检查握手响应的 Sec-WebSocket-Extensions，应包含 permessage-deflate

Trades行情(深度)-ws

快速开始#

接口说明#

心跳与连接探测#

订阅规则#

支持的品种类型#

请求#

请求参数#

客户端示例（均已启用压缩）#

Python（websockets 库）#

Java（Java-WebSocket）#

wscat#

Go（gorilla/websocket）#

浏览器#

返回数据结构说明#

注意事项#