V5 API WebSocket 订阅参数与频道 URL 调整全解析

本次变更聚焦于 V5 API WebSocket 订阅参数、频道 URL 的优化升级，旨在提升 高频交易 场景下的低延迟与稳定性体验。请所有 实盘与模拟盘开发者 关注时间节点、检查代码兼容，并尽快完成迁移。

一、调整延期通知：多端并行更安心

原定 5 月底执行的 V5 API WebSocket 调整 已延期至 6 月 20 日 17:10–17:50（UTC+8）。经过技术团队的额外灰度验证，这一窗口期将最大限度降低对 市价单、网格策略、定投策略 等业务的影响。

提示：此时间段仅为分钟级切换，请在事前完成脚本验证，并确保重连与降级逻辑就绪。

二、订阅参数变动：`uly` → `instFamily`

2.1 为什么要替换？

旧版订阅使用 uly（underlying）字段，系统会隐式将其视为 instFamily。调优后的架构需要开发者 显式声明标识，以减少匹配歧义，进一步提升撮合引擎性能。

2.2 快速迁移三步走

在初始化 WebSocket 连接的 订阅 message 中，查找 uly 关键字。
将其字段名改为 instFamily，值保持不变（例如 USDT-USD-SWAP）。
在本地与模拟盘先跑单元测试——若返回 404 或 30012 错误码，说明仍有遗漏。

示例前后对比：

// 调整前（6 月 20 日后将返回参数错误）
{
  "op": "subscribe",
  "args": [{ "channel": "candle", "uly": "BTC-USDT" }]
}

// 调整后（推荐写法）
{
  "op": "subscribe",
  "args": [{ "channel": "candle", "instFamily": "BTC-USDT" }]
}

三、频道 URL 迁移：从 `/public` & `/private` 到 `/business`

3.1 涉及哪些频道？

高频量化、网格策略、定投系统常用的 大宗交易、策略委托、K 线与市场深度 频道，将全部迁移到 /business 路径。

典型应用：
- 大宗行情网格 通过 block-tickers 捕捉大单异动；
- 定投策略 监听 algo-recurring-buy 的委托回报；
- 回测系统 利用 candle 增量补全历史分钟线。

👉 立即核对代码：/business 路径切换检查清单

3.2 新版 URL 一览

实盘公共 & 私有共用
wss://ws.okx.com:8443/ws/v5/business
wss://wsaws.okx.com:8443/ws/v5/business
模拟盘公共 & 私有共用
wss://wspap.okx.com:8443/ws/v5/business?brokerId=9999

小提示： 使用负载均衡域名（如 wsaws）时，务必验证 DNS 更新是否生效；默认 TTL 为 30 秒，可在部署脚本中加 sleep 40 兜底。

四、迁移时间表：开发者自查表

阶段	任务	检查项	截止时间
灰度	参数替换自测	本地日志无 `uly`	6 月 15 日
预发	URL 切换测试	/business 重连失败率 <1%	6 月 18 日
正式	生产全量上线	连接监控 200ms 内建立	6 月 20 日 17:10

五、FAQ：迁移过程中的高频疑问

Q1：如果 6 月 20 日之后才想起要改，会出现什么后果？
A：旧路径将返回 403 Forbidden；未替换的 uly 字段会触发 30012 参数错误。
建議预先建“监控脚本”，在异常码出现时自动熔断并切换新配置。

Q2：我目前用的是 SDK，需要手动改 URL 吗？
A：大部分 官方 SDK (v1.9.0+) 已内置 /business 默认值，确认版本即可；老版本请手动升级或覆盖 WebSocketConfig。

Q3：模拟盘是否可以先行体验新频道？
A：可以！即日起，模拟盘 /business 已稳定运行，灰度无流量限制。
建议跑 24 小时压力测试，验证订阅数大于 100 时内存波动 <15%。

Q4：一分钟内多次重连会触发风控吗？
A：短连接高频重连会被判定为异常；推荐应用层使用 心跳保活（按 30/30/60 秒阶梯式重试），减少握手开销。

Q5：K 线频道 candle 的粒度是否会同步扩展？
A：此次仅迁移路径，粒度枚举不变（1m/3m/5m/15m/…1M）。若有新粒度需求，关注后续 v6 路线图。

Q6：网格子订单 grid-sub-orders 升级后字段会发生变化吗？
A：消息结构不变，新增 dealAvgPx（成交均价）便于做 盈亏对账。无需额外适配，仅增加字段解析即可。

六、最佳实践：让迁移更丝滑

批量校验
写一个 precommit 钩子脚本，专门扫描代码库里的 WebSocket URL 与订阅字段。
熔断策略
部署 nginx+uWSGI 做 TCP 探活，当 /business 返回 502 自动回退旧域名，避免人工干预。
日志分级
用 JSON 结构化日志打印 subscribeId，异常定位更快。

👉 升级前一键检验脚本＋配置模板下载

迁移虽短，但细节决定收益。祝各位开发者 低延迟、不丢单、稳盈利！