Skip to main content

What is gRPC?

The Sui Full Node gRPC API provides a fast, type-safe, and efficient interface for interacting with the Sui blockchain. Designed for power users, indexers, explorers, and decentralized apps, this API enables access to Sui data with high performance and low latency.

info

JSON-RPC is deprecated. Migrate to either gRPC or GraphQL RPC before the week of July 27, 2026, when JSON-RPC is disabled on Sui Foundation mainnet full nodes. Full decommission, including code removal, is planned for mid-October 2026. For a method mapping, decision criteria, and the full timeline, see the JSON-RPC Migration Guide.

Refer to the list of RPC or data providers that have enabled gRPC on their full nodes or offer GraphQL RPC. Contact a provider directly to request access. If your RPC or data provider doesn’t yet support these data access methods, ask them to enable support or contact the Sui Foundation team on Discord, Telegram, or Slack for help.

gRPC offers a high-performance, efficient communication protocol that uses Protocol Buffers for fast, compact data serialization. Its strongly typed interfaces reduce runtime errors and simplify client and server development across multiple languages.

The gRPC API replaces JSON-RPC on full nodes. JSON-RPC is deprecated and the gRPC API is generally available. Apart from the message and request format changes between the two, the gRPC API comes with a couple of key functional differences:

  • Use streaming or subscription API endpoints to consume real-time streaming data in your application without polling for those records. This support replaces the deprecated WebSocket support in JSON-RPC.

  • There is no implicit fallback from a full node gRPC endpoint to the Archival Store for historical data. If your gRPC client needs high-retention data, query an Archival Service endpoint directly. GraphQL can route supported historical lookups to Archival when the GraphQL operator configures it.

Release status​

gRPC polling and streaming APIs are generally available. JSON-RPC is deprecated, and JSON-RPC is disabled on Sui Foundation mainnet full nodes the week of July 27, 2026, with full decommission (including code removal) in mid-October 2026. For decision criteria, a JSON-RPC method mapping, the full timeline, and common migration gotchas, see the JSON-RPC Migration Guide.

warning

The gRPC and GraphQL RPC APIs have replaced JSON-RPC. View the video below to learn more about the migration timeline and which API to use.

When to use​

With built-in support for code generation, you can scaffold clients in TypeScript, Go, Rust, and more. This makes gRPC a strong fit for scalable backend systems, indexers, exchanges, and typed systems-language clients.

In addition to request-response calls, gRPC supports server-side streaming, enabling real-time data delivery without constant polling. Use gRPC when you need subscriptions, filtered queries over checkpoints, transactions, or events, generated protobuf clients, low protocol overhead, or low-latency point lookups. For frontends, developer tools, scripts, dynamic-language clients, or queries that join multiple resource types in a single request, consider GraphQL RPC first. Both gRPC and GraphQL support filtered queries over historical transactions and events; gRPC additionally supports streaming subscriptions with the same filters.

Trust boundary

gRPC is an API transport, not proof by itself: a response reflects what the node you queried returns, so it is only as trustworthy as that node. When you need trustless verification rather than trust in a single endpoint, use checkpoint verification, authenticated events, or the SignatureVerificationService.

How gRPC fits into the application stack​

The following gRPC services are available on Sui. Protocol buffers define the gRPC interface. You can find the relevant .proto files at sui-apis on GitHub, which apart from the gRPC messages (request and response payloads), include the following services:

Service.proto filePurpose
TransactionExecutionServicesui/rpc/v2/transaction_execution_service.protoSubmit and execute signed transactions on the Sui network. Wallets and apps use this service to send user actions to the network.
LedgerServicesui/rpc/v2/ledger_service.protoLook up specific checkpoints, transactions, objects, and more from the current state and recent history of the Sui network. Also provides streaming list APIs (ListCheckpoints, ListTransactions, ListEvents) for paginated, filtered queries over a checkpoint range. History refers to the recent past, limited to what a full node retains. The Archival Service implements the same LedgerService interface for long-term historical data beyond a full node's retention window.
StateServicesui/rpc/v2/state_service.protoQuery up-to-date onchain data like balances, coin metadata, dynamic fields, or owned objects. It also supports dry-run simulations for transactions.
SubscriptionServicesui/rpc/v2/subscription_service.protoStream live updates for checkpoints, transactions, and events with server-side filtering. Use SubscribeCheckpoints, SubscribeTransactions, or SubscribeEvents to receive only the data matching your filters. Ideal for building reactive systems such as indexers, bots, and dashboards. See Subscriptions for streaming data.
MovePackageServicesui/rpc/v2/move_package_service.protoAccess metadata and the content of Move packages deployed on the Sui network. Useful for tooling, analysis, and smart contract introspection.
SignatureVerificationServicesui/rpc/v2/signature_verification_service.protoValidate signatures outside transaction execution. Helps pre-verify payloads that might include zkLogin or other signatures, simulate authentication, or build custom signing workflows.
NameServicesui/rpc/v2/name_service.protoResolve human-readable SuiNS names to their underlying name records, and perform reverse lookups from Sui addresses back to linked names.

Use these definitions to generate client libraries in various programming languages.

info

If you were using the v2beta2 .proto files previously, the latest definitions are now under the v2 version. Also, the LiveDataService has been renamed to StateService, and the SimulateTransaction API has been moved to the TransactionExecutionService.

Subscriptions for streaming data​

The SubscriptionService provides real-time streaming updates for onchain activity through gRPC server-side streaming APIs. 3 subscription RPCs are available:

  • SubscribeCheckpoints streams finalized checkpoints, optionally filtered by a TransactionFilter. Use this when you need the full checkpoint structure, including all transactions and their events.
  • SubscribeTransactions streams individual executed transactions matching a TransactionFilter. Use this when you only need specific transactions (for example, those calling a particular Move function or affecting a specific address).
  • SubscribeEvents streams individual events matching an EventFilter. Use this when you only need specific events (for example, events of a particular Move type or emitted by a specific module).

All subscriptions begin at the current tip of the chain as seen by the server. They do not support resumption from a prior checkpoint. Each streamed response includes a progress marker (a cursor for SubscribeCheckpoints, or a Watermark for SubscribeTransactions and SubscribeEvents), so your application can track how far along the chain the stream has reached.

To combine historical and real-time data without gaps, open the subscription first, note the first progress marker (cursor or Watermark) in the stream, then backfill with the corresponding list API (ListCheckpoints, ListTransactions, or ListEvents) up to that point. The list APIs accept start_checkpoint and end_checkpoint bounds and return results as a server-side stream with cursor-based pagination through QueryOptions. Once the backfill is complete, begin consuming from the already-open subscription.

Streaming APIs are useful for building indexers, dashboards, or bots that need to react to real-time Sui activity with minimal latency.

Handling pruned data​

If a full node does not return a specific object, transaction, or checkpoint, the data might have been pruned based on the node's retention configuration. Full node gRPC does not automatically fall back to Archival. To access high-retention data, configure your application to query the Archival Store and Service directly.

You can reuse the same gRPC LedgerService methods for this lookup, but you must point the client at an Archival Service endpoint such as archive.mainnet.sui.io:443 or your provider's archival URL instead of the full node's URL.

Best practices​

  1. Always use field masks when applicable to reduce response size and latency, especially for large resources.

  2. Use TLS (port 443) for production traffic to ensure encrypted transport and prevent downgrade attacks.

  3. Use streaming subscriptions for real-time use cases instead of polling repeatedly.

  4. Generate client code from the official .proto definitions in sui-apis to ensure compatibility and type safety.

  5. Paginate carefully. Always check next_page_token and do not assume all data is returned at once.

  6. Retry transient failures with exponential backoff, especially for streaming APIs or busy public nodes.

  7. Validate all input data, including encodings and message formats, to prevent hard-to-debug API rejections.

Frequently asked questions​

Can I use field masks in batch requests?​

Only the top-level read_mask field is respected in batch requests like BatchGetObjects. Any field masks within individual GetObjectRequest items are ignored.

Why does the API return fewer results than the requested page_size?​

Even if you request a specific page_size, the server might return fewer items. This could be due to full node specific limits, filtered results, or reaching the end of available data.

Why do some fields say optional if they're required?​

In proto3, marking a field as optional gives the API the ability to detect field presence, that is, whether a field value is explicitly set or defaulted. This doesn't mean the field is optional in practice. You still need to follow the API contract to ensure the request is valid.

Full nodes might vary in which services and retention they support. Some services might not be supported yet or some APIs might return NOT_FOUND depending on the node's configuration and data availability.