yellowstone-grpc Checked

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

| Type | What You Get | Use Case |
|------|-------------|----------|
| `transactions` | Full transaction with metadata | DEX swap monitoring, copy trading |
| `accounts` | Account data on change | Pool reserve tracking, token supply |
| `slots` | Slot progression events | Block timing, confirmation tracking |
| `blocks` | Full block contents | Block-level analysis |
| `blocks_meta` | Block metadata only | Lightweight block tracking |
| `entry` | Block entries (shred groups) | Low-level validator data |
| `transactions_status` | Tx status without full data | Lightweight confirmation |

### 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

| Level | Speed | Safety | Use For |
|-------|-------|--------|---------|
| `PROCESSED` | Fastest | May be rolled back | Time-critical signals |
| `CONFIRMED` | ~400ms slower | Supermajority voted | Most trading use cases |
| `FINALIZED` | ~6-12s slower | Irreversible | Settlement verification |

## 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

| Program | Address | What It Does |
|---------|---------|-------------|
| PumpFun | `6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P` | Token launches, bonding curve trades |
| PumpSwap |