Skip to main content
Use WebSocket when you need a stream instead of a single REST response. The same authenticated socket accepts live subscription and replay commands, but support is channel-specific.
Lighter live subscriptions are available on lighter_orderbook, lighter_trades, lighter_open_interest, and lighter_funding through wss://api.0xarchive.io/ws. lighter_candles and lighter_l3_orderbook are replay-only, and all six Lighter channels support historical replay. See Lighter WebSocket channels.Lighter on Robinhood Chain live subscriptions are available on rh_lighter_orderbook, rh_lighter_trades, rh_lighter_open_interest, and rh_lighter_funding through wss://api.0xarchive.io/ws. rh_lighter_candles is replay-only, and all five Robinhood Chain channels support historical replay. See Lighter on Robinhood Chain.
The open event confirms that the transport and authentication handshake succeeded. It does not confirm that a channel or replay request is supported. Wait for subscribed after subscribe, or replay_started after replay, and handle error for rejected operations.

Connect

Decide what to set before you connect, then open the socket, authenticate, keep it alive, and reconnect cleanly.

Keep alive

Ping/pong, idle timeout, backoff, and resubscription discipline.

Channels

Choose channel-specific live subscriptions or historical replay by venue family, including the live and replay-only Lighter channels.

Real-time streams

Choose WebSocket when live updates and sequence matter.

L4 order book

Maintain stateful L4 books with snapshots, diffs, gaps, and replay.

Lighter channels

Stream live Lighter order books, trades, open interest, and funding, and parse each live payload.

Replay

Replay supported historical sequences with the delivery model for the selected channel.

Backtesting

Use replay windows for deterministic research and strategy checks.

Message schema

Use documented command and event shapes for clients and agents.

Limits

Size subscriptions, replay jobs, and reconnection behavior for your plan.

Tier limits

Match subscription count, standard replay speed, and concurrency to plan limits.

Latency, freshness, and infrastructure boundaries

The canonical customer endpoint is wss://api.0xarchive.io/ws. Current WebSocket health is an HTTP service check, not a client connection-time or round-trip measurement. The service does not publish a stable numeric WebSocket latency claim. Keep these measurements separate: HTTP service health, server-side REST handler timing, stored-data freshness, ingest lag, WebSocket upgrade/connect time, application ping/pong round-trip time, and client processing lag. In the data-quality response, websocket.current_ms is the latest stored order-book freshness value, not client WebSocket round-trip time. There is no published end-to-end WebSocket latency percentile today. A client can measure one session with the native application ping/pong messages. Send {"op":"ping"} and time the response {"type":"pong"}. That result describes the requesting client’s path and processing, not a platform-wide claim. 0xArchive does not sell a general Hyperliquid node or RPC service and does not publish deployment topology here. The docs do not make region, co-location, or root-cause claims about infrastructure.

Server-Side Node.js Smoke Test

Keep WebSocket credentials on the server. Browser WebSocket clients cannot set a custom Authorization header, so browser apps should connect through your backend. Never expose a real API key in browser code, public prompts, logs, screenshots, or shared notebooks. The server-side header form is Authorization: Bearer $OXARCHIVE_API_KEY; load the real value from a server-side secret store before sending it.

When To Use WebSocket

Use WebSocket when sequence matters. Live subscriptions are useful for monitors, dashboards, and local books that need updates after an initial state. Replay is useful for backtests, incident review, reconstruction, and workflows where event order carries meaning. If the job only needs one current order-book snapshot or one bounded trade list, REST is usually simpler and easier to retry. For a Hyperliquid-focused overview of live channels, replay delivery models, and depth choices, start with the Hyperliquid WebSocket Streaming API. Every WebSocket client should implement four paths: open and authenticate, subscribe or start replay, handle messages, and recover from close or gap signals. A client that only handles happy-path messages will eventually corrupt a local stateful workflow. Keep reconnection and resubscription explicit, and route gap handling to the same data-quality policy used by REST jobs.

Stream Execution Checklist

Before writing WebSocket code or handing the task to an agent, capture the stream checklist. If the checklist is incomplete, start with REST or a one-channel sample instead of a broad streaming client.

Contract Boundaries

WebSocket is a command-and-event surface. Client commands use op values such as subscribe, unsubscribe, replay, replay.pause, replay.resume, replay.seek, replay.stop, and ping. The legacy stream and stream.stop commands remain parseable by some SDKs but currently return an error because bulk WebSocket streaming was discontinued. Use the Data Catalog for large file delivery. Use WebSocket message schema before building typed handlers. Do not infer event names from replay-control command names. replay.pause is a client command, while replay_paused is a server event. For standard replay, the successful sequence is replay_started, historical_data records, and replay_completed, with gap_detected notifications when applicable. A multi-channel replay sends replay_snapshot baselines before its timeline. Core L4 replay sends replay_started, then one l4_snapshot, then ordered l4_batch messages, and finally replay_completed; its speed value is ignored and replay.seek returns an error.

Message Discipline

Do not mix venue families inside one channel assumption. A HIP-3 channel should use HIP-3 symbols such as km:US500. Lighter channels should stay in the Lighter namespace. If the stream feeds a model, alert, or strategy harness, store enough message metadata to reconstruct what channel, symbol, time window, and request produced the state.

Choosing Between REST And WebSocket

Use WebSocket when sequence matters or live updates drive the job. Use REST when a single snapshot or bounded historical window answers the question. If local state, replay order, or continuous updates matter, WebSocket is the right surface. If not, a REST call is simpler to retry and audit.
Last modified on September 26, 2026