WebSocket 连接

证据：ptrader-ws-gateway netty/WebSocketHandler.java、docs/WS_API_SPOT.md、Postman OpenAPI-WS 文件夹。

Base

wss://<host> — [NEEDS-CONFIRMATION: 各环境公网域名]

公开行情（文档收录）

Path	行为
/openapi/quote/ws/v1/<streamName>	单流；握手即订阅
/openapi/quote/stream?streams=a/b/c	组合模式；消息包装为 { "stream", "data" }

示例：

wss://<host>/openapi/quote/ws/v1/btcusdt@aggTrade
wss://<host>/openapi/quote/stream?streams=btcusdt@aggTrade/btcusdt@depth20

私有用户数据

wss://<host>/openapi/ws/<listenKey>/spot

通过 REST 创建 / 续期 / 删除 listenKey（/openapi/v1/userDataStream，仅 API Key）。见 私有用户流。

不在公开文档范围

Path	原因
/user、/user/spot、Cookie / 握手后 web 鉴权	交易所 Web BFF
/ws、/ws/spot、/ws/future（遗留别名）	[NEEDS-CONFIRMATION: 是否对外发布] — 确认前不写入公开指南
/openapi/ws/<listenKey>/future	[NEEDS-CONFIRMATION: Polaris 是否支持 future]

心跳

方向	机制
服务端 → 客户端	WebSocket Ping 每 20s；须在 120s 内 Pong，否则断开
客户端 → 服务端	JSON {"ping": <epochMs>} → {"pong": <epochMs>}

限制

限制	值
每连接最大流数	1024
客户端消息	25 / s
无活跃订阅	60s 后断开

订阅 / 退订（coins.ph 风格）

{ "method": "SUBSCRIBE", "params": ["btcusdt@aggTrade"], "id": 1 }

{ "method": "UNSUBSCRIBE", "params": ["btcusdt@aggTrade"], "id": 2 }

{ "method": "LIST_SUBSCRIPTIONS", "id": 3 }

成功回复形如：{ "result": null, "id": <n> }（LIST 时为订阅列表）。

网关亦接受遗留 { "op": "subscribe", "args": [...] }，公开示例统一使用 method / params。