Subscribe, filter and reconcile.

Quickstart

A subscription has four parts: your token, a region, your named filters, and a loop that reads events. The stream is gRPC and runs to your own servers. Access is enabled on request, so ask for it first.

# placeholders only: the client library documents the exact calls
stream = client.subscribe(region=region, filters={"my-pool": {"accounts": [pool_account]}})
for event in stream:
    handle(event)   # SlotStart, Transaction, SlotEnd

Start with one region near the leaders you care about and one narrow filter, confirm what you receive against your usual feed, and widen from there.

Message types

Every accepted transaction arrives as one message with the raw transaction, its slot and its sequence within the slot. Slot start and slot end markers frame each slot, so you know when a slot is complete. When the stream withholds transactions because of your fair share, it reports that on the stream.

Filters

A subscription holds named filters. A filter can select by accounts (include, require or exclude), by signers, by program instructions or by signatures. A transaction is delivered if it matches any filter, and the update names the filters it matched. Keep filters narrow: no customer receives the full feed.

Regions

Each region carries different slots, so there is nothing to deduplicate between regions. Choose regions by where the leader is, not where you are, and subscribe to regions near your servers, because far regions arrive too late to be useful.

Reconnects and gaps

If the connection drops, the client reconnects with backoff. The transactions produced during the gap are dropped and are not replayed, so treat a reconnect as a gap and reconcile with your usual feed.

Preconfs, shreds and Geyser

A shred stream carries the pieces of a block after they exist. A Geyser feed reports what a validator has processed. A preconfirmation is earlier than both: it is the leader's signal that it accepted a transaction into the slot it is building. It is a commitment, not finality, and a slot can still be skipped or the fork dropped. How much earlier depends on where the leader is, so we publish the measured lead per region with the method stated.

More guides

New guides are listed under Latest on the home page as they are published.