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:

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.

Sui Mainnet gRPC Postman collection

Get your API key: Use your standard Tatum API key. For gRPC, this is passed via the x-api-key header (see Authentication below).
Import the collection: Open Postman using the button below to access the Sui gRPC-over-HTTPS collection.
Configure variables: Set host and API key per the collection's instructions.
Start testing: Call Sui gRPC methods (for example, GetObject or GetLatestCheckpoint) as provided in the collection.

▶️ Run gRPC in Postman

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.

Install Node.js (version 18+)
```
   brew install node
   node -v
```
Install grpcurl:
Highly recommended for smoke testing your endpoint and API key.
```
   brew install grpcurl
```

Create your project and install dependencies:

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

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

   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

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.
```
   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:
```
{
  "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

Get the Sui gRPC URL.
Get an API Key from the Tatum Dashboard.

Configure your client with the endpoint and x-api-key:

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

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.
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.
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.