Subscribing

After connecting, use the subscribe operation to start receiving events. There are two subscription modes: single address and bulk addresses.

Single Address Subscription

Subscribe to a specific token address on a network and stream.

{
  "op": "subscribe",
  "network": "sol",
  "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "stream": "clusters"
}

Response

{
  "op": "subscribed",
  "mode": "add",
  "accepted": 1,
  "rejected": 0,
  "topics_now": 1
}

Field	Type	Description
`mode`	string	The mode used: `add` or `replace`
`accepted`	integer	Number of subscriptions successfully created
`rejected`	integer	Number of subscriptions that failed (e.g. duplicates, limit hit)
`topics_now`	integer	Total active topic count after this operation

Bulk Subscription

Subscribe to multiple addresses in a single message using the subs array. This is more efficient than sending individual subscribe messages.

{
  "op": "subscribe",
  "subs": [
    { "network": "sol", "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "stream": "clusters" },
    { "network": "sol", "address": "So11111111111111111111111111111111111111112", "stream": "clusters" },
    { "network": "eth", "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "stream": "clusters" }
  ]
}

Response

{
  "op": "subscribed",
  "mode": "add",
  "accepted": 3,
  "rejected": 0,
  "topics_now": 3
}

Invalid entries in the subs array (bad network, bad address, unknown stream) are silently skipped -- they count toward rejected without producing individual error messages.

Subscribe Modes

Both single and bulk subscriptions accept an optional mode field:

Mode	Behaviour
`add` (default)	Add the new topics to your existing subscriptions. Duplicates are ignored.
`replace`	Remove all existing subscriptions for the same network+stream combination, then add the new ones. Subscriptions on other network+stream pairs are untouched.

Example: Replace Mode

If you're subscribed to 5 Solana cluster topics and send:

{
  "op": "subscribe",
  "mode": "replace",
  "network": "sol",
  "address": "NEW_ADDRESS_HERE",
  "stream": "clusters"
}

All 5 previous sol:clusters subscriptions are removed and replaced with the single new one. Any eth:clusters subscriptions remain untouched.

Event Messages

Once subscribed, you will receive event messages whenever new data is available:

{
  "op": "event",
  "network": "sol",
  "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "stream": "clusters",
  "timestamp": "2026-02-07T14:30:00.000Z",
  "data": {
    // stream-specific payload
  }
}

Field	Type	Description
`op`	string	Always `"event"`
`network`	string	The network ID (e.g. `sol`, `eth`)
`address`	string	The token address this event relates to
`stream`	string	The stream name (e.g. `clusters`)
`timestamp`	string	ISO 8601 timestamp (UTC) of when the event was generated
`data`	object	The event payload, structure depends on the stream

Ping / Pong

Send periodic pings to keep the connection alive. You can include an optional id field that will be echoed back.

{ "op": "ping", "id": "heartbeat-1" }

Response

{
  "op": "pong",
  "id": "heartbeat-1",
  "ts": 1707300000
}

We recommend sending a ping every 30 seconds.