QuickStart

General gRPC Capability and Functional Background

Sui gRPC API provides high-performance access to network data via gRPC interfaces. It serves as a powerful tool for developers who need to:

• Lower latency and higher throughput – gRPC leverages HTTP/2 and binary Protobuf encoding for faster, more efficient communication than JSON-RPC.
• Strongly typed APIs – Protocol buffer definitions enable compile-time safety and reduce integration errors. Native streaming support – Clients can subscribe to real-time data (e.g., checkpoints or events) without polling.
• Reduced resource consumption – Efficient serialization and connection reuse lower bandwidth and CPU usage.
• Multi-language client generation – Auto-generated SDKs in Go, Rust, Python, TypeScript, and more simplify integration.
• Early access to advanced features – New Sui capabilities will be exposed first or exclusively via gRPC.

Support areas

• supported networks：sui-mainnet，sui-testnet
• supported methods：
  • sui.rpc.v2.LedgerService/GetServiceInfo
  • sui.rpc.v2.LedgerService/GetObject
  • sui.rpc.v2.LedgerService/BatchGetObjects
  • sui.rpc.v2.LedgerService/GetTransaction
  • sui.rpc.v2.LedgerService/BatchGetTransactions
  • sui.rpc.v2.LedgerService/GetCheckpoint
  • sui.rpc.v2.LedgerService/GetEpoch
  • sui.rpc.v2.MovePackageService/GetPackage
  • sui.rpc.v2.MovePackageService/GetDatatype
  • sui.rpc.v2.MovePackageService/GetFunction
  • sui.rpc.v2.MovePackageService/ListPackageVersions
  • sui.rpc.v2.NameService/LookupName
  • sui.rpc.v2.NameService/ReverseLookupName
  • sui.rpc.v2.SignatureVerificationService/VerifySignature
  • sui.rpc.v2.StateService/ListDynamicFields
  • sui.rpc.v2.StateService/ListOwnedObjects
  • sui.rpc.v2.StateService/GetCoinInfo
  • sui.rpc.v2.StateService/GetBalance
  • sui.rpc.v2.StateService/ListBalances
  • sui.rpc.v2.SubscriptionService/SubscribeCheckpoints
  • sui.rpc.v2.TransactionExecutionService/ExecuteTransaction
  • sui.rpc.v2.TransactionExecutionService/SimulateTransaction

Integration Method

1. grpc endpoint：https://grpc.zan.top
2. Metadata:
   1. x-token: api key（Required）
   2. x-network: ecosystem network（Required：sui-mainnet，sui-testnet）
   3. x-data-type: archive（Not required, just for Archive Store Data）

Integration Example Guide

• Steps
  Configuration

  # Example for Linux AMD64
  > wget https://github.com/fullstorydev/grpcurl/releases/download/v1.9.3/grpcurl_1.9.3_linux_x86_64.tar.gz
  tar -xvf grpcurl_1.9.3_linux_x86_64.tar.gz
  
  > mv grpcurl /usr/local/bin/
  
  > grpcurl --version
  grpcurl v1.9.3
  
  # Clone the repository with minimal depth
  > git clone https://github.com/MystenLabs/sui-apis.git --depth=1
  
  # Copy the proto files to your working directory
  > cp -r sui-apis/proto .

• SubscribeCheckpoints
  sui.rpc.v2.SubscriptionService/SubscribeCheckpoints

  grpcurl -proto sui/rpc/v2/subscription_service.proto \
    -d '{"read_mask": {"paths": ["sequence_number","digest","network_total_transactions","previous_digest"]}}' \
    -H "x-token: api_key" \
    -H "x-network: sui-mainnet" \
    grpc.zan.top:443 \
    sui.rpc.v2.SubscriptionService/SubscribeCheckpoints 

• GetObject
  sui.rpc.v2.LedgerService/GetObject

  grpcurl -proto sui/rpc/v2/ledger_service.proto \
  -d '{ "object_id": "0x27c4fdb3b846aa3ae4a65ef5127a309aa3c1f466671471a806d8912a18b253e8" }' \
  -H "x-token: api_key" \
  -H "x-network: sui-mainnet" \
  grpc.zan.top:443 \
  sui.rpc.v2.LedgerService/GetObject 

• GetEpoch(Query Data from Archive Store)
  sui.rpc.v2.LedgerService/GetEpoch

  grpcurl -proto sui/rpc/v2/ledger_service.proto \
  -d '{"epoch": 1}' \
  -H "x-token: api_key" \
  -H "x-network: sui-mainnet" \
  -H "x-data-type: archive" \
  grpc.zan.top:443 \
  sui.rpc.v2.LedgerService/GetEpoch 

gRPC-Web

Install Dependency

To get started, usenpm install to instal dependency

{
  "type": "module",
  "devDependencies": {
    "@mysten/sui": "^1.45.2"
  },
  "dependencies": {
    "@protobuf-ts/grpcweb-transport": "^2.11.1"
  }
}

Example

import { SuiGrpcClient } from '@mysten/sui/grpc';
import { GrpcWebFetchTransport } from '@protobuf-ts/grpcweb-transport';

// 1. add Header
const customFetch = (input, init) => {
  const headers = new Headers(init?.headers);
  headers.set('x-token', '<your-token>');
  headers.set('x-network', 'sui-mainnet');
  return fetch(input, { ...init, headers });
};

// 2. build gRPC-Web
const transport = new GrpcWebFetchTransport({
  baseUrl: 'https://grpc.zan.top:443',
  fetch: customFetch,
});

// 3. init client
const grpcClient = new SuiGrpcClient({
  transport,
});

// 4. query object
const { response } = await grpcClient.ledgerService.getObject({
  objectId: '0x27c4fdb3b846aa3ae4a65ef5127a309aa3c1f466671471a806d8912a18b253e8',
});
console.log(response);

• Output

Object {
  object: Object {
    objectId: '0x27c4fdb3b846aa3ae4a65ef5127a309aa3c1f466671471a806d8912a18b253e8',
    version: 912347514n,
    digest: 'hvF3FCvrv5denkfJUfQXY4wAJgfBiYPYSUcM7kejBMh'
  }
}

More examples referred to https://sdk.mystenlabs.com/sui/clients/grpc

proto

https://github.com/MystenLabs/sui-apis/tree/main/proto