WebSocket protocol

All messages are JSON text frames. The current protocol version is v1. Every server message has a type and a ts (server time in ms). The message reference below shows every message's JSON and explains each field.

Connection lifecycle

1. Connect to /ws (optionally with ?subscribe=ch1,ch2).
2. The server sends welcome.
3. You send subscribe. For each new channel the server replies with subscribed, then a snapshot.
4. The server streams ticker / agg deltas until you unsubscribe or disconnect.

Client → server

{ "op": "subscribe", "channels": ["ticker:SOLUSDT"] }
{ "op": "unsubscribe", "channels": ["ticker:SOLUSDT"] }
{ "op": "ping" }

Server → client

Timestamps

All timestamps are Unix epoch milliseconds from the server's clock.

Message reference

welcome

Sent once, right after you connect.

{
  "type": "welcome",
  "ts": 1731400000000,
  "version": "v1",
  "channels": ["agg:*", "ticker:<SYMBOL>"],
  "pairs": ["BTCUSDT", "ETHUSDT", "SOLUSDT"],
  "exchanges": ["binance", "bybit", "okx"],
  "limits": {
    "max_subscriptions": 200,
    "max_connections_per_ip": 10,
    "ticker_interval_ms": 0,
    "agg_interval_ms": 1000
  },
  "docs": "/docs",
  "disclaimer": "For informational purposes only. Not investment advice. See /terms"
}

subscribed / unsubscribed

Confirms a subscribe or unsubscribe request. It lists only the channels that actually changed.

{ "type": "subscribed", "ts": 1731400000012, "channels": ["ticker:BTCUSDT", "agg:*"] }

snapshot (ticker channel)

The full current state of one pair, sent right after you subscribe and again if your connection falls behind. Replace your local state for that pair.

{
  "type": "snapshot",
  "ts": 1731400000013,
  "channel": "ticker:BTCUSDT",
  "s": "BTCUSDT",
  "data": [
    { "ex": "binance", "b": 97012.5, "a": 97012.51, "bq": 3.214, "aq": 0.82, "t": 1731400000001 },
    { "ex": "okx", "b": 97011.9, "a": 97012.0, "bq": 0.51, "aq": 1.07, "t": 1731399999987, "et": 1731399999861 }
  ]
}

ticker

Real-time updates for one pair. Each message contains only the exchanges whose quote changed: merge them into your state by ex.

{
  "type": "ticker",
  "ts": 1731400000140,
  "channel": "ticker:BTCUSDT",
  "s": "BTCUSDT",
  "data": [
    { "ex": "okx", "b": 97012.1, "a": 97012.2, "bq": 0.33, "aq": 2.4, "t": 1731400000139, "et": 1731400000012 }
  ]
}

snapshot (agg:*)

The current summary of all pairs, sent right after you subscribe to agg:*. Replace your local state.

{
  "type": "snapshot",
  "ts": 1731400000000,
  "channel": "agg:*",
  "data": [
    { "s": "BTCUSDT", "p": 97012.3, "bb": 97014.0, "bbx": "kraken", "bbq": 0.42, "ba": 97011.8, "bax": "bybit", "baq": 1.37, "sp": -0.0023, "n": 11, "ch": 1.84, "v": 1834455120, "t": 1731399999990 }
  ]
}

agg

Sent every second with only the pairs that changed: merge by s. A row with n: 0 means the pair is currently unavailable, so remove it.

{
  "type": "agg",
  "ts": 1731400001000,
  "channel": "agg:*",
  "data": [
    { "s": "ETHUSDT", "p": 3561.2, "bb": 3561.3, "bbx": "okx", "bbq": 4.1, "ba": 3561.1, "bax": "binance", "baq": 2.0, "sp": -0.0056, "n": 12, "ch": 2.1, "v": 912003311, "t": 1731400000990 }
  ]
}

pong

Reply to {"op":"ping"}.

{ "type": "pong", "ts": 1731400005000 }

error

Your request was rejected. The connection stays open.

{ "type": "error", "ts": 1731400000015, "code": "unknown_channel", "msg": "`ticker:NOPEUSDT` is not a published pair" }

Errors

Connection-level rejections happen before the upgrade, as plain HTTP:

• 429: too many connections from your IP.
• 503: the server is at capacity. Retry later with backoff.

Heartbeats

The server sends a WebSocket ping frame every 30 s. Browsers and most libraries answer automatically. Connections with no traffic for 90 s are closed. A client that cannot keep up with sending is disconnected.

Reconnecting

Reconnect with exponential backoff and jitter (for example 0.5 s, 1 s, 2 s … capped at 15 s), then re-send your subscriptions. A fresh snapshot follows, so there is no state to repair. @aeon-feed/client does this for you.

Snapshots and resyncs

If your connection falls behind on a channel, the server skips the missed deltas and sends a new snapshot for that channel instead. Always treat a snapshot as replace, and a delta as merge.