The short version

Use Sui GraphQL for the screen. Use Sui gRPC for the pipe. Use both when the product has a UI and an indexer.

Stop at the first rule that matches:

  1. Live checkpoint stream: gRPC SubscriptionService/SubscribeCheckpoints.
  2. History past a full node’s retention: GraphQL object with a version, or a read pinned with atCheckpoint.
  3. One joined read (address, balance, objects, transactions): GraphQL.
  4. Typed client, field mask, or a hot point lookup: gRPC.
  5. Anything else: GraphQL for a frontend, explorer, or script. gRPC for an indexer or exchange backend.

Sui GraphQL is one query document over indexed chain data. Sui gRPC is Protocol Buffers over HTTP/2: point lookups, submits, and the live checkpoint stream. Both can simulate and execute a transaction. Only gRPC streams.

Tatum serves both on mainnet, testnet, and devnet. One x-api-key from the Sui page in the dashboard covers each host. Checked November 16, 2026: Tatum mainnet gRPC published 28 methods, and a keyless GraphQL read returned checkpoint 345804791 plus the SUI balance of 0x2. The reproduction steps are in Checked November 16, 2026. Field-level docs: Sui GraphQL and Sui gRPC.

JSON-RPC is the API to leave

Sui replaced JSON-RPC with two interfaces, gRPC and GraphQL RPC. The Sui Foundation disabled JSON-RPC on its mainnet full nodes the week of July 27, 2026, and planned to remove the code in mid-October 2026. New work should target the replacements.

Joined reads move through the GraphQL migration guide. Backend pipelines move through the gRPC migration guide. That gRPC page describes gRPC as 3 to 10 times faster than JSON-RPC, because the payload is binary. The 3 to 10 times figure compares gRPC with JSON-RPC. It does not compare gRPC with GraphQL, and this article does not turn it into a latency ranking.

The general shape of the choice is older than Sui. Stack Overflow’s gRPC vs GraphQL write-up still holds: GraphQL when the client should choose the shape of a read, gRPC when two services want a compact, typed contract. Sui’s own order is the five rules at the top of this page.

Pick by the job, in this order

Sui’s own data access guide tells you to stop at the first rule that matches:

  1. Live stream. Use gRPC. GraphQL has no subscriptions on Tatum. The published Tatum method is SubscriptionService/SubscribeCheckpoints.
  2. History past a full node’s retention. Use GraphQL fields such as object with a version, objectVersions, and atCheckpoint. A gRPC full node does not silently fall back to archive. NOT_FOUND (gRPC code 5) usually means the data was pruned. See Full Nodes and Archive.
  3. One response that joins several resources. Use GraphQL. Address, balance, objects, transactions, events, and a checkpoint can share a query.
  4. Typed clients, field masks, or a hot point lookup. Use gRPC. Mysten’s TypeScript SDK treats SuiGrpcClient as the default and SuiGraphQLClient as the client for custom indexed queries. Point either client at the Tatum host. The SDK notes are in Sui Clients.
  5. Otherwise. GraphQL for frontends, explorers, and scripts. gRPC for indexers, exchanges, and other backends.

Both interfaces can simulate and submit. GraphQL does that with simulateTransaction and the executeTransaction mutation. gRPC does it with TransactionExecutionService. Writes are available on either surface. Streaming is gRPC.

Question Use Sui GraphQL Sui gRPC
Best client Split by process Frontends, dashboards, explorers, scripts Indexers, exchanges, services that already speak protobuf
Request shape GraphQL for a tree of fields One nested query. You list the fields. One RPC method, or a server stream
Streaming gRPC Unavailable. Poll transactions or events with a cursor. SubscribeCheckpoints. Checked November 16, 2026.
Filtered event history GraphQL events by module, sender, type, or checkpoint range SubscribeEvents and ListEvents were absent from the published list
History GraphQL Object versions, package versions, reads pinned with atCheckpoint Limited to the full node’s retention
Submit and simulate Either executeTransaction, simulateTransaction ExecuteTransaction, SimulateTransaction
Trim the payload Either Select fields in the query read_mask on the RPC
Discover the surface Either Schema introspection. GraphiQL, Insomnia, or Postman can load it. /_methods, /llms.txt, server reflection, and the sui-apis protos
Auth Same key x-api-key HTTP header x-api-key gRPC metadata, TLS on port 443
Tatum mainnet Both https://sui-mainnet.gateway.tatum.io/graphql https://sui-mainnet-grpc.gateway.tatum.io
Job Use Call
Wallet screen GraphQL address { balance objects transactions }
Checkpoint stream gRPC SubscriptionService/SubscribeCheckpoints
Submit a transaction gRPC when the worker already speaks protobuf. GraphQL executeTransaction when the client is already a query document. TransactionExecutionService/ExecuteTransaction
Explorer page GraphQL transaction(digest)
Past object version GraphQL object(address, version)
Filtered events GraphQL events(filter)
Job picker for Sui APIs. Wallet screen is selected. Recommendation is GraphQL on https://sui-mainnet.gateway.tatum.io/graphql because one query can return balance, owned objects, and recent transactions. Other jobs listed: checkpoint stream, submit a transaction, explorer page, past object version, filtered events.

Decision

Which surface fits this job?

GraphQL

One query returns the SUI balance, a page of owned objects, and recent transactions for the address on screen.

address { balance objects transactions }

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

Pick a job. The recommendation follows Sui’s data-access order and the methods Tatum publishes.

Checked November 16, 2026

The numbers below are from keyless calls on November 16, 2026, from one client. gRPC on this host requires an API key, so this guide leaves latency out of the comparison.

The data object from the GraphQL read at 09:27:41 UTC:

json
{
  "chainIdentifier": "4btiuiMPvEENsttpZC7CZ53DruC3MAgfznDbASZ7DR6S",
  "checkpoint": {
    "sequenceNumber": 345804791,
    "timestamp": "2026-11-16T09:27:41.078Z"
  },
  "address": {
    "address": "0x0000000000000000000000000000000000000000000000000000000000000002",
    "balance": { "totalBalance": "2400568446767" }
  }
}

0x2 came back as 64 hex characters. totalBalance is a string. The GraphQL reference lists SUI at 9 decimals, so 2400568446767 is 2,400.568446767 SUI. A separate read at 09:25:57 UTC, checkpoint 345804360, returned serviceConfig: max depth 20, max nodes 300, max page size 50 on transactions, timeout 40,000 ms, max multi-get 200.

The gRPC census is GET https://sui-mainnet-grpc.gateway.tatum.io/_methods. The body listed 28 methods: 2 reflection methods and 26 sui.rpc.v2 methods. Present: SubscribeCheckpoints, GetCheckpoint, ListTransactions, GetBalance, ListOwnedObjects, ExecuteTransaction, SimulateTransaction. Absent: SubscribeTransactions, SubscribeEvents, ListEvents, and GetLatestCheckpoint. An empty GetCheckpoint is how the gRPC reference reads the latest checkpoint.

Sui’s protocol docs also describe transaction and event subscriptions. Those names were not on Tatum’s mainnet list during this check. An indexer that requires SubscribeTransactions or SubscribeEvents should use a host that publishes them, or take filtered history from GraphQL events and the live cursor from SubscribeCheckpoints.

After several keyless GraphQL calls, the gateway returned HTTP 429: “You have exceeded your limit of 5 requests per minute.” The same error text points paid plans at 200 requests per second. Treat that as the keyless cap observed on November 16, 2026, and confirm the current plan on plans and limits.

Repeat the check:

shell
curl -sS 'https://sui-mainnet-grpc.gateway.tatum.io/_methods'

curl -sS -X POST 'https://sui-mainnet.gateway.tatum.io/graphql' \
  -H 'content-type: application/json' \
  -d '{"query":"{ chainIdentifier checkpoint { sequenceNumber timestamp } address(address: \"0x2\") { address balance(coinType: \"0x2::sui::SUI\") { totalBalance } } }"}'

What a request looks like

A wallet home screen is the clearest schema difference. GraphQL walks the graph in one document. gRPC names a service and a method, then repeats that for the next fact.

Schema comparison. Left: one GraphQL query on address with balance, objects, and transactions. Right: three gRPC calls, StateService/GetBalance, StateService/ListOwnedObjects, and LedgerService/ListTransactions, plus SubscriptionService/SubscribeCheckpoints for a live stream. Tatum wordmark on the header.

Schema

Same wallet read, two shapes

GraphQL · one round trip

query Wallet($addr: SuiAddress!) {
  address(address: $addr) {
    balance(coinType: "0x2::sui::SUI") {
      totalBalance
    }
    objects(first: 5) {
      nodes { address version }
    }
    transactions(first: 5) {
      nodes { digest }
    }
  }
}

gRPC · one method each

  1. 1StateService/GetBalance
  2. 2StateService/ListOwnedObjects
  3. 3LedgerService/ListTransactions

SubscriptionService/SubscribeCheckpoints stays open. GraphQL has no matching stream. Poll with a cursor, or hand the live path to gRPC.

GraphQL selects a tree of fields. gRPC calls a method, then another method. The stream exists only on gRPC.

The wallet-screen join is why explorers and wallet UIs land on GraphQL. Three small gRPC calls are still the right shape when each call sits on a hot path and the client is generated from protos.

GraphQL on Tatum

The GraphQL URL is the Sui gateway host plus /graphql. Full query list, arguments, and sample responses are in the Sui GraphQL reference.

Network GraphQL endpoint
Mainnet https://sui-mainnet.gateway.tatum.io/graphql
Testnet https://sui-testnet.gateway.tatum.io/graphql
Devnet https://sui-devnet.gateway.tatum.io/graphql

Root fields on the GraphQL reference, grouped the same way as the gRPC services below:

Group GraphQL fields
Chain tip chainIdentifier, checkpoint, checkpoints, epoch, epochs, protocolConfigs
Address address, then balance, objects, transactions
History object with version or atCheckpoint, objectVersions, packageVersions
Events and names events, coinMetadata, nameRecord
Writes simulateTransaction, mutation executeTransaction
Caps serviceConfig

A smoke test from the migration guide. A healthy mainnet response includes the chain identifier 4btiuiMPvEENsttpZC7CZ53DruC3MAgfznDbASZ7DR6S and the latest checkpoint sequence. The November 16 read above is one such response.

shell
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 timestamp } }" }'

The wallet query, with the fields a home screen actually renders:

json
{
  "query": "query ($addr: SuiAddress!) { address(address: $addr) { address balance(coinType: \"0x2::sui::SUI\") { totalBalance } objects(first: 5) { nodes { address } pageInfo { hasNextPage endCursor } } } }",
  "variables": { "addr": "0x2" }
}

Lists use Relay cursors: first, after, pageInfo { hasNextPage endCursor }. Ask for fewer fields when the screen is simple. Depth, node count, page size, and timeout are enforced, and you can read the live caps instead of hard-coding them:

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

The reference’s sample of serviceConfig matches a live keyless read on November 16, 2026: depth 20, 300 nodes, page size 50 on transactions, a 40 second timeout, and a multi-get size of 200. Call serviceConfig again before you ship. Operators can change the caps.

Two fields people reach for first:

  • transaction(digest) and transactionEffects for status, gas, balance changes, and events on one digest.
  • coinMetadata(coinType: "0x2::sui::SUI") for name, symbol, decimals, and supply. nameRecord resolves a SuiNS name such as mysten.sui.

gRPC on Tatum

gRPC uses its own host. TLS is required. Pass the API key as metadata, not as a query string. The typed setup, including grpcurl and a Node client, is in the Sui gRPC reference. The same calls are in the Sui mainnet Postman collection.

Network gRPC endpoint
Mainnet sui-mainnet-grpc.gateway.tatum.io:443
Testnet sui-testnet-grpc.gateway.tatum.io:443
Devnet sui-devnet-grpc.gateway.tatum.io:443

Services on the mainnet list fetched November 16, 2026 from /_methods and Tatum’s Sui RPC page. The same 26 chain methods are what that URL returned. Reflection accounts for the other 2 of the 28 names.

Service Use it for
LedgerService Checkpoints, transactions, objects, epochs
StateService Balances, coin info, owned objects, dynamic fields
TransactionExecutionService ExecuteTransaction and SimulateTransaction
SubscriptionService SubscribeCheckpoints
MovePackageService Package, function, and datatype lookups
NameService LookupName and ReverseLookupName
SignatureVerificationService VerifySignature
CheckpointSummaryService Checkpoint summaries, lighter than a full checkpoint

Before you generate a client, read the live list. It is published for humans and for agents. On November 16, 2026 the mainnet file also had a short llms.txt (1,916 bytes) that points at the same method names.

Testnet and devnet use the same paths on sui-testnet-grpc.gateway.tatum.io and sui-devnet-grpc.gateway.tatum.io. Sui’s protocol also defines transaction and event subscriptions. If a method is absent from /_methods, do not code against it on that host.

Smoke test from the proto directory. Clone sui-apis first. The proto tree imports itself, so a single downloaded file will not load.

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

SubscribeCheckpoints stays open for a live indexer. Store the last sequence you applied, and resume from that sequence after a disconnect:

javascript
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', process.env.TATUM_API_KEY);

const stream = client.SubscribeCheckpoints({}, meta);
stream.on('data', (checkpoint) => {
  // persist sequenceNumber, then advance
});

The full Node sample, including GetObject, is in the gRPC reference. Use read_mask when you only need the owner or the digest. Reconnect on Unavailable (code 14). Unauthenticated (code 16) means the metadata key is missing or wrong.

Use both

Exchanges and indexers on Sui tend to split the process the same way the foundation describes. The UI and support tools speak GraphQL. The ingestion worker speaks gRPC, then the product reads its own database for anything the screen asks twice.

Architecture: a wallet UI calls Tatum Sui GraphQL, an indexer calls Tatum Sui gRPC SubscribeCheckpoints, and both reach Sui through the Tatum gateway on one API key.

One key, two pipes

A wallet and its indexer

Wallet UI balance, objects, recent sends
GraphQL sui-mainnet.gateway.tatum.io/graphql
Indexer checkpoint cursor in your database
gRPC SubscribeCheckpoints

Both hosts accept the same Tatum API key. The UI never opens the stream. The indexer never assembles the home-screen query.

GraphQL answers the screen. gRPC feeds the database. Sui sits behind the Tatum gateway either way.

A practical split for a new app:

  • Render the portfolio with address, balance, and objects.
  • Open a transaction page with transaction so effects, gas, and balance changes arrive together.
  • Ingest checkpoints over SubscribeCheckpoints and store the sequence you have already applied.
  • Submit from the backend with TransactionExecutionService/ExecuteTransaction when the worker is already a gRPC client. If the only client you have is GraphQL, the executeTransaction mutation is the documented path and waits for finality.
  • After a submit, poll transaction(digest) before you trust indexed fields such as a fresh balance. The GraphQL reference notes that effects can lag the moment of finality.

JSON-RPC methods, mapped

There is no single GraphQL method named suix_getBalance. You select a field. gRPC maps more closely onto a service method. The full tables are in the two migration guides. The rows below are the ones most apps hit first.

JSON-RPC GraphQL gRPC
sui_getLatestCheckpointSequenceNumber checkpoint { sequenceNumber } LedgerService/GetCheckpoint
sui_getTransactionBlock transaction LedgerService/GetTransaction
suix_getBalance address { balance } StateService/GetBalance
suix_getOwnedObjects address { objects } StateService/ListOwnedObjects
suix_queryEvents events Read them from your checkpoint pipeline, or query GraphQL
sui_executeTransactionBlock executeTransaction TransactionExecutionService/ExecuteTransaction
sui_dryRunTransactionBlock simulateTransaction TransactionExecutionService/SimulateTransaction
suix_getCoinMetadata coinMetadata StateService/GetCoinInfo
suix_resolveNameServiceAddress address(name:) or nameRecord NameService/LookupName

Gotchas that break a migration

Balances, gas, and supply come back as strings. Parse them with BigInt. GraphQL UInt53 values, including checkpoint sequence numbers and epoch ids, are JSON numbers and are safe in JavaScript. gRPC still hands large integers back as strings when you load protos with longs: String.

GraphQL addresses arrive in full 32-byte form. 0x2 comes back as 64 hex characters after 0x. Normalize before you compare.

JSON-RPC errors arrived in a 200 body. gRPC uses status codes. Code 16 is the key. Code 5 is pruned or missing data. Code 14 is a transport blip worth a reconnect.

GraphQL will not stream. If a product needs “tell me when the next checkpoint lands,” open SubscribeCheckpoints. Cursor polling is the fallback for a dashboard that only has to be a few seconds fresh.

FAQ

Sources

Get a Sui API key