gRPC API Overview

FortiBlox Nexus gRPC provides high-performance, bidirectional streaming for real-time blockchain data. Built on Yellowstone gRPC protocol, it offers low-latency access to transactions, blocks, accounts, and slots with advanced filtering capabilities.

What is gRPC?

gRPC (gRPC Remote Procedure Call) is a modern, high-performance RPC framework that uses HTTP/2 for transport, Protocol Buffers for serialization, and provides features like:

• Bidirectional streaming - Real-time data flow in both directions
• Multiplexing - Multiple streams over single connection
• Header compression - Reduced bandwidth usage
• Strong typing - Protocol buffer schemas ensure data integrity
• Code generation - Auto-generate clients in multiple languages

Why Use gRPC for Blockchain Data?

Performance Benefits

• 10x lower latency compared to REST polling (< 10ms vs 100-500ms)
• 90% less bandwidth with binary protocol buffers vs JSON
• Higher throughput - handles 10,000+ events/second per stream
• Efficient multiplexing - multiple subscriptions over one connection

Developer Experience

• Type safety - Protocol buffers provide compile-time type checking
• Auto-generated clients - IDEs provide autocomplete and inline docs
• Backward compatibility - Protocol buffer versioning
• Multi-language support - Node.js, Python, Rust, Go, Java, C++, and more

Key Features

Yellowstone gRPC Compatible

100% compatible with Yellowstone gRPC protocol - use existing client libraries without modifications.

Real-time Streaming

Stream live blockchain data with minimal latency:

const stream = client.subscribe({
  transactions: {
    vote: false,
    failed: false,
    accountInclude: ['JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4']
  }
});

stream.on('data', (tx) => {
  console.log('New transaction:', tx.signature);
});

Historical Data Replay

Replay past transactions from any slot range:

request = SubscribeRequest(
    transactions={
        'jupiter_swaps': TransactionSubscribe(
            account_include=['JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4'],
            vote=False
        )
    },
    slots={'slots': SlotsSubscribe()},
    commitment=CommitmentLevel.CONFIRMED
)

for update in stub.Subscribe(request):
    if update.HasField('transaction'):
        print(f"Transaction: {update.transaction.signature}")

Advanced Filtering

Precise filtering reduces noise and bandwidth:

• Account filters - Include/exclude specific accounts
• Program filters - Filter by program ID
• Vote filters - Exclude vote transactions
• Commitment levels - Confirmed or finalized
• Slot ranges - Historical replay from specific slots

Network Endpoints

Subscription Methods

Subscribe (Bidirectional Streaming)

Main subscription endpoint for all data types:

rpc Subscribe(stream SubscribeRequest) returns (stream SubscribeUpdate);

Supports:

• Transaction streams
• Block streams
• Slot updates
• Account updates (coming soon)
• Block metadata
• Entry updates

Ping

Health check and connection testing:

rpc Ping(PingRequest) returns (PongResponse);

GetLatestBlockhash

Get the latest blockhash for transaction building:

rpc GetLatestBlockhash(GetLatestBlockhashRequest) returns (GetLatestBlockhashResponse);

Use Cases

DeFi Protocol Monitoring

Monitor DEX swaps and liquidity events in real-time:

const stream = client.subscribe({
  transactions: {
    'jupiter': {
      accountInclude: ['JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4'],
      vote: false
    }
  }
});

stream.on('data', async (update) => {
  if (update.transaction) {
    const swap = parseJupiterSwap(update.transaction);
    await notifyLargeSwap(swap);
  }
});

Real-time Dashboards

Power live blockchain explorers and analytics:

for update in stub.Subscribe(request):
    if update.HasField('slot'):
        # Update slot display
        dashboard.update_slot(update.slot)

    if update.HasField('block'):
        # Update block stats
        dashboard.update_block_stats({
            'slot': update.block.slot,
            'transactions': len(update.block.transactions),
            'timestamp': update.block.block_time.timestamp
        })

Transaction Monitoring

Track specific wallets or programs:

while let Some(update) = stream.next().await {
    match update {
        Ok(msg) => {
            if let Some(transaction) = msg.update_oneof {
                match transaction {
                    UpdateOneof::Transaction(tx) => {
                        if is_target_account(&tx) {
                            alert_transaction(&tx).await;
                        }
                    }
                    _ => {}
                }
            }
        }
        Err(e) => eprintln!("Stream error: {}", e),
    }
}

NFT Marketplace Indexing

Index NFT sales across all marketplaces:

stream, err := client.Subscribe(ctx)
if err != nil {
    log.Fatal(err)
}

// Subscribe to marketplace programs
err = stream.Send(&pb.SubscribeRequest{
    Transactions: map[string]*pb.SubscribeRequestFilterTransactions{
        "magic_eden": {
            AccountInclude: []string{MAGIC_EDEN_PROGRAM},
            Vote:          false,
        },
    },
})

for {
    update, err := stream.Recv()
    if err != nil {
        log.Fatal(err)
    }

    if tx := update.GetTransaction(); tx != nil {
        if sale := parseNFTSale(tx); sale != nil {
            indexSale(sale)
        }
    }
}

Authentication

gRPC requires API key authentication via metadata:

const grpc = require('@grpc/grpc-js');

const metadata = new grpc.Metadata();
metadata.add('x-api-key', process.env.FORTIBLOX_API_KEY);

const stream = client.subscribe(metadata);

metadata = [('x-api-key', os.getenv('FORTIBLOX_API_KEY'))]
stream = stub.Subscribe(request_iterator, metadata=metadata)

let token = MetadataValue::try_from(
    std::env::var("FORTIBLOX_API_KEY").unwrap()
).unwrap();

let mut request = tonic::Request::new(stream);
request.metadata_mut().insert("x-api-key", token);

md := metadata.New(map[string]string{
    "x-api-key": os.Getenv("FORTIBLOX_API_KEY"),
})
ctx := metadata.NewOutgoingContext(context.Background(), md)

stream, err := client.Subscribe(ctx)

Rate Limits & Quotas

Performance Characteristics

Latency

• Real-time streams: < 10ms (Redis pub/sub)
• Historical replay: Batch-optimized (1000 events/batch)
• Network latency: Depends on geographic location

Throughput

• Single stream: Up to 10,000 events/second
• Concurrent streams: 100+ simultaneous connections
• Backpressure handling: Automatic flow control

Reliability

• Automatic reconnection: Built into client libraries
• Message ordering: Guaranteed per-stream
• Slot gaps: Detected and reported
• Error handling: gRPC status codes with details

Comparison with Other APIs

Getting Started

Supported Languages

Official support and examples for:

• JavaScript/Node.js - @grpc/grpc-js
• Python - grpcio
• Rust - tonic
• Go - google.golang.org/grpc
• Java - grpc-java
• C++ - grpc-cpp

Community libraries available for many other languages.

Next Steps

1. Getting Started - Install and connect
2. Streaming Guide - Learn streaming patterns
3. Code Examples - Production-ready code
4. Protocol Reference - API specifications

Support

• Discord: discord.gg/fortiblox
• Email: [email protected]
• GitHub: github.com/fortiblox/geyser-grpc
• Examples: github.com/fortiblox/geyser-grpc/examples