Perps WebSocket

One connection streams every perps channel: tickers, books, best bid/offer, trades, statistics, and candles.

wss://perps.polynode.dev/ws?key=pn_live_...

Authenticate with your normal polynode API key as the key query parameter. On connect you receive a hello frame listing the available channels and your subscription allowance, then you subscribe:

const ws = new WebSocket("wss://perps.polynode.dev/ws?key=pn_live_...");

ws.onopen = () => {
  ws.send(JSON.stringify({
    action: "subscribe",
    channels: ["perps_tickers", "perps_book:BTC-USD", "perps_trades:BTC-USD"],
  }));
};

ws.onmessage = (msg) => {
  const event = JSON.parse(msg.data);
  if (event.action === "subscribed") {
    console.log("subscribed:", event.channels, "rejected:", event.rejected);
    return;
  }
  console.log(event.channel, event.data);
};

Protocol

Message	Direction	Shape
Hello	server → you	{"status": "connected", "max_subscriptions": ..., "channels": [...]}
Subscribe	you → server	{"action": "subscribe", "channels": [...]}
Unsubscribe	you → server	{"action": "unsubscribe", "channels": [...]}
Ack	server → you	{"action": "subscribed", "channels": [...], "rejected": [...], "active_subscriptions": n}
Event	server → you	{"channel": "perps_tickers", "data": {...}}
Ping	you → server	{"action": "ping"} → {"action": "pong"}

Invalid channels come back in rejected with a reason — the rest of the batch still subscribes. Instruments can be referenced by id (6), symbol (BTC-USD), or bare asset (btc).

Authentication failures

A missing or invalid key does not silently drop the connection: the socket opens, you receive one error frame naming the problem, and the connection closes with an application close code — 4401 for a bad or missing key, 4429 when your plan’s connection limit is reached. If you see close code 4401, check the key query parameter first.

Event payloads use the same field names as the REST endpoints — a perps_tickers event carries the exact shape of /v3/perps/tickers/:instrument, so REST and WS code paths share models.

Connection limits

Per-key concurrent connections and channel subscriptions follow your plan — see rate limits. A single connection is enough for most platforms: perps_tickers alone covers every instrument.

Keep-alive and recovery

The server pings every 30 seconds; standard pong replies (automatic in browsers and most WS libraries) keep the connection alive. If your consumer falls behind, you receive {"warning": "lagged", "dropped_events": n} instead of silently missing data — resubscribe or refetch REST state for the affected instruments. Every delivered perps_book message is a complete snapshot — replace, don’t merge. A subscription acknowledgement confirms channel acceptance, not that a snapshot has already arrived; fetch the REST book when startup needs immediate state (channel details).