Yellowstone Grpc

Yellowstone gRPC — Real-Time Solana Streaming

Stream every transaction, account update, slot, and block on Solana in real-time using Yellowstone gRPC. This is the foundation for any latency-sensitive Solana trading system — replacing REST polling with push-based streaming at ~5ms slot latency.

Why Yellowstone gRPC

Yellowstone is a Geyser plugin that exposes Solana validator data over gRPC. Every major RPC provider runs it. You subscribe to filtered streams of transactions, account changes, slots, blocks, and entries — and the data pushes to you.

Quick Start

1. Get Access

You need a gRPC-enabled RPC provider. See references/providers.md for full comparison.

2. Install Dependencies

# Python
uv pip install grpcio grpcio-tools protobuf base58 solders python-dotenv

# Generate Python stubs from proto files
git clone https://github.com/rpcpool/yellowstone-grpc.git
python -m grpc_tools.protoc \
  -I./yellowstone-grpc/yellowstone-grpc-proto/proto/ \
  --python_out=./generated \
  --pyi_out=./generated \
  --grpc_python_out=./generated \
  ./yellowstone-grpc/yellowstone-grpc-proto/proto/*.proto

# Rust — Cargo.toml
[dependencies]
yellowstone-grpc-client = "6.0.0"
yellowstone-grpc-proto = "6.0.0"
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
futures = "0.3"
bs58 = "0.5"

# TypeScript
npm install @triton-one/yellowstone-grpc @solana/web3.js

3. Environment Setup

export GRPC_ENDPOINT="https://grpc.ny.shyft.to"  # your provider endpoint
export GRPC_TOKEN="your-x-token-here"              # from provider dashboard

4. Connect and Subscribe

import grpc
import os
from generated import geyser_pb2, geyser_pb2_grpc

endpoint = os.environ["GRPC_ENDPOINT"].replace("https://", "")
token = os.environ["GRPC_TOKEN"]

# Authenticated TLS channel
auth_creds = grpc.metadata_call_credentials(
    lambda ctx, cb: cb((("x-token", token),), None)
)
channel = grpc.secure_channel(
    endpoint,
    grpc.composite_channel_credentials(
        grpc.ssl_channel_credentials(), auth_creds
    ),
    options=[("grpc.max_receive_message_length", 64 * 1024 * 1024)],
)
stub = geyser_pb2_grpc.GeyserStub(channel)

Core Concepts

Subscription Types

Filter Logic

• Multiple filter types (transactions + accounts) = AND — you get updates matching any type
• Values within arrays (multiple addresses in account_include) = OR
• Named filters let you distinguish which filter matched in the response
• Sending a new SubscribeRequest replaces all previous filters

Commitment Levels

Common Subscription Patterns

Watch All Swaps on a DEX Program

# Filter: all non-vote, non-failed transactions involving PumpFun
request = geyser_pb2.SubscribeRequest(
    transactions={
        "pumpfun": geyser_pb2.SubscribeRequestFilterTransactions(
            account_include=["6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P"],
            vote=False,
            failed=False,
        )
    },
    commitment=geyser_pb2.CommitmentLevel.PROCESSED,
)

Track Specific Wallets

request = geyser_pb2.SubscribeRequest(
    transactions={
        "whales": geyser_pb2.SubscribeRequestFilterTransactions(
            account_include=[
                "WalletAddress1...",
                "WalletAddress2...",
            ],
            vote=False,
            failed=False,
        )
    },
    commitment=geyser_pb2.CommitmentLevel.CONFIRMED,
)

Monitor Pool Reserves (Account Subscription)

request = geyser_pb2.SubscribeRequest(
    accounts={
        "raydium_pools": geyser_pb2.SubscribeRequestFilterAccounts(
            account=["PoolAddress1...", "PoolAddress2..."],
        )
    },
    commitment=geyser_pb2.CommitmentLevel.PROCESSED,
)

Reduce Bandwidth with Data Slicing

# Only get the first 40 bytes of account data (e.g., just the discriminator + key fields)
request = geyser_pb2.SubscribeRequest(
    accounts={
        "token_accounts": geyser_pb2.SubscribeRequestFilterAccounts(
            owner=["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"],
            filters=[
                geyser_pb2.SubscribeRequestFilterAccountsFilter(
                    token_account_state=True
                )
            ],
        )
    },
    accounts_data_slice=[
        geyser_pb2.SubscribeRequestAccountsDataSlice(offset=0, length=40)
    ],
)

Parsing Transaction Updates

When you receive a SubscribeUpdateTransaction, extract:

for update in stream:
    if update.HasField("transaction"):
        tx = update.transaction
        info = tx.transaction
        sig = base58.b58encode(info.signature).decode()
        slot = tx.slot

        msg = info.transaction.message
        account_keys = [base58.b58encode(k).decode() for k in msg.account_keys]

        # Instructions
        for ix in msg.instructions:
            program = account_keys[ix.program_id_index]
            accounts = [account_keys[i] for i in ix.accounts]
            data = ix.data  # bytes — decode per program IDL

        # Token balance changes (post-execution)
        meta = info.meta
        for tb in meta.post_token_balances:
            mint = tb.mint
            owner = tb.owner
            amount = tb.ui_token_amount.ui_amount

See references/proto_reference.md for complete field documentation.

Production Architecture

[gRPC Stream] → [Bounded Channel] → [Processing Workers]
                   (1K-100K cap)      ├─ Parse instructions
                                      ├─ Update state / DB
                                      └─ Trigger actions

Critical patterns:

• Decouple I/O from processing — never block the gRPC stream
• Reconnect with exponential backoff (100ms → 60s cap)
• Use from_slot to resume after disconnection (subtract ~32 slots for reorg safety)
• Ping every 15-30 seconds to keep connection alive
• Filter vote: false always — vote transactions are ~70% of all traffic
• Set max_receive_message_length to 64MB+ (default 4MB is too small)

See references/performance.md for full production checklist.

Key Program IDs for Trading

Files

References

• references/providers.md — Provider comparison: endpoints, pricing, auth, features
• references/subscription_filters.md — Complete filter reference with examples for every filter type
• references/proto_reference.md — Key protobuf message definitions and field documentation
• references/performance.md — Connection management, reconnection, backpressure, production checklist

Scripts

• scripts/subscribe_transactions.py — Stream and parse transactions filtered by program ID
• scripts/monitor_wallets.py — Watch specific wallets for on-chain activity

Yellowstone gRPC — Performance & Production Guide

Latency Benchmarks

Data Volume Expectations

• All Solana transactions: ~2,000-4,000 TPS (including votes)
• Vote transactions: ~70% of total — always filter with vote: false
• PumpFun alone: ~20,000+ trades/hour during active periods
• Single DEX program filter: ~100-1,000 updates/second depending on activity
• Single wallet filter: ~0.01-10 updates/second depending on activity

Connection Management

Max Message Size

The default gRPC max message size (4MB) is too small for Solana. Set it higher:

# Python
options = [("grpc.max_receive_message_length", 64 * 1024 * 1024)]  # 64MB

# For block subscriptions, go higher
options = [("grpc.max_receive_message_length", 1024 * 1024 * 1024)]  # 1GB

// Rust
.max_decoding_message_size(64 * 1024 * 1024)

// TypeScript
{ "grpc.max_receive_message_length": 64 * 1024 * 1024 }

Keep-Alive / Ping

Send pings every 15-30 seconds to prevent connection timeout:

import time, threading

def ping_loop(request_iterator):
    while True:
        time.sleep(15)
        request_iterator.send(SubscribeRequest(
            ping=SubscribeRequestPing(id=int(time.time()))
        ))

Handle pong responses — if you receive a SubscribeUpdatePing from the server, respond:

if update.HasField("ping"):
    request_iterator.send(SubscribeRequest(
        ping=SubscribeRequestPing(id=update.ping.id)
    ))

Reconnection with Exponential Backoff

import time, random

def connect_with_backoff(max_delay: float = 60.0):
    delay = 0.1  # start at 100ms
    last_slot = None

    while True:
        try:
            stream = subscribe(from_slot=last_slot)
            delay = 0.1  # reset on success

            for update in stream:
                last_slot = extract_slot(update)
                process(update)

        except grpc.RpcError as e:
            jitter = random.uniform(0, delay * 0.1)
            print(f"Disconnected: {e.code()}. Reconnecting in {delay:.1f}s")
            time.sleep(delay + jitter)
            delay = min(delay * 2, max_delay)

Resume After Disconnection

Use from_slot to replay missed data. Subtract ~32 slots for reorg safety:

request = SubscribeRequest(
    transactions={...},
    from_slot=last_processed_slot - 32,
)

Important: from_slot replay may produce duplicate updates. Deduplicate by transaction signature.

Replay depth varies by provider:

• Shyft: ~150 slots
• QuickNode: ~3,000 slots
• Helius: ~24 hours

Backpressure Architecture

Never process messages in the gRPC receive loop. Decouple I/O from business logic:

[gRPC Stream Thread]
    │
    ▼
[Bounded Channel/Queue]  ← backpressure point (1K-100K capacity)
    │
    ▼
[Processing Worker(s)]
    ├─ Parse instructions
    ├─ Update state
    ├─ Trigger signals
    └─ Batch DB writes

Python Implementation

import queue
import threading

msg_queue = queue.Queue(maxsize=10_000)

def grpc_reader(stub, request):
    """Dedicated thread: reads gRPC stream into queue."""
    stream = stub.Subscribe(iter([request]))
    for update in stream:
        try:
            msg_queue.put(update, timeout=1.0)
        except queue.Full:
            print("WARNING: queue full, dropping message")

def processor():
    """Dedicated thread: processes messages from queue."""
    while True:
        update = msg_queue.get()
        handle_update(update)

threading.Thread(target=grpc_reader, args=(stub, request), daemon=True).start()
threading.Thread(target=processor, daemon=True).start()

Rust Implementation

use tokio::sync::mpsc;

let (tx, mut rx) = mpsc::channel(100_000);

// Spawn gRPC reader
tokio::spawn(async move {
    while let Some(msg) = stream.next().await {
        if tx.send(msg.unwrap()).await.is_err() { break; }
    }
});

// Process in main task
while let Some(update) = rx.recv().await {
    match update.update_oneof {
        Some(UpdateOneof::Transaction(tx)) => handle_transaction(tx),
        _ => {}
    }
}

Database Write Batching

Don't write every update to the database individually. Batch writes:

batch = []
last_flush = time.time()

for update in process_stream():
    batch.append(to_row(update))

    if len(batch) >= 1000 or (time.time() - last_flush) > 1.0:
        db.executemany("INSERT INTO events ...", batch)
        batch.clear()
        last_flush = time.time()

Multi-Connection Patterns

For high-throughput programs, split across multiple gRPC connections:

Connection 1: PumpFun transactions      → Worker pool A
Connection 2: Raydium + Orca swaps      → Worker pool B
Connection 3: Tracked wallet activity   → Worker pool C
Connection 4: Pool account updates      → Worker pool D

Each connection runs on its own thread/task with independent reconnection logic.

Monitoring

Track these metrics in production:

Production Checklist

• [ ] vote: false on all transaction filters
• [ ] max_receive_message_length set to 64MB+
• [ ] Exponential backoff reconnection (100ms → 60s cap)
• [ ] from_slot resume after disconnection
• [ ] Ping/pong every 15-30 seconds
• [ ] Bounded channel between I/O and processing
• [ ] Database write batching (1000 rows or 1s flush)
• [ ] Duplicate detection on replay (by tx signature)
• [ ] Monitoring: updates/sec, queue depth, reconnection count
• [ ] Graceful shutdown (drain queue before exit)
• [ ] Error classification (retriable vs fatal gRPC errors)
• [ ] Separate connections for independent data streams

Yellowstone gRPC — Protobuf Reference

Source: rpcpool/yellowstone-grpc

Service Definition

service Geyser {
  rpc Subscribe(stream SubscribeRequest) returns (stream SubscribeUpdate) {}
  rpc Ping(PingRequest) returns (PongResponse) {}
  rpc GetLatestBlockhash(GetLatestBlockhashRequest) returns (GetLatestBlockhashResponse) {}
  rpc GetBlockHeight(GetBlockHeightRequest) returns (GetBlockHeightResponse) {}
  rpc GetSlot(GetSlotRequest) returns (GetSlotResponse) {}
  rpc IsBlockhashValid(IsBlockhashValidRequest) returns (IsBlockhashValidResponse) {}
  rpc GetVersion(GetVersionRequest) returns (GetVersionResponse) {}
}

Subscribe is bidirectional streaming — you send SubscribeRequest messages and receive SubscribeUpdate messages continuously.

SubscribeRequest

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 keys are user-defined labels. They appear in SubscribeUpdate.filters to identify which subscription matched.

SubscribeUpdate (Response)

message SubscribeUpdate {
  repeated string filters = 1;  // which named filters matched
  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;
}

Transaction Update

message SubscribeUpdateTransaction {
  SubscribeUpdateTransactionInfo transaction = 1;
  uint64 slot = 2;
}

message SubscribeUpdateTransactionInfo {
  bytes signature = 1;            // 64 bytes, base58-encode for display
  bool is_vote = 2;
  Transaction transaction = 3;    // from solana-storage.proto
  TransactionStatusMeta meta = 4; // execution results
  uint64 index = 5;               // position within the block
}

Transaction (Inner)

message Transaction {
  repeated bytes signatures = 1;  // first is the tx signature
  Message message = 2;
}

message Message {
  MessageHeader header = 1;
  repeated bytes account_keys = 2;    // all account pubkeys (32 bytes each)
  bytes recent_blockhash = 3;
  repeated CompiledInstruction instructions = 4;
  bool versioned = 5;
  repeated MessageAddressTableLookup address_table_lookups = 6;
}

message MessageHeader {
  uint32 num_required_signatures = 1;
  uint32 num_readonly_signed_accounts = 2;
  uint32 num_readonly_unsigned_accounts = 3;
}

message CompiledInstruction {
  uint32 program_id_index = 1;  // index into account_keys
  bytes accounts = 2;           // indices into account_keys
  bytes data = 3;               // instruction data (program-specific)
}

TransactionStatusMeta (Post-Execution)

message TransactionStatusMeta {
  TransactionError err = 1;
  uint64 fee = 2;
  repeated uint64 pre_balances = 3;   // SOL balances before (lamports)
  repeated uint64 post_balances = 4;  // SOL balances after (lamports)
  repeated InnerInstructions inner_instructions = 5;
  repeated string log_messages = 6;
  repeated TokenBalance pre_token_balances = 7;
  repeated TokenBalance post_token_balances = 8;
  repeated Reward rewards = 9;
  repeated bytes loaded_writable_addresses = 12;
  repeated bytes loaded_readonly_addresses = 13;
  ReturnData return_data = 14;
  optional uint64 compute_units_consumed = 15;
}

Token Balance

message TokenBalance {
  uint32 account_index = 1;  // index into account_keys
  string mint = 2;           // token mint address (base58)
  UiTokenAmount ui_token_amount = 3;
  string owner = 4;          // token account owner (base58)
}

message UiTokenAmount {
  double ui_amount = 1;      // human-readable amount
  uint32 decimals = 2;
  string amount = 3;         // raw amount as string
}

Inner Instructions

message InnerInstructions {
  uint32 index = 1;  // which top-level instruction generated these
  repeated InnerInstruction instructions = 2;
}

message InnerInstruction {
  uint32 program_id_index = 1;
  bytes accounts = 2;
  bytes data = 3;
  optional uint32 stack_height = 4;
}

Account Update

message SubscribeUpdateAccount {
  SubscribeUpdateAccountInfo account = 1;
  uint64 slot = 2;
  optional bool is_startup = 3;
}

message SubscribeUpdateAccountInfo {
  bytes pubkey = 1;           // 32 bytes
  uint64 lamports = 2;
  bytes owner = 3;            // program that owns this account (32 bytes)
  bool executable = 4;
  uint64 rent_epoch = 5;
  bytes data = 6;             // account data (variable length)
  uint64 write_version = 7;
  optional bytes txn_signature = 8;  // which tx caused this update
}

Commitment Levels

enum CommitmentLevel {
  PROCESSED = 0;   // fastest, may be rolled back
  CONFIRMED = 1;   // supermajority voted
  FINALIZED = 2;   // irreversible
}

Slot Status

enum SlotStatus {
  SLOT_PROCESSED = 0;
  SLOT_CONFIRMED = 1;
  SLOT_FINALIZED = 2;
  SLOT_FIRST_SHRED_RECEIVED = 3;
  SLOT_COMPLETED = 4;
  SLOT_CREATED_BANK = 5;
  SLOT_DEAD = 6;
}

Parsing Checklist

When processing a SubscribeUpdateTransaction:

1. Signature: base58.b58encode(info.signature).decode() 2. Account keys: Decode each 32-byte entry in message.account_keys to base58 3. Instructions: For each CompiledInstruction:

• Program = account_keys[program_id_index]
• Accounts = [account_keys[i] for i in accounts]
• Data = raw bytes, first 8 bytes are typically the instruction discriminator

4. Inner instructions: CPI calls generated during execution — same structure as top-level 5. Token changes: Compare pre_token_balances vs post_token_balances for swap amounts 6. SOL changes: Compare pre_balances vs post_balances for fee and SOL transfer analysis 7. Logs: meta.log_messages contain program logs (useful for debugging) 8. Compute: meta.compute_units_consumed for gas analysis

Yellowstone gRPC — Provider Comparison

Shyft

• Entry price: $199/mo (Build plan)
• Endpoints: grpc.{region}.shyft.to — NY, VA, MIA, AMS, FRA, LON, SGP
• Auth: x-token from dashboard, or IP whitelisting
• Bandwidth: Unlimited (no metering)
• Connections: 10 (Build), 20 (Grow/$349), 50 (Accelerate/$649)
• Dedicated nodes: From $1,800/mo (unlimited connections, 5-10ms latency advantage)
• Historical replay: Up to 150 slots lookback
• Unique feature: RabbitStream — pre-execution shred-level data (transactions before confirmation, no metadata)
• DeFi parsing examples: github.com/Shyft-to/solana-defi — Raydium, PumpFun, Orca, Meteora parsers
• Connection management: Clear stale connections via https://grpc.{region}.shyft.to/clear-connections?xtoken=YOUR_TOKEN
• Best for: Price-sensitive teams, PumpFun/DEX trading, good regional coverage

Helius (LaserStream)

• Entry price: $999/mo (Professional plan, mainnet gRPC)
• Endpoints:
• US East: laserstream-mainnet-ewr.helius-rpc.com
• US West: laserstream-mainnet-slc.helius-rpc.com
• Europe: laserstream-mainnet-fra.helius-rpc.com
• Asia: laserstream-mainnet-tyo.helius-rpc.com
• Devnet: laserstream-devnet-ewr.helius-rpc.com
• Auth: API key as x-token
• Bandwidth: Credit-based + data add-ons ($500/5TB, scaling tiers)
• Historical replay: Up to 24 hours
• Unique features: DAS API (token/NFT metadata), enhanced webhooks, auto-reconnect, multi-node failover
• Best for: Teams already using Helius RPC/DAS, need rich Solana APIs beyond streaming

Triton One (Dragon's Mouth)

• Entry price: ~$2,900/mo (dedicated nodes)
• Bandwidth: ~$0.08/GB
• Auth: x-token
• Created Yellowstone: Triton built and open-sources the Yellowstone gRPC plugin
• Unique features:
• Deshred (SubscribeDeshred): Pre-execution transaction streaming (~6.3ms p50, ~20ms p90). Paid beta, limited availability
• Fumarole: Multi-node HA aggregator for persistent streaming
• Old Faithful: Historical data replay (full archive)
• Whirligig: Enhanced WebSocket proxy over Yellowstone
• Best for: HFT/MEV, lowest raw latency, enterprise infrastructure

QuickNode

• Entry price: Marketplace add-on (price depends on base plan)
• Port: 10000 (separate from RPC)
• Endpoint format: your-endpoint.solana-mainnet.quiknode.pro:10000
• Auth: Built into endpoint URL
• Rate limits: Tied to plan RPS (e.g., 125 RPS on Accelerate)
• Historical replay: Up to 3000 slots via from_slot
• Best for: Teams already on QuickNode, flexible add-on model

Chainstack

• Entry price: $49/mo (1 stream)
• Tiers: $49/1 stream, $149/5 streams, $449/25 streams
• Limits: Up to 50 accounts per stream, 5 concurrent filters of same type
• Features: Jito ShredStream enabled by default on all nodes
• Best for: Budget option, teams needing ShredStream bundled

Alchemy

• Entry price: Free tier (30M compute units/mo)
• Bandwidth: ~$0.08/GB for gRPC
• Pay-as-you-go: $5 per 11M compute units
• Best for: Experimentation, low-volume testing

GetBlock

• Entry price: Included with Dedicated Solana Node subscription
• Auth: Access token created after node deployment
• Features: Single TLS endpoint (no separate port config)
• Best for: Teams with existing GetBlock dedicated nodes

Provider Selection Guide

Authentication Code (All Providers)

All providers use the same x-token pattern:

import grpc, os

endpoint = os.environ["GRPC_ENDPOINT"].replace("https://", "")
token = os.environ["GRPC_TOKEN"]

auth = grpc.metadata_call_credentials(
    lambda ctx, cb: cb((("x-token", token),), None)
)
channel = grpc.secure_channel(
    endpoint,
    grpc.composite_channel_credentials(grpc.ssl_channel_credentials(), auth),
    options=[("grpc.max_receive_message_length", 64 * 1024 * 1024)],
)

use yellowstone_grpc_client::GeyserGrpcClient;
let mut client = GeyserGrpcClient::connect(endpoint, Some(token), None).await?;

import Client from "@triton-one/yellowstone-grpc";
const client = new Client(endpoint, token, {
  "grpc.max_receive_message_length": 64 * 1024 * 1024,
});

Yellowstone gRPC — Subscription Filters Reference

How Filters Work

A SubscribeRequest contains named filter maps. Each map key is a label you choose — it appears in the response's filters field so you know which subscription matched.

• Multiple filter types (transactions + accounts in same request) run independently
• Values within arrays (account_include: [A, B, C]) are logical OR
• Sending a new SubscribeRequest replaces all previous filters entirely
• To unsubscribe, send empty maps for all types

Transaction Filters

Filter real-time transactions by involved accounts, vote status, and failure status.

message SubscribeRequestFilterTransactions {
  optional bool vote = 1;              // include vote transactions?
  optional bool failed = 2;            // include failed transactions?
  optional string signature = 5;       // watch a specific signature
  repeated string account_include = 3; // tx must involve ANY of these
  repeated string account_exclude = 4; // tx must NOT involve ANY of these
  repeated string account_required = 6;// tx must involve ALL of these
}

Filter by Program ID

Subscribe to all successful transactions involving a DEX program:

transactions={
    "raydium_swaps": SubscribeRequestFilterTransactions(
        account_include=["675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8"],
        vote=False,
        failed=False,
    )
}

Filter by Multiple Programs

OR logic — matches transactions involving ANY listed program:

transactions={
    "all_dex": SubscribeRequestFilterTransactions(
        account_include=[
            "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",  # PumpFun
            "675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8",  # Raydium AMM
            "whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc",   # Orca
        ],
        vote=False,
        failed=False,
    )
}

Filter by Wallet (Copy Trading)

Watch specific wallets for any on-chain activity:

transactions={
    "tracked_wallets": SubscribeRequestFilterTransactions(
        account_include=[
            "WalletPubkey1...",
            "WalletPubkey2...",
        ],
        vote=False,
        failed=False,
    )
}

Exclude Known Programs

Exclude noisy programs to reduce volume:

transactions={
    "clean_feed": SubscribeRequestFilterTransactions(
        account_include=["TargetWallet..."],
        account_exclude=[
            "Vote111111111111111111111111111111111111111",
            "ComputeBudget111111111111111111111111111111",
        ],
        vote=False,
        failed=False,
    )
}

Require Multiple Accounts (AND logic)

Match only transactions that involve ALL listed accounts:

transactions={
    "wallet_on_pumpfun": SubscribeRequestFilterTransactions(
        account_required=[
            "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",  # PumpFun
            "SpecificWalletAddress...",                         # Target wallet
        ],
        vote=False,
        failed=False,
    )
}

Watch a Specific Transaction

Track confirmation of a submitted transaction:

transactions={
    "my_tx": SubscribeRequestFilterTransactions(
        signature="5wHu1qwD7q8ZHqDRYBiHMk2aJ4C8tNqVNK5...",
    )
}

Account Filters

Stream account data whenever it changes on-chain. Useful for tracking pool reserves, token balances, and program state.

message SubscribeRequestFilterAccounts {
  repeated string account = 2;    // specific account pubkeys
  repeated string owner = 3;      // accounts owned by these programs
  repeated SubscribeRequestFilterAccountsFilter filters = 4;
  optional bool nonempty_txn_signature = 5;
}

Watch Specific Accounts

accounts={
    "pool_reserves": SubscribeRequestFilterAccounts(
        account=["PoolAccountPubkey1...", "PoolAccountPubkey2..."],
    )
}

Watch All Accounts Owned by a Program

accounts={
    "all_token_accounts": SubscribeRequestFilterAccounts(
        owner=["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"],
        filters=[
            SubscribeRequestFilterAccountsFilter(token_account_state=True)
        ],
    )
}

Warning: Subscribing to all accounts owned by the Token Program produces enormous data volume. Always add filters to narrow the stream.

Memcmp Filter (Match Bytes at Offset)

Filter accounts by specific bytes at a given offset in account data:

# Match token accounts for a specific mint (mint pubkey at offset 0)
accounts={
    "sol_token_accounts": SubscribeRequestFilterAccounts(
        owner=["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"],
        filters=[
            SubscribeRequestFilterAccountsFilter(
                memcmp=SubscribeRequestFilterAccountsFilterMemcmp(
                    offset=0,
                    base58="So11111111111111111111111111111111111111112",
                )
            )
        ],
    )
}

Data Size Filter

Match accounts by exact data length:

accounts={
    "sized_accounts": SubscribeRequestFilterAccounts(
        owner=["YourProgramId..."],
        filters=[
            SubscribeRequestFilterAccountsFilter(datasize=165)  # SPL token account size
        ],
    )
}

Lamports Filter

Filter by SOL balance:

accounts={
    "whales": SubscribeRequestFilterAccounts(
        owner=["11111111111111111111111111111111"],
        filters=[
            SubscribeRequestFilterAccountsFilter(
                lamports=SubscribeRequestFilterAccountsFilterLamports(
                    gt=1_000_000_000_000  # > 1000 SOL in lamports
                )
            )
        ],
    )
}

Data Slicing

Reduce bandwidth by requesting only specific byte ranges of account data:

# Only first 40 bytes (discriminator + first key field)
accounts_data_slice=[
    SubscribeRequestAccountsDataSlice(offset=0, length=40)
]

Multiple slices are supported — you get concatenated results.

Slot Filters

slots={
    "slot_updates": SubscribeRequestFilterSlots(
        filter_by_commitment=True,
    )
}

Slot status values: PROCESSED, CONFIRMED, FINALIZED, FIRST_SHRED_RECEIVED, COMPLETED, CREATED_BANK, DEAD.

Block and Block Meta Filters

# Full blocks (high bandwidth)
blocks={
    "full_blocks": SubscribeRequestFilterBlocks(
        account_include=["ProgramId..."],  # optional: only blocks with this program
        include_transactions=True,
        include_accounts=False,
        include_entries=False,
    )
}

# Block metadata only (low bandwidth)
blocks_meta={
    "block_meta": SubscribeRequestFilterBlocksMeta()
}

Multiple Named Filters

Use different labels to multiplex subscriptions on one connection:

request = SubscribeRequest(
    transactions={
        "pumpfun": SubscribeRequestFilterTransactions(
            account_include=["6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P"],
            vote=False, failed=False,
        ),
        "whales": SubscribeRequestFilterTransactions(
            account_include=["Whale1...", "Whale2..."],
            vote=False, failed=False,
        ),
    },
    accounts={
        "pools": SubscribeRequestFilterAccounts(
            account=["Pool1...", "Pool2..."],
        ),
    },
    commitment=CommitmentLevel.PROCESSED,
)

# In the response, update.filters tells you which matched: ["pumpfun"], ["whales"], ["pools"]

Historical Replay

Resume from a specific slot (useful after disconnection):

request = SubscribeRequest(
    transactions={...},
    from_slot=last_seen_slot - 32,  # subtract for reorg safety
)

Replay depth varies by provider: Shyft ~150 slots, QuickNode ~3000 slots, Helius ~24 hours.