Sui gRPC Guide: Endpoints, Streaming & JSON-RPC Migration

Sui gRPC: Why It Is the Default Integration Path

Sui gRPC is the protocol-based RPC interface exposed by Sui full nodes. It uses Protocol Buffers (proto) over HTTP/2 for type-safe, compact, bidirectional communication. For production applications, gRPC is the recommended path because it reduces payload size, supports server streaming, and maps directly to Sui's object and checkpoint model.

OnFinality provides managed Sui gRPC and RPC infrastructure for mainnet and testnet. The exact endpoints and access details are published on the Sui network page (/networks/sui). Teams should treat gRPC as infrastructure: verify supported services, request visibility, and failover before moving sustained traffic.

If you are coming from JSON-RPC, plan migration around workflows rather than method-by-method copies. The same chain state is available, but gRPC groups operations into services such as LedgerService and TransactionExecutionService.

Safe Endpoint Setup with grpcurl and Authorization Placeholders

To experiment without a generated client, use grpcurl. Do not paste a public endpoint from a third-party unless you have explicit permission and understand rate limits. For OnFinality managed endpoints, use the placeholder GRPC_ENDPOINT and pass authentication metadata via -rpc-header. The exact host and token format are available from your provider dashboard or the /networks/sui page.

A minimal grpcurl listing looks like this:

• Use TLS (port 443) for managed services; plaintext localhost is only for self-hosted full nodes.
• Keep authorization tokens in environment variables or a secret manager; never commit them.
• Validate service list with grpcurl $GRPC_ENDPOINT list, then describe a service with grpcurl $GRPC_ENDPOINT describe <service>.

Core Sui gRPC Services and Their Responsibilities

The Sui gRPC API is grouped into services defined in proto files. The four services most relevant for builders are LedgerService, StateService, TransactionExecutionService, and SubscriptionService. Other services may exist for package metadata or signature verification; consult your client's generated stubs or the provider's service listing.

Reading Objects and Checkpoints

Sui's object-centric model means reading state often starts with an object ID or owner address. StateService handles object reads and related queries. You can retrieve individual objects, list objects owned by an address, and inspect dynamic fields using the generated client methods for those workflows. Because gRPC methods are typed, you work with object references and field masks where supported rather than free-form JSON params.

Checkpoint retrieval is served by LedgerService. A checkpoint is a certified set of transactions that bounds Sui finality. Use LedgerService methods to get the latest checkpoint sequence number, fetch a checkpoint by sequence or digest, and page through transaction lists within a checkpoint. This is a foundational pattern for indexers that need consistent, ordered data.

• Always capture sequence number, digest, and timestamp when processing checkpoints for resumability.
• For object reads, prefer field masks to control response size.
• Treat object versions as important: state queries may include an object version to reason about updates.

Executing and Simulating Transactions with TransactionExecutionService

TransactionExecutionService is where signed transaction execution and simulation live. Use SimulateTransaction to validate a transaction before sending it. Simulation accepts a transaction payload and returns effects without committing state, making it useful for estimating gas, checking Move errors, and previewing balance changes.

Use ExecuteTransaction for submitting a fully signed transaction for inclusion. The exact request fields are defined in the proto schemas and generated client wrappers; do not reconstruct those by hand. After calling ExecuteTransaction, track checkpoint inclusion or wait for effects through the client or subscription feed to confirm finality.

If a generated client uses a slightly different wrapper name, follow the generated method that exposes the ExecuteTransaction workflow.

• Simulate first, execute second.
• Keep the signed transaction bytes intact; don't modify after signing.
• Use idempotency or transaction digest checks for retries.

Streaming with SubscribeCheckpoints, SubscribeTransactions, and SubscribeEvents

SubscriptionService provides server-streaming RPCs for real-time chain activity. SubscribeCheckpoints pushes finalized checkpoints as they are certified. SubscribeTransactions streams executed transactions, and SubscribeEvents streams emitted Move events. These methods reduce polling and enable indexers, explorers, and alerting systems to react with low latency.

Each stream supports server-side filtering and field masks where the proto defines them. On reconnect, use the last processed checkpoint sequence or transaction digest to resume without gaps. For public or managed endpoints, be aware of stream timeouts and reconnection policies; test with long-lived clients.

• SubscribeCheckpoints: use for ordered chain state and indexing.
• SubscribeTransactions: use for transaction feeds and mempool observation.
• SubscribeEvents: use for listening to emitted Move event types.

Practical JSON-RPC to gRPC Migration Mapping

Migration is a workflow mapping, not a one-to-one method swap. Legacy JSON-RPC methods like suix_getObject, suix_getBalance, suix_executeTransactionBlock, and suix_subscribeEvent map conceptually to StateService, LedgerService, TransactionExecutionService, and SubscriptionService. However, the request and response shapes differ because gRPC uses protobuf messages, not SuiJSON.

Start by inventorying JSON-RPC calls in your codebase. Group them into reads (objects, balances), checkpoints, transaction execution/simulation, and subscriptions. Then implement each group using the generated gRPC client for your language. Keep the same application logic for parsing effects; adjust to native protobuf types.

Do not invent protobuf fields from JSON-RPC names. Generate stubs from the official Sui proto definitions or the provider's documented client libraries, then use the generated methods.

Mainnet and Testnet Considerations

Use separate endpoints for mainnet and testnet. Testnet is for development and testing, not production. The official Sui testnet faucet is https://faucet.sui.io; verify current faucet policy and limits before requesting tokens. Testnet data and endpoints are not permanent and may reset or change.

Mainnet endpoints require careful capacity planning and production monitoring. OnFinality's Sui network page (/networks/sui) lists current mainnet and testnet details. For testnet-specific setup, see /rpc-assistant/sui-testnet-rpc.

• Never reuse mainnet tokens or keys on testnet.
• Keep testnet and mainnet configs separated in your deployment pipeline.
• Treat testnet streams as ephemeral; build resumability from checkpoints.

Choosing an OnFinality Sui gRPC Plan and Operational Checks

When moving from shared to dedicated infrastructure, review these checks: Does the plan expose the required gRPC services? Are subscription streams allowed and what are their timeout/retention limits? Is there request and error visibility? Is a dedicated node needed for isolation or predictable capacity?

OnFinality's Sui RPC provider guidance (/rpc-assistant/sui-rpc-providers) and Sui RPC node page (/rpc-assistant/sui-rpc-node) explain the options. Use the Sui network page (/networks/sui) for endpoint facts.

Frequently Asked Questions