Skip to content

WebSocket#

Real-time streams: order status, child orders, trades, positions, position risk, balances, market data. Read-only — orders are placed and cancelled through the REST API.

Authentication (listenKey)#

  1. Call GET /api/v2/trading/listenKey (signed like any REST call). Response body = listenKey, a JWT valid 1 hour.
  2. Connect to wss://<host>/api/v2/ws?listenKey=<listenKey> — or send Authorization: Bearer <listenKey> as a handshake header (keeps the token out of proxy logs).

Invalid/expired listenKey → handshake rejected with HTTP 401. Checked only at handshake; established connections are not dropped on expiry, but every reconnect needs a fresh key.

Keep-alive#

Server sends {"topic":"ping"} every minute — reply {"topic":"pong"}. No client message for 5 minutes → close 1001. Re-subscribe on every reconnect (subscriptions are per-connection).

Subscribing#

{"topic": "order", "exchange": "binance", "method": "subscribe"}
Parameter Description
topic order, child_order, trade, position, position_risk, balance, ticker, ohlcv, open_interest
exchange required; any trading exchange, case-insensitive
method subscribe / unsubscribe

One subscription per (topic, exchange) pair per connection.

Errors#

Code Meaning
0 OK — ack; message echoes your request
5 rate limit exceeded
8054 exchange missing or invalid
7002 invalid request — unparseable message or missing method
7001 internal error — stream terminated; re-subscribe