Overview
TheSubscribe method establishes a bidirectional streaming connection that allows you to receive real-time updates from the Solana blockchain. You can subscribe to various update types including accounts, transactions, slots, blocks, and entries.
How It Works
Subscribe uses bidirectional streaming, which means:- Client sends initial request: You send a
SubscribeRequestwith filters defining what data you want to receive - Server streams updates: The server continuously sends
SubscribeUpdatemessages matching your filters - Dynamic updates: You can send additional
SubscribeRequestmessages at any time to add, modify, or remove filters - Ping/Pong keepalive: The connection supports ping/pong messages to keep load balancers and firewalls happy
SubscribeRequest
The request message defines filters for the types of updates you want to receive.Map of account filters. Key is a user-defined filter name, value contains filter criteria.
Map of slot filters. Subscribe to slot status updates (processed, confirmed, finalized, etc.).
Map of transaction filters. Receive transaction updates with full execution details and metadata.
Map of transaction status filters. Receive lightweight transaction status updates (success/failure) without full transaction data.
Map of block filters. Receive complete block data including transactions, accounts, and entries.
Map of block metadata filters. Receive block metadata without full transaction/account data.
Map of entry filters. Subscribe to ledger entry updates.
Commitment level for updates: PROCESSED (0), CONFIRMED (1), or FINALIZED (2). If not specified, defaults to PROCESSED.
Array of data slices to receive only portions of account data. Useful for large accounts when you only need specific data ranges.
Send a ping request. Server will respond with a pong message containing the same ID.
Start receiving updates from a specific slot number. Useful for replaying historical data.
Account Filters
List of account public keys to subscribe to (base58 encoded).
List of program owner public keys. Receives updates for all accounts owned by these programs.
Additional filters: memcmp (memory comparison), datasize (account data size), token_account_state (valid token accounts), lamports (balance filters).
Only receive account updates that include a transaction signature.
Transaction Filters
Filter vote transactions. Set to false to exclude vote transactions.
Filter failed transactions. Set to true to include failed transactions.
Subscribe to a specific transaction signature.
List of accounts. Receive transactions that include any of these accounts.
List of accounts. Exclude transactions that include any of these accounts.
List of accounts. Receive transactions that include all of these accounts.
SubscribeUpdate
The server responds with a stream of update messages.Names of the filters that matched this update.
One of the following update types:
account: Account update with balance, data, and ownership changesslot: Slot status update (processed, confirmed, finalized, rooted, dead, etc.)transaction: Full transaction with metadata and execution detailstransaction_status: Lightweight transaction status (success/error)block: Complete block datablock_meta: Block metadata without full transaction dataentry: Ledger entry updateping: Server-initiated ping for keepalivepong: Response to client ping
Timestamp when the update was created on the server.
Account Update
Account public key (32 bytes).
Account balance in lamports.
Program that owns this account (32 bytes).
Whether this account contains executable program data.
Epoch when rent is next due.
Account data.
Monotonically increasing version number.
Transaction signature that caused this account update.
Slot number for this update.
True if this is a startup/snapshot account (not from a transaction).
Transaction Update
Transaction signature (64 bytes).
Whether this is a vote transaction.
Full transaction data including message and signatures.
Transaction metadata including status, fee, logs, compute units, and account changes.
Transaction index within the block.
Slot number containing this transaction.
Examples
Dynamic Filter Updates
You can update your subscription filters at any time by sending a newSubscribeRequest on the existing stream. This allows you to add new filters, remove existing ones, or modify filter parameters without reconnecting.
Keepalive with Ping/Pong
For long-running connections, especially behind load balancers, use ping/pong messages:Best Practices
- Use specific filters: Subscribe only to the data you need to reduce bandwidth and processing overhead
- Handle backpressure: Process updates quickly or use buffering to avoid blocking the stream
- Set appropriate commitment: Use PROCESSED for real-time data, CONFIRMED for reduced reorg risk, or FINALIZED for immutability
- Implement reconnection logic: Networks are unreliable; implement exponential backoff and reconnection
- Monitor memory: Account and transaction data can be large; use data slices for accounts when possible
- Filter votes: Most applications should set
vote: falseto exclude vote transactions