The SubscribeRequest message is the foundation of all Yellowstone gRPC subscriptions. It defines what data you want to receive and how you want to filter it.
A SubscribeRequest contains multiple subscription types that can be combined in a single request:
message SubscribeRequest {
map<string, SubscribeRequestFilterAccounts> accounts = 1;
map<string, SubscribeRequestFilterSlots> slots = 2;
map<string, SubscribeRequestFilterTransactions> transactions = 3;
map<string, SubscribeRequestFilterTransactions> transactions_status = 10;
map<string, SubscribeRequestFilterBlocks> blocks = 4;
map<string, SubscribeRequestFilterBlocksMeta> blocks_meta = 5;
map<string, SubscribeRequestFilterEntry> entry = 8;
optional CommitmentLevel commitment = 6;
repeated SubscribeRequestAccountsDataSlice accounts_data_slice = 7;
optional SubscribeRequestPing ping = 9;
optional uint64 from_slot = 11;
}Map of account subscription filters. The key is a user-defined identifier for the subscription.
Type: map<string, SubscribeRequestFilterAccounts>
See Subscribe to Accounts for details.
Map of slot subscription filters. The key is a user-defined identifier for the subscription.
Type: map<string, SubscribeRequestFilterSlots>
See Subscribe to Slots for details.
Map of transaction subscription filters. The key is a user-defined identifier for the subscription.
Type: map<string, SubscribeRequestFilterTransactions>
See Subscribe to Transactions for details.
Map of full block subscription filters. The key is a user-defined identifier for the subscription.
Type: map<string, SubscribeRequestFilterBlocks>
See Subscribe to Blocks for details.
Map of block metadata subscription filters. The key is a user-defined identifier for the subscription.
Type: map<string, SubscribeRequestFilterBlocksMeta>
Map of entry subscription filters. The key is a user-defined identifier for the subscription.
Type: map<string, SubscribeRequestFilterEntry>
Entries represent the unit of blockchain data between transactions and blocks. Entry subscriptions are advanced use cases for low-level block construction monitoring.
Map of transaction status subscription filters. Similar to transaction subscriptions but for transaction status updates.
Type: map<string, SubscribeRequestFilterTransactions>
Transaction status updates provide information about transaction execution status separately from full transaction data.
The commitment level for the subscription. Controls when updates are sent based on Solana's confirmation status.
Type: optional CommitmentLevel
Values:
PROCESSED- Fastest updates, can be rolled backCONFIRMED- Supermajority vote received (recommended for most use cases)FINALIZED- Fully finalized, cannot be rolled back
Default: CONFIRMED
Specify which portions of account data to include in responses. Reduces bandwidth when you only need specific data ranges.
Type: repeated SubscribeRequestAccountsDataSlice
Structure:
message SubscribeRequestAccountsDataSlice {
uint64 offset = 1;
uint64 length = 2;
}Each slice specifies an offset and length to extract from account data.
Start streaming from a historical slot. This allows you to replay up to 6000 slots of historical data.
Type: optional uint64
Behavior:
- If specified, streaming begins from this slot number
- All matching data from
from_slotonwards will be sent - Historical data up to 6000 slots back is available (~40 minutes)
- If not specified, streaming begins from the current slot
Use Cases:
- Recover from application downtime
- Backfill historical data
- Test application logic against real historical events
- Debug specific slot ranges
Can be used to send a ping to the server to maintain connection health.
Type: optional SubscribeRequestPing
Each filter map uses string keys that you define. These identifiers are included in SubscribeUpdate messages, allowing you to determine which filter matched the data.
Best Practices:
- Use descriptive identifiers (e.g., "usdc_accounts", "swap_transactions")
- Keep identifiers consistent across your application
- Use identifiers to route data to different handlers
You can combine multiple subscription types in a single request:
// Create a subscription request that combines multiple subscription types
SubscribeRequest {
// Subscribe to all slot updates
// The key "all_slots" is a user-defined identifier that will be included in responses
slots: HashMap::from([(
"all_slots".to_string(),
SubscribeRequestFilterSlots {
// Use default filter settings to receive all slot updates
..Default::default()
},
)]),
// Subscribe to transactions with specific filters
// The key "all_transactions" identifies this subscription in responses
transactions: HashMap::from([(
"all_transactions".to_string(),
SubscribeRequestFilterTransactions {
vote: Some(false), // Exclude vote transactions to reduce data volume
failed: Some(false), // Exclude failed transactions (only successful ones)
// Use default values for other filter fields (no account/signature filters)
..Default::default()
},
)]),
// Set commitment level to CONFIRMED for balance between speed and reliability
// CONFIRMED means supermajority vote has been received
commitment: Some(CommitmentLevel::Confirmed as i32),
// Use default values for other subscription types (accounts, blocks, etc.)
..Default::default()
}The server responds with a stream of SubscribeUpdate messages containing:
message SubscribeUpdate {
repeated string filters = 1;
oneof update_oneof {
SubscribeUpdateAccount account = 2;
SubscribeUpdateSlot slot = 3;
SubscribeUpdateTransaction transaction = 4;
SubscribeUpdateTransactionStatus transaction_status = 10;
SubscribeUpdateBlock block = 5;
SubscribeUpdatePing ping = 6;
SubscribeUpdatePong pong = 9;
SubscribeUpdateBlockMeta block_meta = 7;
SubscribeUpdateEntry entry = 8;
}
google.protobuf.Timestamp created_at = 11;
}The filters field contains the identifiers of the filters that matched this update.
Explore specific subscription types:
- Subscribe to Accounts - Real-time account updates
- Subscribe to Transactions - Transaction streaming
- Subscribe to Slots - Slot progression tracking
- Subscribe to Blocks - Full block data