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:
- Live checkpoint stream: gRPC
SubscriptionService/SubscribeCheckpoints. - History past a full node’s retention: GraphQL
objectwith a version, or a read pinned withatCheckpoint. - One joined read (address, balance, objects, transactions): GraphQL.
- Typed client, field mask, or a hot point lookup: gRPC.
- 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:
- Live stream. Use gRPC. GraphQL has no subscriptions on Tatum. The published Tatum method is
SubscriptionService/SubscribeCheckpoints. - History past a full node’s retention. Use GraphQL fields such as
objectwith a version,objectVersions, andatCheckpoint. 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. - One response that joins several resources. Use GraphQL. Address, balance, objects, transactions, events, and a checkpoint can share a query.
- Typed clients, field masks, or a hot point lookup. Use gRPC. Mysten’s TypeScript SDK treats
SuiGrpcClientas the default andSuiGraphQLClientas the client for custom indexed queries. Point either client at the Tatum host. The SDK notes are in Sui Clients. - 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) |
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
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:
{
"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:
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
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
StateService/GetBalance - 2
StateService/ListOwnedObjects - 3
LedgerService/ListTransactions
SubscriptionService/SubscribeCheckpoints stays open. GraphQL has no matching stream. Poll with a cursor, or hand the live path to 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.
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:
{
"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:
{ "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)andtransactionEffectsfor status, gas, balance changes, and events on one digest.coinMetadata(coinType: "0x2::sui::SUI")for name, symbol, decimals, and supply.nameRecordresolves a SuiNS name such asmysten.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.
- https://sui-mainnet-grpc.gateway.tatum.io/_methods
- https://sui-mainnet-grpc.gateway.tatum.io/llms.txt
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.
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:
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.
One key, two pipes
A wallet and its indexer
Both hosts accept the same Tatum API key. The UI never opens the stream. The indexer never assembles the home-screen query.
A practical split for a new app:
- Render the portfolio with
address,balance, andobjects. - Open a transaction page with
transactionso effects, gas, and balance changes arrive together. - Ingest checkpoints over
SubscribeCheckpointsand store the sequence you have already applied. - Submit from the backend with
TransactionExecutionService/ExecuteTransactionwhen the worker is already a gRPC client. If the only client you have is GraphQL, theexecuteTransactionmutation 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
Use GraphQL when one request should join balances, objects, transactions, or events, and when the client is a frontend, explorer, or script. Use gRPC when you need SubscribeCheckpoints, a generated client, or a low-latency point lookup from a backend. Production apps often use both.
Yes. Mainnet GraphQL is https://sui-mainnet.gateway.tatum.io/graphql. Mainnet gRPC is sui-mainnet-grpc.gateway.tatum.io:443. Testnet and devnet follow the same host pattern. One Tatum API key covers both. The network grid is on the Sui RPC page.
No. Sui deprecated JSON-RPC in favor of gRPC and GraphQL. The foundation disabled it on mainnet full nodes the week of July 27, 2026. Joined reads move through the GraphQL migration guide. Backend pipelines move through the gRPC migration guide.
Yes. executeTransaction takes BCS transaction bytes and signatures and waits for finality. simulateTransaction dry-runs without signatures. gRPC exposes the same two jobs on TransactionExecutionService.
Tatum’s GraphQL endpoint does not stream. Poll events or transactions with a cursor, or stream checkpoints with gRPC SubscriptionService/SubscribeCheckpoints. On November 16, 2026, SubscribeTransactions and SubscribeEvents were also absent from Tatum’s mainnet /_methods list.
Code 5 usually means the object, transaction, or checkpoint is outside the full node’s retention. Read versioned history through GraphQL, or follow Full Nodes and Archive when you need data the node has pruned.
A keyless POST to https://sui-mainnet.gateway.tatum.io/graphql at 09:27:41 UTC returned chain identifier 4btiuiMPvEENsttpZC7CZ53DruC3MAgfznDbASZ7DR6S, checkpoint 345804791, and 0x2’s SUI balance string 2400568446767 (2,400.568446767 SUI at 9 decimals). GET https://sui-mainnet-grpc.gateway.tatum.io/_methods listed 28 methods. SubscribeTransactions, SubscribeEvents, ListEvents, and GetLatestCheckpoint were not in that list. A later keyless GraphQL call returned HTTP 429 at 5 requests per minute. This check did not time GraphQL against gRPC.
Sources
- Tatum: Sui GraphQL reference
- Tatum: Sui gRPC reference
- Tatum: Sui networks, methods, and endpoints
- GraphQL migration guide, from JSON-RPC
- gRPC migration guide, from JSON-RPC
- Sui: when to use GraphQL or gRPC
- Sui: JSON-RPC migration guide
- Mysten: Sui clients
- Stack Overflow: when to use gRPC vs GraphQL
- Chainstack: Sui GraphQL vs gRPC
- OnFinality: Sui JSON-RPC, gRPC, and GraphQL



