gRPC
Overview
The Sui gRPC API is a fast, type-safe, and efficient interface for interacting with the Sui blockchain. It replaces the deprecated JSON-RPC protocol and is now generally available. gRPC uses Protocol Buffers for compact, high-performance data serialization, and supports both standard request-response calls and real-time server-side streaming — no polling required.
Note: JSON-RPC is deprecated and will be deactivated in July 2026. Migrating to gRPC is strongly recommended for all production integrations.
When to use gRPC
gRPC is the best choice when you need:
High-performance, low-latency point lookups for transactions, objects, and checkpoints
Real-time streaming subscriptions (replaces deprecated WebSocket support)
Strongly typed clients generated from
.protodefinitions in TypeScript, Go, Rust, and other languagesScalable backend systems — indexers, exchanges, bots, and dashboards
For frontends, developer tooling, or flexible filtered historical queries, consider GraphQL RPC as an alternative.
Important: gRPC full nodes do not automatically fall back to Archival Storage for historical data. If your integration requires deep historical lookups, use the Archival Storage and Services endpoint directly.
Endpoints
Free Test Endpoint (Mainnet — rate-limited)
We provide a free shared gRPC endpoint for testing and evaluation purposes. It is strictly rate-limited and intended for development use only, not for production traffic.
No authentication token is required for this endpoint.
Shared Clients
Shared plan clients access gRPC via the standard shared endpoint. Your unique endpoint hostname is available in the client panel.
Endpoint format:
Replace XXX with your specific endpoint slug shown in the panel.
Authentication is required via the X-Token header:
Both your endpoint and token can be found in your client panel.
Dedicated Clients
Dedicated plan clients have a private endpoint provisioned exclusively for their use.
Endpoint format:
Replace XXX with your dedicated endpoint slug shown in the panel.
Authentication is required via the X-Token header:
Both your endpoint and token can be found in your client panel.
Authentication
All non-free endpoints require the X-Token header to be included with every request. You can find your token in the client panel.
When using grpcurl:
When using a generated gRPC client (e.g. in Go or TypeScript), add the token as a metadata field on every call:
Available Services
The Sui gRPC API is defined via .proto files available in the sui-apis repository on GitHub. The following services are available:
TransactionExecutionService
Submit and execute signed transactions on the Sui network
LedgerService
Look up checkpoints, transactions, and objects from current state and recent history
StateService
Query live onchain data: balances, owned objects, dynamic fields; dry-run simulations
SubscriptionService
Stream live checkpoint updates in real time
MovePackageService
Access deployed Move package metadata and content
SignatureVerificationService
Validate signatures (including zkLogin) outside of transaction execution
NameService
Resolve SuiNS names to addresses and perform reverse lookups
Use these .proto definitions to generate type-safe client libraries in your language of choice.
Quickstart: grpcurl Examples
grpcurl is the easiest way to explore the API from the command line.
List available services
List methods in LedgerService
Get the latest checkpoint
Get a transaction (events and effects)
Subscribe to live checkpoints (streaming)
Key Concepts
Field Masks
Use read_mask to request only the fields you need, reducing response size and latency:
Pass "*" to request all fields. If read_mask is omitted, it defaults to *. In batch requests, only the top-level read_mask is respected.
Pagination
List APIs (owned objects, balances, etc.) return paginated results. Use page_size to control batch size and pass the returned next_page_token into the next request to continue. An empty next_page_token means you have reached the end. Keep all other request parameters constant between pages.
Encodings
AddressandObjectId: 64-character hex with a0xprefixDigest: Base58 encodedTypeTag/StructTag: Canonical string format
Errors
Errors follow the gRPC richer error model. Detailed error information is provided in the grpc-status-details-bin header as a Base64-encoded google.rpc.Status message.
Resources
Last updated
Was this helpful?