Yellowstone gRPC - Python Guide

Python guide for Yellowstone gRPC on FluxRPC. Generate protocol bindings and connect to streaming data with gRPC tools.

Setup

Install Python 3, pip, and the required dependencies:

Python Setup Shell

# Install Python gRPC tools
pip install grpcio==1.75.0 grpcio-tools==1.62.3
# Download proto files
curl -O https://raw.githubusercontent.com/rpcpool/yellowstone-grpc/master/yellowstone-grpc-proto/proto/geyser.proto
curl -O https://raw.githubusercontent.com/rpcpool/yellowstone-grpc/master/yellowstone-grpc-proto/proto/solana-storage.proto
# Generate Python code from proto files
python -m grpc_tools.protoc -I./proto --python_out=. --pyi_out=. --grpc_python_out=. ./proto/geyser.proto
python -m grpc_tools.protoc -I./proto --python_out=. --pyi_out=. --grpc_python_out=. ./proto/solana-storage.proto

Complete Example

This example subscribes to slot updates and demonstrates authentication, connection management, and processing streaming responses:

Python Slot Subscription Python

from typing import Optional
import grpc
import geyser_pb2
import geyser_pb2_grpc
import time
import queue
# Authentication Plugin
class TokenAuthPlugin(grpc.AuthMetadataPlugin):
    def __init__(self, token: str):
        self.token = token
    def __call__(self, context, callback):
        metadata = (("x-token", self.token),)
        callback(metadata, None)
# Setup connection
def setup_connection(endpoint, token):
    auth_plugin = TokenAuthPlugin(token)
    call_credentials = grpc.metadata_call_credentials(auth_plugin)
    ssl_credentials = grpc.ssl_channel_credentials()
    combined_credentials = grpc.composite_channel_credentials(
        ssl_credentials, call_credentials
    )
    return combined_credentials
# Subscribe to updates
def subscribe_to_slots(endpoint, token):
    credentials = setup_connection(endpoint, token)
    
    with grpc.secure_channel(endpoint, credentials=credentials) as channel:
        stub = geyser_pb2_grpc.GeyserStub(channel)
        
        # Create subscription request for slots
        subscribe_request = geyser_pb2.SubscribeRequest()
        slot_filter = geyser_pb2.SubscribeRequestFilterSlots()
        subscribe_request.slots["slot_updates"].CopyFrom(slot_filter)
        
        # Create request iterator
        request_queue = queue.Queue()
        request_queue.put(subscribe_request)
        
        def request_iterator():
            while True:
                try:
                    request = request_queue.get(timeout=30)
                    if request is None:
                        break
                    yield request
                except queue.Empty:
                    # Send ping to keep connection alive
                    ping_request = geyser_pb2.SubscribeRequest()
                    ping_request.ping.id = int(time.time())
                    yield ping_request
        
        # Subscribe and process updates
        response_stream = stub.Subscribe(request_iterator())
        
        print("✅ Connected! Listening for slot updates...")
        
        try:
            for update in response_stream:
                if update.slot:
                    print(f"🎰 Slot: {update.slot.slot}, Status: {update.slot.status}")
        except KeyboardInterrupt:
            print("\n🛑 Stopping subscription...")
            request_queue.put(None)
# Usage
if __name__ == "__main__":
    endpoint = "yellowstone.eu.fluxrpc.com"  # or yellowstone.us.fluxrpc.com
    token = "<your-API-key>"
    subscribe_to_slots(endpoint, setup_connection(endpoint, token))

Code Examples

For more examples including account subscriptions, transaction monitoring, and block streaming, check out the official Yellowstone gRPC repository:

Golang ExamplesRust Examples

Open the section overview for the broader context, live navigation, and interactive code examples.

Continue in this section

• Yellowstone gRPC - Protocol Reference — Protocol reference for Yellowstone gRPC on FluxRPC, including service definitions and Protocol Buffer message structures.
• Yellowstone gRPC - Streaming Overview — Stream real-time Solana blockchain data with Yellowstone gRPC. Subscribe to accounts, transactions, blocks, and slots with low latency.
• Yellowstone gRPC - Quick Start — Quick start guide for Yellowstone gRPC on FluxRPC. Connect, authenticate, and start streaming blockchain data in minutes.
• Yellowstone gRPC - Try It — Build a Yellowstone gRPC subscription in the browser and inspect the processed live response stream with FluxRPC.
• Yellowstone gRPC - Authentication — Authentication guide for Yellowstone gRPC on FluxRPC. Learn how to use API keys and request headers correctly.
• Yellowstone gRPC - API Reference — API reference for Yellowstone gRPC on FluxRPC, including SubscribeRequest and SubscribeUpdate message shapes.

← Back to documentation home