Subscribe Request

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.

Request Structure

A SubscribeRequest contains multiple subscription types that can be combined in a single request:

1
message SubscribeRequest {
2
    map<string, SubscribeRequestFilterAccounts> accounts = 1;
3
    map<string, SubscribeRequestFilterSlots> slots = 2;
4
    map<string, SubscribeRequestFilterTransactions> transactions = 3;
5
    map<string, SubscribeRequestFilterTransactions> transactions_status = 10;
6
    map<string, SubscribeRequestFilterBlocks> blocks = 4;
7
    map<string, SubscribeRequestFilterBlocksMeta> blocks_meta = 5;
8
    map<string, SubscribeRequestFilterEntry> entry = 8;
9
    optional CommitmentLevel commitment = 6;
10
    repeated SubscribeRequestAccountsDataSlice accounts_data_slice = 7;
11
    optional SubscribeRequestPing ping = 9;
12
    optional uint64 from_slot = 11;
13
}

Key Parameters

accounts

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.

slots

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.

transactions

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.

blocks

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.

blocks_meta

Map of block metadata subscription filters. The key is a user-defined identifier for the subscription.

Type: map<string, SubscribeRequestFilterBlocksMeta>

entry

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.

transactions_status

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.

commitment

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 back
• CONFIRMED - Supermajority vote received (recommended for most use cases)
• FINALIZED - Fully finalized, cannot be rolled back

Default: CONFIRMED

accounts_data_slice

Specify which portions of account data to include in responses. Reduces bandwidth when you only need specific data ranges.

Type: repeated SubscribeRequestAccountsDataSlice

Structure:

1
message SubscribeRequestAccountsDataSlice {
2
    uint64 offset = 1;
3
    uint64 length = 2;
4
}

Each slice specifies an offset and length to extract from account data.

from_slot

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_slot onwards 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

ping

Can be used to send a ping to the server to maintain connection health.

Type: optional SubscribeRequestPing

Filter Identifiers

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

Combining Multiple Subscriptions

You can combine multiple subscription types in a single request:

1
// Create a subscription request that combines multiple subscription types
2
SubscribeRequest {
3
    // Subscribe to all slot updates
4
    // The key "all_slots" is a user-defined identifier that will be included in responses
5
    slots: HashMap::from([(
6
        "all_slots".to_string(),
7
        SubscribeRequestFilterSlots {
8
            // Use default filter settings to receive all slot updates
9
            ..Default::default()
10
        },
11
    )]),
12
    
13
    // Subscribe to transactions with specific filters
14
    // The key "all_transactions" identifies this subscription in responses
15
    transactions: HashMap::from([(
16
        "all_transactions".to_string(),
17
        SubscribeRequestFilterTransactions {
18
            vote: Some(false),   // Exclude vote transactions to reduce data volume
19
            failed: Some(false), // Exclude failed transactions (only successful ones)
20
            // Use default values for other filter fields (no account/signature filters)
21
            ..Default::default()
22
        },
23
    )]),
24
    
25
    // Set commitment level to CONFIRMED for balance between speed and reliability
26
    // CONFIRMED means supermajority vote has been received
27
    commitment: Some(CommitmentLevel::Confirmed as i32),
28
    
29
    // Use default values for other subscription types (accounts, blocks, etc.)
30
    ..Default::default()
31
}

Response: SubscribeUpdate

The server responds with a stream of SubscribeUpdate messages containing:

1
message SubscribeUpdate {
2
    repeated string filters = 1;
3
    oneof update_oneof {
4
        SubscribeUpdateAccount account = 2;
5
        SubscribeUpdateSlot slot = 3;
6
        SubscribeUpdateTransaction transaction = 4;
7
        SubscribeUpdateTransactionStatus transaction_status = 10;
8
        SubscribeUpdateBlock block = 5;
9
        SubscribeUpdatePing ping = 6;
10
        SubscribeUpdatePong pong = 9;
11
        SubscribeUpdateBlockMeta block_meta = 7;
12
        SubscribeUpdateEntry entry = 8;
13
    }
14
    google.protobuf.Timestamp created_at = 11;
15
}

The filters field contains the identifiers of the filters that matched this update.

Next Steps

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