WebSocket Connection | 0xArchive Docs

Connection

Open one authenticated socket, answer the server heartbeat, and reuse the same session for subscriptions and replay.

Open the socket

Connect to wss://api.0xarchive.io/ws with your API key.

JavaScriptJavaScript

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

ws.onopen = () => {
  console.log("Connected to 0xArchive WebSocket");
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log("Received:", data);
};

PythonPython

import asyncio
import websockets
import json

async def connect():
    uri = "wss://api.0xarchive.io/ws?apiKey=0xa_your_api_key"
    async with websockets.connect(uri) as ws:
        print("Connected to 0xArchive WebSocket")
        async for message in ws:
            data = json.loads(message)
            print("Received:", data)

asyncio.run(connect())

Keep-alive

The server sends ping frames every 30 seconds. Clients that do not answer within 60 seconds are disconnected.

JavaScript

// Send a ping to keep connection alive
ws.send(JSON.stringify({ op: "ping" }));

// Server responds with:
// {"type": "pong"}

Command model

The same socket handles subscribe, unsubscribe, replay, and keep-alive commands.

Real-time Subscriptions

subscribe

Subscribe to a real-time channel

Params: channel, symbol

Send

{
  "op": "subscribe",
  "channel": "orderbook",
  "symbol": "BTC"
}

Receive

{
  "type": "subscribed",
  "channel": "orderbook",
  "symbol": "BTC"
}

unsubscribe

Unsubscribe from a channel

Params: channel, symbol

Send

{
  "op": "unsubscribe",
  "channel": "orderbook",
  "symbol": "BTC"
}

Receive

{
  "type": "unsubscribed",
  "channel": "orderbook",
  "symbol": "BTC"
}

Historical Replay

replay

Start historical replay. Use "channel" for single or "channels" (array) for multi-channel synchronized replay. All channels must be from the same exchange. Use interval for candles (1m-1w). Use granularity for lighter_orderbook.

Params: channel|channels, symbol, start, end, speed, [interval], [granularity]

Send

{
  "op": "replay",
  "channel": "trades",
  "symbol": "BTC",
  "start": 1704067200000,
  "end": 1704153600000,
  "speed": 10
}

Receive

{
  "type": "replay_started",
  "replay_id": "rpl_abc123",
  "channel": "trades",
  "symbol": "BTC",
  "speed": 10
}

replay.pause

Pause current replay

Params: -

Send

{
  "op": "replay.pause"
}

Receive

{
  "type": "replay_paused",
  "replay_id": "rpl_abc123"
}

replay.resume

Resume paused replay

Params: -

Send

{
  "op": "replay.resume"
}

Receive

{
  "type": "replay_resumed",
  "replay_id": "rpl_abc123"
}

replay.seek

Seek to specific timestamp

Params: timestamp

Send

{
  "op": "replay.seek",
  "timestamp": 1704100000000
}

Receive

{
  "type": "replay_seeked",
  "replay_id": "rpl_abc123",
  "timestamp": 1704100000000
}

replay.stop

Stop current replay

Params: -

Send

{
  "op": "replay.stop"
}

Receive

{
  "type": "replay_stopped",
  "replay_id": "rpl_abc123"
}

Utility

ping

Send a ping to keep connection alive (server responds with pong)

Params: -

Send

{
  "op": "ping"
}

Receive

{
  "type": "pong",
  "timestamp": "2026-01-01T12:00:00Z"
}