Documentation index

Subscribe

The Subscribe method is the heart of the Yellowstone Geyser gRPC interface. It establishes a bidirectional streaming connection that multiplexes all real-time subscriptions into a single gRPC stream. Clients send SubscribeRequest messages with filter configurations, and the server pushes SubscribeUpdate messages as matching on-chain events occur.

This is the most powerful and commonly used Geyser method. It replaces JSON-RPC polling and WebSocket subscriptions with a single, persistent connection that delivers sub-millisecond latency updates. Every HFT bot, MEV searcher, and real-time indexer on Solana should use this method.

Type: Bidirectional Streaming

Subscription Filter Types

Each filter type is documented in detail on its own page:

FilterDescriptionPage
AccountsStream account state changes by pubkey or ownerAccount Subscriptions
TransactionsStream full transaction data with account filtersTransaction Subscriptions
TransactionStatusLightweight transaction status updatesTransaction Status Subscriptions
BlocksStream complete block dataBlock Subscriptions
BlockMetaLightweight block metadataBlock Meta Subscriptions
SlotsSlot progression and status changesSlot Subscriptions
EntriesLedger entry dataEntry Subscriptions
ProgramsMonitor program deployments and upgradesProgram Subscriptions

Commitment Levels

All filters share the top-level commitment field:

ValueNameDescription
0ProcessedFastest. Transaction has been processed by the current node but may be rolled back.
1ConfirmedTransaction has been confirmed by supermajority of the cluster. Very unlikely to roll back.
2FinalizedTransaction has been finalized. Cannot be rolled back.

Parameters

ParameterTypeRequiredDescription
accountsmap<string, SubscribeRequestFilterAccounts>NoAccount subscription filters keyed by a label you choose
slotsmap<string, SubscribeRequestFilterSlots>NoSlot subscription filters
transactionsmap<string, SubscribeRequestFilterTransactions>NoTransaction subscription filters
transactions_statusmap<string, SubscribeRequestFilterTransactions>NoTransaction status subscription filters (lightweight)
blocksmap<string, SubscribeRequestFilterBlocks>NoBlock subscription filters
blocks_metamap<string, SubscribeRequestFilterBlocksMeta>NoBlock metadata subscription filters
entrymap<string, SubscribeRequestFilterEntry>NoLedger entry subscription filters
commitmentCommitmentLevelNoCommitment level: Processed (0), Confirmed (1), or Finalized (2)
accounts_data_sliceSubscribeRequestAccountsDataSlice[]NoRequest only specific byte ranges of account data
pingSubscribeRequestPingNoReply to a server ping. id is any number you choose; the server's pong echoes it
from_slotuint64NoReplay updates from this slot. AllenHark keeps about the last 48 hours

Response

Each SubscribeUpdate message contains a filters array (your label strings) and exactly one of:

FieldTypeDescription
accountSubscribeUpdateAccountAccount state change
slotSubscribeUpdateSlotSlot progression
transactionSubscribeUpdateTransactionFull transaction data
transaction_statusSubscribeUpdateTransactionStatusLightweight transaction status
blockSubscribeUpdateBlockComplete block
block_metaSubscribeUpdateBlockMetaBlock metadata only
entrySubscribeUpdateEntryLedger entry
pingSubscribeUpdatePingKeep-alive ping from server
pongSubscribeUpdatePongAnswer to your ping, with the id you sent

Ping/Pong Keep-Alive

The server periodically sends SubscribeUpdatePing messages to keep the connection alive. The ping carries no fields. Reply on the same stream with a SubscribeRequest that sets only ping, with any id (for example { ping: { id: 1 } }); the server answers with a pong carrying that id. A request with only ping set leaves your filters unchanged. Replying also keeps proxies that close streams with no client traffic from closing yours.

Reconnection Strategy

gRPC streams can drop due to network issues, server restarts, or idle timeouts. Implement exponential backoff reconnection logic in your client. When reconnecting, re-send your full SubscribeRequest -- the server does not persist subscription state across connections.

Code Examples

Node.js

JavaScript
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');

const packageDef = protoLoader.loadSync('geyser.proto', {
  keepCase: true, longs: String, enums: String, defaults: true, oneofs: true
});
const proto = grpc.loadPackageDefinition(packageDef).geyser;
const client = new proto.Geyser('88.216.36.108:10001', grpc.credentials.createInsecure());

const stream = client.subscribe();

// Handle incoming updates
stream.on('data', (update) => {
  if (update.account) {
    console.log('[Account]', Buffer.from(update.account.account.pubkey).toString('hex'));
  } else if (update.transaction) {
    console.log('[Tx]', Buffer.from(update.transaction.transaction.signature).toString('hex'));
  } else if (update.slot) {
    console.log('[Slot]', update.slot.slot, update.slot.status);
  } else if (update.ping) {
    // Answer the server's ping; the ping has no id, so send any number
    stream.write({ ping: { id: 1 } });
  }
});

stream.on('error', (err) => {
  console.error('Stream error:', err);
  // Implement reconnection logic here
});

// Send subscription request -- monitor USDC account + all slots
stream.write({
  accounts: {
    usdc: {
      account: ['EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'],
      owner: [],
      filters: []
    }
  },
  slots: {
    allSlots: { filter_by_commitment: false }
  },
  transactions: {},
  transactionsStatus: {},
  blocks: {},
  blocksMeta: {},
  commitment: 1,
  entry: {},
  accountsDataSlice: [],
  ping: null
});

Rust

Rust
use yellowstone_grpc_client::GeyserGrpcClient;
use yellowstone_grpc_proto::prelude::*;
use std::collections::HashMap;
use futures::StreamExt;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let mut client = GeyserGrpcClient::build_from_uri("http://88.216.36.108:10001")
        .connect()
        .await?;

    // Build subscription: accounts (USDC) + all slots
    let mut accounts = HashMap::new();
    accounts.insert("usdc".to_string(), SubscribeRequestFilterAccounts {
        account: vec!["EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v".to_string()],
        owner: vec![],
        filters: vec![],
        nonempty_txn_signature: None,
    });

    let mut slots = HashMap::new();
    slots.insert("allSlots".to_string(), SubscribeRequestFilterSlots {
        filter_by_commitment: Some(false),
        interleave: None,
    });

    let request = SubscribeRequest {
        accounts,
        slots,
        transactions: HashMap::new(),
        transactions_status: HashMap::new(),
        blocks: HashMap::new(),
        blocks_meta: HashMap::new(),
        commitment: Some(CommitmentLevel::Confirmed as i32),
        entry: HashMap::new(),
        accounts_data_slice: vec![],
        ping: None,
        from_slot: None,
    };

    let (_, mut stream) = client.subscribe_with_request(Some(request)).await?;

    while let Some(msg) = stream.next().await {
        match msg?.update_oneof {
            Some(UpdateOneof::Account(acct)) => {
                println!("Account update: {:?}", acct.account.map(|a| a.pubkey));
            }
            Some(UpdateOneof::Slot(slot)) => {
                println!("Slot: {} status: {:?}", slot.slot, slot.status);
            }
            Some(UpdateOneof::Ping(_)) => {
                println!("Received ping -- connection alive");
            }
            _ => {}
        }
    }

    Ok(())
}

Example Response

JSON
{
  "filters": ["usdc"],
  "account": {
    "account": {
      "pubkey": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "lamports": "2039280",
      "owner": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
      "data": "...",
      "write_version": "12345678",
      "slot": "250000042"
    },
    "slot": "250000042",
    "is_startup": false
  }
}
JSON
{
  "filters": ["allSlots"],
  "slot": {
    "slot": "250000043",
    "parent": "250000042",
    "status": "CONFIRMED"
  }
}