WebSocket Connecting

This is the WebSocket connection-start checklist. WebSocket Connection remains the broader connection reference. Connect to WebSocket when the workflow needs live messages or replay control. Use REST for a one-off snapshot or bounded historical pull where streaming order does not matter.

Minimal Connection

const ws = new WebSocket("wss://api.0xarchive.io/ws?apiKey=0xa_your_api_key");

ws.onopen = () => {
  ws.send(JSON.stringify({
    op: "subscribe",
    channel: "orderbook",
    symbol: "BTC"
  }));
};

This example is useful for a smoke test. A production client should keep the API key in a backend or secret-managed process, not in browser logs, copied URLs, or prompt transcripts.

Connection Checklist

Choose stream or replay

Decide whether the job needs live subscription messages, replay, or REST history before opening the socket.

Open with auth

Pass the API key through the environment or backend-controlled connection path.

Subscribe after open

Send subscription or replay commands only after the socket reaches the open state.

Handle every event class

Implement open, message, error, close, keep-alive, reconnect, and unsubscribe behavior.

Log connection state

Preserve active channels, symbols, retry count, close code, close reason, and restored subscriptions.

What To Decide Before Code

Decision	Why
Channel family	Prevents core, Spot, HIP-3, HIP-4, and Lighter mixups
Symbol format	Keeps pair symbols, builder prefixes, and outcome identifiers intact
Consumer capacity	Prevents message backlog and stale local state
Reconnect policy	Prevents tight reconnect loops
Gap policy	Decides whether a downstream job can continue

Connection State To Track

Keep connection state in one object rather than scattering it across callbacks.

Field	Store
`status`	connecting, open, closing, closed, reconnecting, or failed
`activeSubscriptions`	channel-symbol pairs that should be restored after reconnect
`lastMessageAt`	latest server message timestamp seen by the client
`retryCount`	reconnect attempts for the current outage
`close`	close code, reason, and whether the close was expected
`unsafeState`	local books, alerts, or replay outputs that need rebuild after a gap

This state makes the reconnect path deterministic. After a new socket opens, restore only the tracked subscriptions, restart keep-alive timers, and rebuild any local state marked unsafe.

Secret Handling Pattern

The URL example is a minimal smoke test. For shared tools, browser apps, and agent workflows, put the key in a backend-controlled process or secret store and keep it out of copied URLs. If an agent is generating code, ask it to show where the key is read, where the URL is constructed, and which logs are safe to keep.

Next Step

Use WebSocket Channels to choose subscriptions, Keep Alive for liveness and reconnect policy, and WebSocket Limits before scaling channel count.

Production Notes

Treat the first successful open event as a connection start, not as evidence that downstream state is usable. The client still needs an acknowledged subscription, message parser, heartbeat policy, reconnect behavior, and gap handling. For local book workflows, rebuild from a known snapshot when reconnects or missed messages make state ambiguous.

Documentation Index

​Minimal Connection

​Connection Checklist

​What To Decide Before Code

​Connection State To Track

​Secret Handling Pattern

​Next Step

​Production Notes