Sui - Migration Guide from JSON-RPC to gRPC

Sui has officially deprecated JSON-RPC in favor of gRPC.

gRPC offers 3-10x faster performance via binary Protocol Buffers, real-time streaming, and robust type safety that catches errors at compile time.

This guide will help you transition your application to the high-performance Tatum Sui gRPC Gateway.

Migration Checklist

1. Get your Tatum API Key: Your existing Tatum API key works for both protocols.
2. Install Dependencies: Add @grpc/grpc-js and @grpc/proto-loader to your Node.js project.
3. Download Protos: Clone the official sui-apis repository to get the required .proto files.
4. Update Authentication: Switch from JSON headers to gRPC metadata using the x-api-key key.

📘

NOTE

Find Tatum Sui gRPC Docs HERE.

Method Mapping: JSON-RPC to gRPC

The transition involves mapping your old method calls to the new gRPC Services.

Checkpoint & Transaction Queries

Object Queries

Balance & Coin Queries

Transaction Execution

Name Service

Code Comparison: Getting a Checkpoint

Before (JSON-RPC)

curl --location 'https://sui-mainnet.gateway.tatum.io' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {YOUR_API_KEY}' \
--data '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "sui_getCheckpoint",
  "params": [
    "{{blockheight}}"
  ]
}'

After (gRPC)

gRPC uses binary serialization. While you can still perform "request-response" calls, you benefit from significantly lower latency and smaller payloads.

📘

NOTE

Find Tatum Sui gRPC Docs HERE.

Key Differences

1. Error Handling

JSON-RPC returns errors in the response body (200 OK with an error object). gRPC uses standard status codes:

• Code 16 (Unauthenticated): Check your x-api-key.
• Code 5 (NOT_FOUND): Usually indicates pruned data (historical data no longer on the full node).

2. Numbers are Strings

To prevent precision loss with large blockchain numbers (like SUI balances), gRPC returns them as Strings. Always parse them using BigInt().

3. Field Masks

To optimize your app, use read_mask. This allows you to request only the specific fields you need (e.g., just the owner of an object), significantly reducing payload size.

Testing the Migration

Use grpcurl to quickly verify your Tatum connection from the terminal:

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

📘

NOTE

Find Tatum Postman Collection HERE