WebSockets & gRPC

Ways to Access Real-Time Data

Data streaming lets your app receive blockchain updates as they happen. Instead of repeatedly polling for new data, your client keeps a persistent connection and receives new events as they become available.

This is recommended for applications that need up-to-the-second information, such as trading infrastructure, DeFi backends, indexers, wallet backends, monitoring systems, and real-time analytics.

Tatum provides two push-based options for consuming real-time data:

• WebSocket Event Subscriptions (Push): real-time updates over a standard web protocol, with no gRPC tooling required. This is the recommended starting point for browser applications, wallets, dashboards, and general-purpose backend services. Available on Solana, Ethereum, and Polygon.
• gRPC Streaming (Push): strongly typed, high-throughput data streaming over HTTP/2 and Protocol Buffers. Best for high-frequency backends, indexers, and large-scale ingestion pipelines.

Tatum also supports additional gRPC interaction models on selected blockchains:

• Structured Queries (Request-response): retrieve specific blockchain state, such as balances, delegations, validators, or governance data.
• Hybrid gRPC (Push + Request-response): combine structured queries and streaming subscriptions through a single gRPC endpoint.

---

WebSocket Event Subscriptions

WebSocket subscriptions let your application receive blockchain events over a persistent WebSocket connection. Once subscribed, your application receives new data as it becomes available instead of repeatedly polling an RPC endpoint.

Depending on the blockchain and subscription method, you can subscribe to blocks, transactions, logs, account updates, contract events, or other chain-specific data.

• Key features: standard WebSocket protocol, real-time event delivery, JSON-based payloads, chain-specific filters, and broad client-library support
• Best for: wallets, dashboards, DeFi applications, monitoring systems, and moderate-volume backend services

WebSockets are the recommended starting point for most real-time applications. They are easier to integrate than gRPC and do not require generated Protobuf clients or additional gRPC tooling.

---

gRPC Solutions

gRPC uses HTTP/2 and Protocol Buffers to provide efficient binary transport and strongly typed request and response schemas.

Compared to WebSockets, gRPC generally requires additional client tooling and generated Protobuf definitions. It is best suited to backend systems where throughput, type safety, and predictable schemas are more important than integration simplicity.

gRPC Streaming

gRPC streaming provides a live stream of blocks, transactions, account updates, and other blockchain data. It uses a persistent connection to push new data to your client as it becomes available.

• Key features: compact binary transport, strongly typed Protobuf schemas, high-throughput delivery, server-side streaming, flow control, and backpressure support
• Best for: high-frequency backend services, indexers, ingestion pipelines, and systems where low latency and high throughput are critical

With gRPC streaming, your application processes new blockchain data as it arrives without repeatedly polling for updates.

Structured Queries

Structured queries use unary gRPC methods for request-response interactions. Your application sends a request for specific blockchain state and receives a strongly typed response.

Unlike WebSocket subscriptions and gRPC streams, structured queries do not continuously push data to your application. They provide a typed and efficient alternative to JSON-RPC for supported blockchain queries.

• Key features: Protobuf-based query services, strongly typed request and response messages, generated clients, and efficient binary transport
• Best for: reading balances, delegations, validator information, staking data, governance state, and other module-backed blockchain data

Hybrid

Some blockchains expose both request-response methods and streaming subscriptions through a single gRPC endpoint.

This allows your application to retrieve specific blockchain state and subscribe to live updates using one protocol and a shared set of Protobuf schemas.

• Key features: unary request-response methods and server-side streaming over one endpoint, strongly typed Protobuf schemas across both models, and a single integration surface for state queries and live data
• Best for: indexers combining historical lookups with live ingestion, wallet backends reading balances and monitoring new activity, and applications retrieving blockchain state while following new checkpoints or events

---

Choosing the Right Solution

Start with WebSockets when you need real-time blockchain updates through a familiar and easy-to-integrate protocol.

Choose gRPC Streaming when throughput, strongly typed schemas, and efficient binary transport are critical.

Use gRPC Structured Queries for typed request-response access to blockchain state. Use standard JSON-RPC for individual blockchain requests or when another interface is not available.

Production Checklist

Before shipping a real-time data integration to production, validate:

• Automatic reconnection with exponential backoff and jitter
• Recreation of WebSocket subscriptions after reconnecting
• Keep-alive and connection timeout handling
• Replay, cursor, slot, block, or checkpoint recovery after disconnections
• Idempotent consumers that safely handle duplicate messages
• Protection against missing or out-of-order events
• Monitoring for connection status, stream lag, error rate, and throughput
• Buffering and backpressure handling during traffic bursts
• Capacity planning for peak blockchain activity

Do not assume that a persistent connection guarantees exactly-once delivery. Your application should be able to recover from disconnections, retrieve missing data where supported, and safely process duplicate events.