Streams

Connect & authenticate

Open a WebSocket to /stream with your Data API key (as ?api-key= or an x-api-key header). On connect you receive a welcome frame listing the channels and filters. Then send subscribe messages; you can hold many subscriptions on one connection.

const ws = new WebSocket("wss://solindex.infinityblocks.io/stream?api-key=<API_KEY>");

ws.onopen = () => {
  // every DegenSafe trade, ≥ $1, pushed live
  ws.send(JSON.stringify({
    action: "subscribe", id: "dgn-trades", channel: "trades",
    filters: { platform: "GKLyKXb8XbvEZqif3C4ksRyYf7BP1ASQTLbRScM8oGnB", minUsd: 1 }
  }));
};
ws.onmessage = (e) => {
  const m = JSON.parse(e.data);
  if (m.channel === "trades") console.log(m.data);   // { time, mint, direction, wallet, amountToken, amountSol, amountUsd, priceUsd, mcapUsd, signature, dex, eventId, eventIndex, poolAddress, slot }
};

Try it — live

—

Channels

Filters

Per-channel semantics

Channels are event-driven — an event is pushed the instant it's indexed, and a channel can sit idle for a while when nothing is happening (e.g. launches only ticks when a token actually launches). A quiet channel is not a broken one. Resume support differs per channel:

¹ prices and bonding-curve are derived live and have no standalone history table — resume them with sinceId against the durable log (covers the live buffer). For deep price history use trades/candles since instead.   ² candles resume by replaying closed candles with since, not sinceId.

Both since and sinceId stream the gap oldest→newest, each event tagged backfill:true, terminated by a single { type:"backfill_done", count } marker, then live events flow. Use sinceId for a fast resume after a brief drop; use since to pull a deeper historical window on first connect.

A since backfill returns up to 2,000 events per subscription (oldest first). If a window holds more than that, raise since (a more recent timestamp) or resume with sinceId from the last cursor you saw — for very deep history page the REST Data API, which is the source of truth and fully paginated.

Live candles

ws.send(JSON.stringify({
  action: "subscribe", id: "chart", channel: "candles",
  filters: { token: "<MINT>", interval: "1m" },
  since: Date.now() - 3600_000          // backfill the last hour, then go live
}));
// -> backfilled closed candles (backfill:true), then live { ...ohlcv, final:false } ticks,
//    and a { final:true } candle each time the 1-minute bucket rolls over.

Stream health & replay horizon

Streams are the low-latency layer; the REST Data API (ClickHouse) is the authoritative store. GET /stream/health is a plain HTTPS endpoint — no API key, no WebSocket — that tells you how current each layer is, so a client can decide whether to resume with sinceId (fast ring-buffer replay) or fall back to a REST backfill, and how deep the ring buffer currently reaches.

curl -s https://solindex.infinityblocks.io/stream/health

{
  "ok": true, "service": "stream", "clients": 42,
  "live": true,
  "replay": {
    "type": "ring-buffer",
    "oldestRetainedId": "1780160000123-0", "oldestRetainedAgeSec": 41820,
    "note": "sinceId replay is a volume-dependent ring buffer (~12h at current load, less when busier); a resume older than oldestRetainedId is unrecoverable and returns {type:gap}",
    "oldestRetainedTs": 1780160000, "oldestRetainedSlot": 423190000,
    "latestId": "1780203800456-3", "latestTs": 1780203800, "latestSlot": 423214981,
    "lagSec": 1, "entries": 812400, "retainedWindowSec": 43800
  },
  "indexer": { "latestTradeTs": 1780203799, "freshnessSec": 2, "checkedAgoSec": 6 }
}

How to use it: reconnecting with a saved sinceId? Compare it (or its embedded timestamp) against replay.oldestRetainedId/oldestRetainedTs — if your cursor predates it, skip straight to a REST backfill instead of waiting on { type:"gap" }. Watch replay.lagSec and indexer.freshnessSec together: both climbing means the pipeline is actually stalled; neither climbing but a channel is quiet just means nothing has happened (these two fields are chain-wide, not per-channel).

Resume after a disconnect

Every event carries a cursor — a composite "batchId:idx" (the underlying Redis stream entry id, plus this event's position within that batch). Reconnect and pass the last cursor you saw back as sinceId for an exactly-once resume: the server rescans the boundary batch, skips everything at or before your idx, replays the rest, then goes live:

ws.send(JSON.stringify({ action: "subscribe", channel: "trades", id: "t",
  filters: { platform: "GKLyKXb8…" }, sinceId: lastCursorYouSaw }));
// -> replayed events (backfill:true) … { type:"backfill_done", count, cursor } … then live
// -> OR, if lastCursorYouSaw predates the retained window: { type:"gap", oldestRetainedId, lostWindowMs }

A bare batch id with no :idx (e.g. a cursor saved before per-event cursors existed) is treated as exclusive of the whole batch — every event in that batch replays again, which can duplicate events you already received. Always resume with the full "batchId:idx" form when you have it.

For deeper history (beyond the ring-buffer window — see Stream health below) use since (a unix-ms timestamp) instead — it backfills from ClickHouse, then resumes live.

Message reference

• subscribe (client → server) — { action, channel, id?, filters?, since?, sinceId? } → { type:"subscribed", sub, channel, filters }
• unsubscribe (client → server) — { action:"unsubscribe", id } → { type:"unsubscribed", sub }
• ping (client → server) — { action:"ping" } → { type:"pong" } (the server also sends WebSocket-protocol pings every 30s)
• welcome (server → client, sent once on connect) — { type:"welcome", channels: [...], filters: [...] }, listing everything your key can subscribe to
• event (server → client) — { channel, sub, cursor, data, backfill? }
• backfill_done (server → client) — { type:"backfill_done", sub, count, cursor? }, marking the end of a since/sinceId catch-up (live events follow)
• gap (server → client) — { type:"gap", sub, channel, requested, oldestRetainedId, lostWindowMs }, sent when a sinceId predates the oldest retained ring-buffer entry (see Stream health) — that window is unrecoverable from the stream; backfill it via REST instead
• error (server → client) — { type:"error", error, sub? } — invalid JSON, unknown channel, bad filter, too many subscriptions, or a failed backfill/replay

Bulk / enterprise consumers

The WebSocket API suits apps and bots. For high-throughput backends that want the raw firehose with durable replay and consumer-group load-balancing, the stream is also available as a durable log (Redis Streams). Ask us for a dedicated consumer endpoint — you get at-least-once delivery, replay from any point, and horizontal fan-out across workers.