Streaming
Open the stream, authenticate, and filter the accounts and transactions you want.
Access and authentication
Access is checked twice, and both checks must pass.
1. IP allow-list
The endpoint only accepts connections from the one IP address registered on your subscription. A connection from any other address is dropped at the firewall: it times out and never reaches the service. You can change the address in the dashboard under Subscription; the new one is allowed within a few seconds and your token stays the same.
2. Token
Every Subscribe call must carry your token in the x-token gRPC metadata header. It is checked when the stream is opened: a missing or unknown token is refused. The token identifies your subscription and carries its limits, and it stays the same for as long as you have an account. Keep it out of source control; anyone holding it and connecting from your address uses your stream allowance.
Endpoint
| LOCATION | ENDPOINT | TRANSPORT |
|---|---|---|
| Amsterdam (AMS) | http://ams.no-name.io:10000 | gRPC over HTTP/2, plaintext |
The endpoint is plaintext HTTP/2 (no TLS). TLS termination costs latency on every update, and the IP allow-list already restricts who can connect. Use http://, not https://. Host your client in or near Amsterdam: every millisecond of network distance is added to every update.
Subscribing
The service implements the Yellowstone geyser.Geyser/Subscribe bidirectional stream. You open the stream, send a SubscribeRequest, and receive SubscribeUpdate messages. Two rules apply to every request:
- Commitment must be
PROCESSED(or left unset). Confirmed and finalized are refused. - Only the
accounts,transactionsandslotsmaps may be populated. Leaveblocks,blocksMeta,entryandtransactionsStatusempty.
Filters are named. Each update lists the names of the filters it matched, so one stream can carry several logical subscriptions. You can replace the filters on a live stream by sending a new SubscribeRequest on it; you do not need to reconnect.
Account filters
An account filter matches when the account is in account or its owner is in owner, and every entry in filters passes. Named filters are OR'd together.
| FIELD | SUPPORTED | NOTES |
|---|---|---|
account | Yes | List of account pubkeys. |
owner | Yes | List of owner program ids. |
filters.memcmp | Yes | bytes, base58 or base64 data at an offset. |
filters.datasize | Yes | Exact data length. |
nonemptyTxnSignature | Yes | Only writes caused by a transaction. |
accountsDataSlice | Yes | Receive only the byte ranges you need. |
filters.tokenAccountState, filters.lamports | No | Use memcmp and datasize instead. |
| Cuckoo filters | No |
An account filter must name at least one account or owner. Filters that would match the whole chain, such as an empty filter or owner set to the System program, are refused. Subscribing to token accounts by owner = Token or Token-2022 program is allowed; add a datasize or memcmp to keep the stream to what you need.
Transaction filters
| FIELD | MEANING |
|---|---|
accountInclude | Matches if the transaction references any of these accounts. |
accountRequired | Matches only if the transaction references all of these accounts. |
accountExclude | Rejects the transaction if it references any of these accounts. |
vote | true = only votes, false = no votes, unset = both. |
failed | true = only failed, false = only successful, unset = both. |
signature | Match one transaction signature. |
Account matching covers the static account keys and the keys loaded through address lookup tables. A transaction filter must name at least one account in accountInclude or accountRequired. Keys that appear in nearly every transaction (the Token programs, Compute Budget, the System program) are refused as the only selector, because that is the full chain.
What is not served
| REQUEST | RESULT |
|---|---|
blocks, blocksMeta, entry, transactionsStatus | INVALID_ARGUMENT: accounts, transactions and slots only. |
Commitment CONFIRMED or FINALIZED | INVALID_ARGUMENT: only processed commitment is supported. |
Unary Ping, GetVersion, GetSlot, GetLatestBlockhash and the other unary calls | UNIMPLEMENTED. |
| Wildcard or chain-wide filters | PERMISSION_DENIED. |
Processed means processed. Updates are produced as transactions execute, on whichever fork the leader is building. A small share of processed state is later abandoned when a fork is dropped. If you need confirmation before acting, pair this feed with a confirmed-commitment source for the accounts where it matters, such as nonces.
Some client libraries call GetVersion or the unary Ping on connect as a health check. Disable that check, or ignore its failure, and rely on HTTP/2 keepalive instead.
Limits
| LIMIT | PER TOKEN |
|---|---|
| Concurrent streams | 16 |
| Named filters per request | 256 |
| Keys across all filters | 200,000 |
| Filter updates on a live stream | 120 per 10 seconds |
| Maximum message size | 64 MiB |
| Registered IP addresses | 1 |
A stream slot is released when its connection closes. Clients that reconnect in a tight loop without closing the previous stream can hold all 16 slots and lock themselves out with RESOURCE_EXHAUSTED; close streams you replace, and back off between reconnects.