Sui - gRPC

Sui gRPC is a high-performance, type-safe interface designed for power users, indexers, and decentralized applications. Utilizing Protocol Buffers and HTTP/2, it provides low-latency access to the Sui blockchain, replacing the deprecated JSON-RPC for full node interactions.

With Tatum’s Sui gRPC endpoint, you can:

• Get a checkpoint
• Get an object
• Stream live checkpoints
• And more

Sui Mainnet gRPC endpoint

Sui gRPC (Mainnet)

▶️ Run in Postman🚀 Get Started

↳ gRPC (Mainnet)

https://sui-mainnet-grpc.gateway.tatum.io

🔍 Status🕵️ Explorer

Test Sui in Postman

Use the collection below to try gRPC calls against Tatum's Sui gateway.

Getting Started

Set Up Your Environment

This guide uses Node.js with macOS to interact with the Sui gRPC gateway. Because gRPC is strictly typed, you must manage .proto files to define the communication contract.

1. Install Node.js (version 18+)

   Shell

      brew install node
      node -v

2. Install grpcurl:
   Highly recommended for smoke testing your endpoint and API key.

   Shell

      brew install grpcurl

3. Create your project and install dependencies:

   Shell

      mkdir tatum-sui-grpc && cd tatum-sui-grpc
      npm init -y
      npm install @grpc/grpc-js @grpc/proto-loader

4. Set up Protobuf definitions:
   Sui gRPC uses the official proto definitions from the sui-apis GitHub repository. Clone or download the relevant .proto files:

   Shell

      git clone https://github.com/MystenLabs/sui-apis.git
      cp -r sui-apis/proto ./proto

   📘

   Note

   Sui proto files have deep interdependencies, so downloading individual files is not practical. Sui types import Google protobuf types, which import further types, and so on. Downloading files individually would require tracking and curling the full dependency chain manually.

   The key service definitions you can use are:

   Service	Proto file	Purpose
   LedgerService	sui/rpc/v2/ledger_service.proto	Query checkpoints, transactions, and objects
   StateService	sui/rpc/v2/state_service.proto	Query balances, owned objects, dry-run transactions
   TransactionExecutionService	sui/rpc/v2/transaction_execution_service.proto	Submit signed transactions
   SubscriptionService	sui/rpc/v2/subscription_service.proto	Stream live checkpoint updates
   MovePackageService	sui/rpc/v2/move_package_service.proto	Access Move package metadata
   NameService	sui/rpc/v2/name_service.proto	Resolve SuiNS names to addresses

5. Verify your connection with grpcurl:

   • Tatum-specific: The gRPC endpoint is sui-mainnet-grpc.gateway.tatum.io:443 (Mainnet).
   • Authentication: Uses the x-api-key header passed as metadata. Port 443 is required for SSL.
   Shell

      grpcurl \
        -H "x-api-key: YOUR_API_KEY" \
        -import-path . \
        -proto sui/rpc/v2/ledger_service.proto \
        -proto sui/rpc/v2/checkpoint.proto \
        sui-mainnet-grpc.gateway.tatum.io:443 \
        sui.rpc.v2.LedgerService/GetCheckpoint

   Expected response format:

   JSON

   {
     "checkpoint": {
       "sequenceNumber": "264536804",
       "digest": "26uaqDyg9ENJwL8URuWpXVnYxetjAQ779C6AQh7jypiF"
     }
   }

   🚧

   Attention

   • Run this command from inside the proto directory. The -import-path . flag tells grpcurl to resolve all proto imports relative to your current location.
   • Multiple -proto flags are required because Sui service definitions have interdependencies.
   • If you receive checkpoint data, your endpoint and API key are working correctly. If this step fails, no amount of Node.js code will fix it, confirm your environment setup and credentials before proceeding.

Quick start checklist

Before making your first production call, confirm:

• Successful smoke test: You can call GetLatestCheckpoint successfully using grpcurl with the x-api-key header.
• Proto files present: Your proto directory contains the full sui-apis proto tree. Missing files cause ENOENT loader errors.
• SSL configured: You are using grpc.credentials.createSsl() to connect via port 443. Non-TLS connections will be rejected.
• Error handling in place: Your application handles gRPC-specific error codes (e.g., Code 14: Unavailable for network issues, Code 16: Unauthenticated for key issues, Code 5: NOT_FOUND for pruned data).

Authentication in Node.js

1. Get the Sui gRPC URL.
2. Get an API Key from the Tatum Dashboard.
3. Configure your client with the endpoint and x-api-key:
   TypeScript

   const grpc = require('@grpc/grpc-js');
   
   const ENDPOINT = "sui-mainnet-grpc.gateway.tatum.io:443";
   const API_KEY = "YOUR_API_KEY";
   
   const meta = new grpc.Metadata();
   meta.add('x-api-key', API_KEY);

Example Requests

Get a checkpoint

Retrieves the latest checkpoint from the Sui network using the LedgerService.

const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const path = require('path');

const PROTO_FILE = path.join(__dirname, 'proto/sui/rpc/v2/ledger_service.proto');

async function main() {
  const packageDefinition = protoLoader.loadSync(PROTO_FILE, {
    keepCase: true,
    longs: String,
    enums: String,
    defaults: true,
    oneofs: true,
    includeDirs: [path.join(__dirname, 'proto')]
  });

  const suiProto = grpc.loadPackageDefinition(packageDefinition).sui.rpc.v2;
  const client = new suiProto.LedgerService(
    'sui-mainnet-grpc.gateway.tatum.io:443',
    grpc.credentials.createSsl()
  );

  const meta = new grpc.Metadata();
  meta.add('x-api-key', 'YOUR_API_KEY');

  client.GetCheckpoint({}, meta, (err, response) => {
    if (err) {
      console.error("RPC Error:", err.message);
      return;
    }
    console.log("Checkpoint:", JSON.stringify(response, null, 2));
  });
}

main().catch(console.error);

Get an object

Retrieves a specific on-chain object by its ID using the LedgerService.

const request = {
  object_id: "0x2"  // Example: the Sui system object
};

client.GetObject(request, meta, (err, response) => {
  if (err) {
    console.error("RPC Error:", err.message);
    return;
  }
  console.log("Object:", JSON.stringify(response, null, 2));
});

Stream live checkpoints

Uses the SubscriptionService to receive checkpoints in real time as they are finalized.

const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const path = require('path');

const PROTO_FILE = path.join(__dirname, 'proto/sui/rpc/v2/subscription_service.proto');

async function main() {
  const packageDefinition = protoLoader.loadSync(PROTO_FILE, {
    keepCase: true,
    longs: String,
    enums: String,
    defaults: true,
    oneofs: true,
    includeDirs: [path.join(__dirname, 'proto')]
  });

  const suiProto = grpc.loadPackageDefinition(packageDefinition).sui.rpc.v2;
  const client = new suiProto.SubscriptionService(
    'sui-mainnet-grpc.gateway.tatum.io:443',
    grpc.credentials.createSsl()
  );

  const meta = new grpc.Metadata();
  meta.add('x-api-key', 'YOUR_API_KEY');

  const stream = client.SubscribeCheckpoints({}, meta);

  stream.on('data', (checkpoint) => {
    console.log("New checkpoint:", JSON.stringify(checkpoint, null, 2));
  });

  stream.on('error', (err) => {
    console.error("Stream error:", err.message);
  });

  stream.on('end', () => {
    console.log("Stream ended.");
  });
}

main().catch(console.error);

Handling pruned data

If a full node returns NOT_FOUND for a specific object, transaction, or checkpoint, the data has likely been pruned based on the node's retention configuration. For historical data beyond this window, see Full Nodes and Archive.

Troubleshooting

1. ENOENT (missing proto file)

   • Symptom: Error: ENOENT: no such file or directory pointing to a .proto import.
   • Cause: The sui-apis proto tree has internal imports. A missing file anywhere in the dependency chain breaks loading.
   • Fix: Ensure you cloned the full sui-apis/proto directory. Do not selectively copy individual files.

2. Common connection issues

   • Auth failures: Confirm the header name is exactly x-api-key and you are using the correct API key.
   • Port 443 & SSL: Always use grpc.credentials.createSsl(). Insecure connections will be rejected.
   • Timeouts: For long-running streaming calls, implement reconnect logic and resume from the last processed checkpoint sequence number.

3. Field masks

   • Use read_mask to request only the fields you need. This reduces response size and improves latency, especially for large objects or batch requests.