---
updatedAt: 2026-07-22T10:43:07.000Z
agentTools:
projectIndex: https://docs.tatum.io/llms.txt
---
# 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.
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](/reference/sui-grpc#get-a-checkpoint)
* [Get an object](/reference/sui-grpc#get-an-object)
* [Stream live checkpoints](https://docs.tatum.io/reference/sui-grpc#stream-live-checkpoints)
* And more
{`
Sui Mainnet gRPC endpoint
`}
{`
Don't have an API key?
Sign up to Dashboard and create your API keys today.
Get higher limits and use debugging tools.
`}
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.
## 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`.
```javascript
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`.
```javascript
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.
```javascript
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](https://docs.tatum.io/docs/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.
