gRPC API

Overview

This page describes how the gRPC interface works and how it differs from HTTP RPC and WebSocket subscriptions. gRPC provides a high-performance, contract-based channel to a node using HTTP/2 for transport and Protocol Buffers for serialization. Unlike a single shared schema, gRPC on each network exposes that protocol's own native service definition. The available methods, message types, and streaming behavior therefore differ per network, and this page documents them individually.

What Is gRPC

gRPC is a remote procedure call framework that runs over HTTP/2 and encodes messages as Protocol Buffers (protobuf). A client generates typed stubs from a .proto service definition and calls remote methods as if they were local functions.

Why Use gRPC?

gRPC provides fast, strongly typed communication using HTTP/2 and Protocol Buffers. It is well suited for high-throughput backend integrations, compact payloads, and real-time data streaming where supported by the network.

How gRPC differs from HTTP RPC and WebSocket subscriptions

• HTTP RPC typically uses a request/response model over HTTP. Depending on the implementation, updates may require repeated requests or a separate subscription interface.
• WebSocket subscriptions keep a persistent connection open and push JSON events as they occur.
• gRPC multiplexes many calls over one HTTP/2 connection, transports compact binary protobuf instead of JSON, and supports both request/response calls and long-lived streams over the same connection. Typed stubs and a fixed schema remove the need to hand-build and parse payloads.

In practice gRPC is used where throughput, payload size, and strict typing matter — high-volume indexing, low-latency streaming where supported, and backend-to-node integrations.

Call types

gRPC defines four method types. Which ones a network supports depends on its node software:

• Unary — one request, one response (for example, fetch a block or an account).
• Server streaming — one request, a stream of responses (for example, subscribe to new checkpoints or blocks).
• Client streaming — a stream of requests, one response.
• Bidirectional streaming — independent request and response streams over one connection.

Protocol Buffers

Message and service contracts are defined in .proto files published by each protocol. Clients compile these into stubs for their language (Go, Rust, Python, Java, TypeScript, and others). Where a node has gRPC server reflection enabled, tooling such as grpcurl can discover services without a local copy of the .proto files.

How to Access gRPC

To access gRPC endpoints, register an account, choose any plan, create an API key, and connect to the gRPC endpoints listed in the documentation.

Connections use TLS. The API key is supplied as gRPC request metadata rather than in the URL path:

api-key: {YOUR_API_KEY}

Example connectivity check with grpcurl (server reflection enabled):

grpcurl -H "api-key: {YOUR_API_KEY}" \
  {NETWORK}-grpc.nownodes.io list

grpcurl covers reflection and unary calls only — it does not support streaming RPCs. To test streaming methods (Sui `SubscribeCheckpoints`, IOTA checkpoint streams, any Kaspa call), use buf curl or a generated client. Kaspa's interface is bidirectional-streaming end to end, so grpcurl cannot be used with it at all.

Example unary call:

grpcurl -H "api-key: {YOUR_API_KEY}" \
  {NETWORK}-grpc.nownodes.io \
  {package.Service}/{Method}

gRPC access is currently available only for Sui, TRON, Kaspa, IOTA, and XRP Ledger.

If you need guaranteed access or additional performance, you can request a dedicated node deployment for one of these networks in the dashboard or by contacting [email protected]. We will provide pricing and deployment time.

Supported Networks

gRPC access is available for the networks listed below. Each network exposes its protocol's native gRPC interface; the proto package and services differ accordingly.

Use Cases

Non-Custodial Wallets

• Query balances, UTXOs, and account state through typed unary calls.
• Track incoming and outgoing transfers by subscribing to address- or ledger-level streams where the network supports them.
• Broadcast signed transactions through the node's submit method.

Block Explorers

• Retrieve blocks, transactions, and ledger data with strongly typed responses.
• Follow chain progress in real time through block, checkpoint, or virtual-chain streams where the network supports them.

Web3 Analytics and Indexing

• Ingest high volumes of block and transaction data with low serialization overhead.
• Build custom indexers on top of streaming methods and replay recent state after a disconnect where the network exposes it.

Monitoring and Automation

• React to new blocks, score changes, and UTXO changes with minimal latency where streaming is available.
• Drive trading, alerting, and reconciliation backends from a single multiplexed connection.

Notes and Limits

• Transport. TLS is required. Connections use HTTP/2; a client that terminates HTTP/2 early (for example, through an incompatible proxy) cannot use gRPC.
• Authentication. The API key is sent as request metadata on every call, including streams.
• Keepalive and streams. Long-lived streams should send HTTP/2 keepalive pings and implement reconnection and gap recovery according to each network's API. Streaming and resume behavior are not uniform across the five supported networks.
• Message size. Large batch reads may exceed default client message-size limits; raise the client's maximum receive size if calls fail with a size error.
• Schema versions. Proto package versions can change as protocols promote gRPC from beta to stable. Regenerate stubs against the node release you connect to.