WebSocket

One socket carries market data and your account events: wss://…/v1/ws. The protocol is version 1, echoed in the auth acknowledgement so a client can detect a server it does not understand.

Channels

channel	carries	auth
prices	oracle prints for a feed (feedId) — the tick stream	no
stats	per-market stats each print: mark, funding rate, OI (marketId)	no
account	your account's events as they land in the log	yes

Client operations

Send JSON frames:

{ "op": "auth", "apiKey": "hb_…" }
{ "op": "subscribe", "channel": "prices", "feedId": "btc-usd" }
{ "op": "subscribe", "channel": "stats", "marketId": "btc-usd-perp" }
{ "op": "unsubscribe", "channel": "prices", "feedId": "btc-usd" }

Authenticate before subscribing to account. subscribe/unsubscribe are mirror images — shed a channel without reconnecting. The server echoes each subscription in an ack (with the feedId/marketId), and an invalid op comes back as an error frame carrying the machine code and the offending op so you can correlate it.

Heartbeat and staleness

The server emits a heartbeat frame ({"op":"ping"}) on a fixed cadence, so a quiet feed is distinguishable from a dead socket. You may reply with {"op":"pong"} (accepted as a harmless no-op) or ignore it — the server does not require a reply and does not close a socket that stays silent.

Every price/stats frame carries the oracle timestamp and a staleness input. A live figure must either be live or look dead: if the socket goes quiet past the staleness threshold, render your mark/funding/OI as visibly stale rather than showing a last-known value with live confidence.

Reconnect doctrine

On reconnect, do not trust the stream to backfill the gap. Take a REST snapshot first (the relevant GET /v1/*), then resume the stream, and dedup on the event seq — the same monotonic sequence number the account channel and the history endpoints share, so history↔live dedup is one comparison. Frames you do not recognise (a newer server, an additive field) must be ignored, not treated as an error: the protocol evolves additively (see Changelog).