WebSocket connection¶

Evidence: ptrader-ws-gateway netty/WebSocketHandler.java, docs/WS_API_SPOT.md, Postman OpenAPI-WS folder.

Base¶

wss://<host> — [NEEDS-CONFIRMATION: public hostnames per environment]

Public market data (document these)¶

Path	Behaviour
`/openapi/quote/ws/v1/<streamName>`	Single stream; pre-subscribed
`/openapi/quote/stream?streams=a/b/c`	Combined mode; messages wrapped as `{ "stream", "data" }`

Examples:

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

Private user data¶

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

Create / keepalive / delete listenKey via REST (/openapi/v1/userDataStream, API key only). See Private user data.

Not in public docs scope¶

Path	Reason
`/user`, `/user/spot`, Cookie / post-handshake web auth	Exchange web BFF
`/ws`, `/ws/spot`, `/ws/future` (legacy aliases)	`[NEEDS-CONFIRMATION: whether any are externally published]` — omit from public guide until confirmed
`/openapi/ws/<listenKey>/future`	`[NEEDS-CONFIRMATION: Polaris future support]`

Heartbeat¶

Direction	Mechanism
Server → client	WebSocket Ping every 20s; respond with Pong within 120s or disconnect
Client → server	JSON `{"ping": <epochMs>}` → `{"pong": <epochMs>}`

Limits¶

Limit	Value
Max streams / connection	1024
Client messages	25 / s
No active subscriptions	disconnect after 60s

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

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

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

Success reply shape: { "result": null, "id": <n> } (or subscription list for LIST).

Legacy { "op": "subscribe", "args": [...] } is also accepted by the gateway (see handler / internal docs) but public examples use method / params.