gRPC Structured Queries

gRPC Structured Queries provide a high-performance, strongly typed alternative to traditional JSON-RPC for reading blockchain state. By utilizing Unary RPCs (request-response calls) over a persistent HTTP/2 connection, you can query balances, staking data, and governance state with greater efficiency and architectural clarity.

Unlike gRPC Data Streams, which push continuous updates, Structured Queries are designed for targeted data retrieval where precision and schema-correctness are the priority.

gRPC Pricing

What this page covers

This guide explains the advantages of using gRPC for state queries and how it differs from both traditional RPC and streaming interfaces.

🚀

Looking for Cosmos gRPC?

Tatum provides Cosmos gRPC for request-response queries to read balances, delegations, validators, staking data, governance state, or other module-backed chain data with a typed API.

👉 Check Cosmos gRPC

---

Why Use gRPC for Queries

Traditional JSON-RPC often requires "hand-rolling" JSON payloads and manually parsing untyped responses. gRPC changes this by using Protocol Buffers (Protobuf).

Key Benefits

• Strongly Typed Schemas: Develop against explicit Protobuf definitions. Your IDE can provide autocomplete for request parameters and response fields, reducing runtime errors.
• Compact Binary Payloads: gRPC uses a binary format that is significantly smaller than text-based JSON, reducing bandwidth and improving parsing speed for backend services.
• Code Generation: Generate native client libraries in languages like Go, Java, Python, or Rust, eliminating the need for manual boilerplate code.
• Persistent Connections: Execute multiple queries over a single, long-lived HTTP/2 connection to reduce the overhead of repeated TCP/TLS handshakes.

---

Event Subscriptions vs. Queries

It is important to distinguish how you interact with the chain state:

Structured Queries (Unary RPC)

You declare a specific request (e.g., "Give me the balance for Address A") and receive a single, structured response.

• Best for: Current state lookups, reading delegations, validator sets, and governance proposals.

Event Subscriptions (Streaming)

You declare a filter (e.g., "Notify me every time Address A receives a transaction") and receive a continuous stream of data as events occur.

• Best for: Real-time monitoring and triggering actions based on live chain activity.

---

gRPC vs. JSON-RPC

While both serve the purpose of querying the blockchain, gRPC is optimized for modern backend architectures that require high reliability and low overhead.

---

Typical Architecture

When using Structured Queries in production, the flow usually looks like this:

1. Application Layer: Initiates a query using a generated gRPC client.
2. Persistence Layer: A single gRPC channel is maintained to Tatum's gateway to avoid connection churn.
3. Data Logic: Responses are immediately mapped to native objects/structs thanks to the typed nature of Protobuf.
4. REST Parity: For environments where gRPC isn't natively supported, these queries often have REST equivalents via gRPC-gateway.

Next steps

To see structured queries in action on a supported chain, visit our reference documentation:

• Cosmos gRPC Reference