Sui gRPC API: A Practical Guide to the Typed Sui Interface

The Role of gRPC in Sui's Data-Access Strategy

Sui is progressively shifting its primary SDK and data-access path from legacy JSON-RPC toward a gRPC API with a generated, typed client. This move reflects a broader industry trend toward schema-driven interfaces that reduce integration errors and improve performance. For new integrations, understanding the gRPC surface is becoming essential, even as JSON-RPC and GraphQL remain available for specific use cases.

The Sui API references document three distinct data-access surfaces: JSON-RPC, gRPC, and GraphQL. Each serves different needs. JSON-RPC offers broad compatibility and a simple request-response model. GraphQL provides a query language over an indexer, allowing clients to specify the exact shape of the response. gRPC delivers a strongly typed, high-performance binary protocol with streaming capabilities. The Sui developer documentation provides SDK and data-access guidance that helps developers choose the right surface for their application.

This article focuses on the gRPC API: what it is, how it works at the protocol level, and how to call it using the Sui TypeScript SDK. It also contrasts gRPC with JSON-RPC and GraphQL so you can make an informed decision about which interface to use. For a broader overview of Sui network access, see the Sui networks page and the OnFinality Learn hub.

• gRPC is a modern, HTTP/2-based RPC framework using Protobuf for message serialization.
• Sui's gRPC API provides a typed client generated from a .proto service definition.
• It supports unary and streaming calls, enabling efficient data retrieval and real-time updates.
• The API is evolving; always pin your SDK version and check provider support.

gRPC Protocol Fundamentals: HTTP/2, Protobuf, and Streaming

gRPC is an open-source RPC framework that uses HTTP/2 as its transport and Protocol Buffers (Protobuf) as its interface definition language and message format. As described in the gRPC introduction, gRPC enables client and server applications to communicate transparently and simplifies the construction of connected systems. It supports four types of service methods: unary, server streaming, client streaming, and bidirectional streaming.

In a gRPC call, the client invokes a method on a service stub, passing a typed request message. The stub serializes the message into Protobuf binary format and sends it over an HTTP/2 stream. The server deserializes the request, processes it, and returns a typed response message. Because the service contract is defined in a .proto file, both client and server share the same schema, enabling code generation and compile-time type checking.

This contrasts with JSON-RPC, where the client sends a JSON object with a method name and parameters, and the server returns a JSON object. There is no formal schema, so type errors are only caught at runtime. gRPC's binary encoding is also more compact than JSON text, which can reduce bandwidth and improve performance, especially for large payloads or high-frequency calls.

• HTTP/2 multiplexing allows multiple concurrent calls over a single connection.
• Protobuf provides efficient binary serialization and strong typing.
• Streaming enables real-time data flows, such as transaction subscriptions.
• Generated client stubs reduce boilerplate and enforce the service contract.

Comparing Sui gRPC with JSON-RPC and GraphQL

Sui's JSON-RPC API is a traditional remote procedure call interface where each request specifies a method name and a JSON payload. It is widely supported and easy to use from any HTTP client, but it lacks a formal schema, so developers must consult documentation to know the expected parameters and response shape. The Sui RPC guide (RPC Assistant) covers JSON-RPC usage in detail. JSON-RPC methods are also subject to deprecation, as noted in the Sui JSON-RPC method deprecation article.

Sui GraphQL, by contrast, is a query language over an indexer. Clients specify the exact fields they need, and the server returns only that data. This flexibility is powerful for complex queries and historical aggregation, but it requires an indexer and may not be suitable for real-time transaction submission. The Sui GraphQL API query surface article explores this surface in depth.

gRPC sits between these two extremes. It offers a typed, schema-driven interface like GraphQL, but with the performance and streaming capabilities of a binary protocol. Unlike GraphQL, gRPC is not a query language; you call predefined methods with typed requests. Unlike JSON-RPC, gRPC requires code generation and an HTTP/2-capable environment. For new integrations that need type safety and efficiency, gRPC is increasingly the preferred choice.

• JSON-RPC: method + JSON text, no schema, broad compatibility.
• GraphQL: query language over an indexer, client-specified response shape.
• gRPC: typed client, Protobuf binary encoding, streaming, HTTP/2 required.
• Each surface has trade-offs; choose based on your application's needs.

Anatomy of a Sui gRPC Call at the Protocol Level

At the protocol level, a Sui gRPC call begins with a client stub invoking a service method, such as GetTransaction or GetObject. The client constructs a typed request message, for example a GetTransactionRequest containing a transaction digest. The stub serializes this message into Protobuf binary and sends it over an HTTP/2 stream to the server. The server processes the request and returns a typed response message, such as a GetTransactionResponse, which the client deserializes into a native object.

This is fundamentally different from a JSON-RPC call, where the client sends an HTTP POST with a JSON body like {"jsonrpc":"2.0","method":"sui_getTransactionBlock","params":["0x..."],"id":1}. The JSON-RPC server parses the JSON, executes the method, and returns a JSON response. There is no compile-time contract; the client must know the method name and parameter order from documentation.

The gRPC service definition is contained in a .proto file, which the Sui SDK wraps and exposes as a typed client. This means you can use auto-completion and type checking in your IDE, reducing the risk of runtime errors. The SDK also handles connection management, serialization, and deserialization, so you can focus on application logic.

// Example .proto snippet (simplified)
service SuiGrpcService {
  rpc GetTransaction(GetTransactionRequest) returns (GetTransactionResponse);
  rpc GetObject(GetObjectRequest) returns (GetObjectResponse);
}

message GetTransactionRequest {
  string digest = 1;
}

message GetTransactionResponse {
  Transaction transaction = 1;
}

Setting Up the Sui TypeScript SDK for gRPC

To call the Sui gRPC API from Node.js or TypeScript, you need the Sui TypeScript SDK, which includes a gRPC client. The SDK is available on npm and can be installed with a package manager. Before you begin, ensure your environment supports HTTP/2, as gRPC requires it. Node.js has built-in HTTP/2 support, so it works out of the box.

You will also need a Sui gRPC endpoint. Providers like OnFinality offer Sui RPC endpoints; check the API service page for available interfaces. Always verify that your provider supports gRPC, as not all RPC endpoints expose it. The RPC pricing page can help you choose a plan that includes gRPC access.

Once installed, you can import the gRPC client and create a connection. The SDK typically provides a SuiGrpcClient class or similar, which you instantiate with the endpoint URL. You may also need to configure authentication if your provider requires an API key. Refer to the SDK documentation for the exact class names and configuration options, as they may change between versions.

// Install the Sui TypeScript SDK
npm install @mysten/sui

// Import the gRPC client (class name may vary by SDK version)
import { SuiGrpcClient } from '@mysten/sui/grpc';

// Create a client instance
const client = new SuiGrpcClient({
  url: 'https://sui-grpc.example.com', // replace with your provider's gRPC endpoint
  // apiKey: 'your-api-key', // if required
});

Runnable Example: Querying a Transaction with the Typed gRPC Client

The following Node.js/TypeScript example demonstrates how to connect to a Sui gRPC endpoint and retrieve a transaction by its digest using the typed client. It then shows the equivalent operation using JSON-RPC for comparison. This example assumes you have installed the Sui TypeScript SDK and have a gRPC endpoint URL.

Replace the placeholder endpoint and transaction digest with your own values. The example uses async/await for readability. Note that the exact method names and response structures may differ slightly depending on the SDK version; always consult the SDK's documentation or type definitions.

After running the example, you should see the transaction details printed to the console. The gRPC response is a typed object, while the JSON-RPC response is a plain JSON object. This illustrates the difference in developer experience: with gRPC, your IDE can provide auto-completion and type checking for the response fields.

import { SuiGrpcClient } from '@mysten/sui/grpc';
import fetch from 'node-fetch'; // for JSON-RPC comparison

const GRPC_URL = 'https://sui-grpc.example.com';
const JSON_RPC_URL = 'https://sui-json-rpc.example.com';
const TX_DIGEST = '0x...'; // replace with a real transaction digest

async function queryWithGrpc() {
  const client = new SuiGrpcClient({ url: GRPC_URL });
  const response = await client.getTransaction({ digest: TX_DIGEST });
  console.log('gRPC response:', response);
  // response is a typed object, e.g., response.transaction
}

async function queryWithJsonRpc() {
  const body = {
    jsonrpc: '2.0',
    method: 'sui_getTransactionBlock',
    params: [TX_DIGEST, { showInput: true, showEffects: true }],
    id: 1,
  };
  const res = await fetch(JSON_RPC_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });
  const json = await res.json();
  console.log('JSON-RPC response:', json);
}

(async () => {
  await queryWithGrpc();
  await queryWithJsonRpc();
})();

Reproducible Measurement: Comparing gRPC and JSON-RPC Calls

To evaluate the practical differences between gRPC and JSON-RPC for your use case, you can perform a reproducible measurement using your own endpoint. The table below provides a template for recording key metrics. Fill it in by running the same logical operation (e.g., fetching a transaction) over both interfaces and measuring the request and response sizes, as well as the response type.

Use a tool like curl with --trace-ascii or a network inspector to capture the raw bytes for JSON-RPC. For gRPC, you can use a gRPC client library's logging or a proxy like grpcurl to inspect the binary payload. Note that gRPC payloads are binary and may not be human-readable, but you can measure their size. The goal is to understand the trade-offs in your specific environment.

Remember that network conditions, endpoint location, and provider configuration can affect results. Run multiple trials and average the numbers. This method is not a benchmark; it is a way to make an informed decision based on your own measurements.

• Operation: e.g., GetTransaction
• gRPC call: e.g., client.getTransaction({ digest })
• JSON-RPC method: e.g., sui_getTransactionBlock
• Request bytes: measure raw payload size
• Response bytes: measure raw payload size
• Typed vs untyped response: gRPC returns typed object; JSON-RPC returns plain JSON

Limitations and Trade-offs of the Sui gRPC API

The Sui gRPC API is powerful, but it comes with limitations. First, gRPC endpoints and supported services vary by provider and network version. Not all RPC providers expose gRPC, and those that do may support only a subset of methods. Always check your provider's supported-interface list before integrating. OnFinality's API service page documents the interfaces available on its Sui endpoints.

Second, the API is evolving. The Sui gRPC interface is under active development, and breaking changes may occur between SDK versions. Pin your SDK version in your project to avoid unexpected breakage, and review release notes before upgrading. The Sui JSON-RPC method deprecation article highlights that JSON-RPC methods are also subject to change, so no interface is entirely static.

Third, gRPC cannot be called directly from a browser without a proxy. Browsers do not expose the necessary HTTP/2 framing and binary handling for gRPC. The Sui SDK provides a web-safe path, often using gRPC-Web or a proxy, but this adds complexity. If you are building a browser-based dApp, consider whether JSON-RPC or GraphQL might be simpler for your read operations.

Finally, gRPC is a read/write interface for the chain, but it does not replace an indexer for historical aggregation. If you need to query historical data across many transactions or compute aggregates, GraphQL or a dedicated indexer is more appropriate. gRPC is optimized for direct chain access, not for analytical queries.

• Provider support for gRPC varies; verify before committing.
• API is evolving; pin SDK version and monitor changes.
• Browser use requires a proxy or gRPC-Web; not direct.
• Not a replacement for indexers when historical aggregation is needed.

Troubleshooting Common gRPC Integration Issues

When integrating with the Sui gRPC API, you may encounter issues related to connectivity, serialization, or version mismatches. This section covers common problems and how to diagnose them. Start by verifying that your endpoint URL is correct and that your provider supports gRPC. A quick test with grpcurl can confirm connectivity and list available services.

If you receive a UNIMPLEMENTED error, the method you are calling may not be supported by your provider or may not exist in the version of the service you are targeting. Check the provider's documentation and the SDK's .proto definitions. If you get a DEADLINE_EXCEEDED error, the request timed out; consider increasing the deadline or checking network latency.

Serialization errors often stem from mismatched Protobuf definitions. Ensure that your client stubs are generated from the same .proto version as the server. If you are using the Sui SDK, this is handled for you, but if you are generating your own stubs, keep them in sync. For JSON-RPC comparison, remember that JSON-RPC errors are returned as JSON objects with an error field, while gRPC uses status codes.

For more troubleshooting tips specific to Sui RPC, see the Sui RPC guide (RPC Assistant). If you are migrating from JSON-RPC, the Sui transaction effects and object changes article explains how to parse transaction results, which is useful when comparing responses.

• Verify endpoint URL and provider gRPC support.
• Use grpcurl to test connectivity and list services.
• Check for UNIMPLEMENTED or DEADLINE_EXCEEDED status codes.
• Ensure Protobuf definitions match between client and server.

Next Steps: Integrating gRPC into Your Sui Application

Now that you understand the Sui gRPC API and how to call it, you can begin integrating it into your application. Start by choosing a provider that supports gRPC, such as OnFinality, and obtain an endpoint URL. Review the RPC pricing page to select a plan that meets your needs. Then, install the Sui TypeScript SDK and experiment with the typed client in a development environment.

As you build, consider the trade-offs between gRPC, JSON-RPC, and GraphQL. For read-heavy applications that need type safety and streaming, gRPC is a strong choice. For complex historical queries, GraphQL may be better. For simple, widely compatible integrations, JSON-RPC remains viable. You can also mix interfaces: use gRPC for transaction submission and JSON-RPC for legacy compatibility.

To deepen your understanding, explore related OnFinality Learn articles such as the Sui GraphQL API query surface and the Sui queryTransactionBlocks cursor pagination guide. These resources will help you build robust, efficient Sui applications. For a complete list of networks and services, visit the Sui networks page and the OnFinality Learn hub.

• Choose a gRPC-capable provider and obtain an endpoint.
• Install the Sui TypeScript SDK and test the typed client.
• Evaluate gRPC vs JSON-RPC vs GraphQL for your use case.
• Explore related Learn articles for deeper dives.