Sui - Migration Guide from JSON-RPC to GraphQL

ui has officially deprecated JSON-RPC in favor of gRPC and GraphQL RPC.

GraphQL lets you fetch exactly the fields you need, join several resources (address → balances → objects → transactions) in a single request, and read multiple data types consistently at the same checkpoint. It is the best fit for frontends, wallets, explorers, developer tools, and clients written in dynamic languages. For backend pipelines, indexers, and streaming, see the gRPC migration guide.

This guide will help you transition your application to the Tatum Sui GraphQL Gateway.

Method Mapping: JSON-RPC to GraphQL

There is no one-to-one method list in GraphQL — instead you query fields on a typed graph. The tables below show which GraphQL field replaces each JSON-RPC method.

The transition involves mapping your old method calls to the new graphQL Services. There is no one-to-one method list. Multiple methods can use same graphQL fields with different filters or fields in response

Checkpoint & Transaction Queries

Object Queries

Balance & Coin Queries

Transaction Execution

Name Service

Key Differences

1. Numbers and Scalars

• BigInt values (balances, gas costs, supply, referenceGasPrice) are returned as Strings to prevent precision loss. Always parse them using BigInt().
• UInt53 values (checkpoint sequence numbers, versions, epoch IDs) are returned as JSON numbers and are safe for JavaScript Number.
• Addresses (SuiAddress) are returned in full 64-hex-character form (e.g. 0x2 → 0x000…0002). Normalize before comparing.

2. Select Only the Fields You Need

JSON-RPC used options objects (showEffects, showEvents, showContent, …). In GraphQL, you simply list the fields you want. Smaller selections mean faster responses and lower query cost.

3. Typed Arguments Instead of Positional Params

JSON-RPC params arrays are replaced by named, typed arguments. Pass dynamic values through variables rather than string interpolation.

4. Cursor Pagination

All lists are Relay-style connections (first/after, last/before, pageInfo { hasNextPage endCursor })

5. Limits

The service enforces a maximum query depth, node count, page size, payload size, and timeout. Query them with:

{
  serviceConfig {
    maxQueryDepth
    maxQueryNodes
    maxMultiGetSize
    queryTimeoutMs
    maxPageSize(type: "Query", field: "transactions")
  }
}

7. No Subscriptions

GraphQL does not offer streaming. Poll events/transactions with cursors, or use the gRPC SubscriptionService for real-time data.

Testing the Migration

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

curl -X POST 'https://sui-mainnet.gateway.tatum.io/graphql' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{ "query": "{ chainIdentifier checkpoint { sequenceNumber } }" }'

A successful response returns the mainnet chain identifier 4btiuiMPvEENsttpZC7CZ53DruC3MAgfznDbASZ7DR6S and the latest checkpoint number.