Sui gRPC developer guide: what to migrate, and how it works

For most of Sui’s short life, talking to a full node meant JSON-RPC — the same protocol pattern Ethereum, Solana, and nearly every other chain settled on years ago. It worked. It was easy. It was also the ceiling on what backend Sui applications could do.

Then Sui shipped gRPC as generally available and set a date for retiring JSON-RPC: public endpoints are already off, and JSON-RPC leaves the full node code in mid-October 2026. What that means for you depends on your provider, which of your calls need to move, and where they move to. Here’s how to think about it.

JSON-RPC decommissioning has started.

Sui Foundation's public mainnet JSON-RPC endpoints shut down July 28. Full decommission by mid-October.

Still on it? Migrate to gRPC or GraphQL RPC by using a data provider already running the new stack.

— Sui Developers (@suidevelopers) July 22, 2026

The short version

• JSON-RPC on Sui: JSON text over HTTP/1.1, one request per round trip, response shapes discovered at runtime.
• gRPC on Sui: Protocol Buffers (binary) over HTTP/2, multiplexed, response shapes fixed at compile time, with native server-side streaming.
• What’s being retired: JSON-RPC. Sui Foundation’s public endpoints no longer serve it, and Sui removes JSON-RPC from the full node code in mid-October 2026. Chainstack nodes still serve it today, alongside gRPC and GraphQL.
• The practical migration: Not everything moves to the same place. Port to gRPC what benefits from it, move filtered queries to GraphQL on Mainnet, and finish before JSON-RPC is removed.

How Sui talked to your backend, and why it was showing its age

The JSON-RPC pattern has been around since 2005. A client sends a POST request with a JSON envelope naming a method and parameters. The server executes and sends back JSON. Simple, universal, debuggable with curl. Every chain adopted it because every language could speak it on day one.

The costs stayed hidden for a while:

• Every call is its own HTTP/1.1 round trip. No multiplexing. Under load, you’re either opening many connections or queueing behind head-of-line blocking.
• Every payload is text. A checkpoint or large object response can be tens of kilobytes of JSON when the equivalent binary encoding is a few kilobytes.
• Every response is dynamically typed. Your client parses JSON, then either hopes the shape matches what it coded against or maintains defensive zod/pydantic/serde layers to catch drift.
• Streaming is an afterthought. Sui bolted WebSocket subscriptions onto JSON-RPC for events, but they lived on a separate connection with a separate lifecycle and separate failure modes.

For a wallet checking a balance twice a minute, none of this matters. For an indexer replaying millions of checkpoints, a Move-analytics pipeline, a game backend watching object mutations, or a market-making bot polling coin metadata, these costs compound.

What changed under the hood

gRPC is not one thing. It’s three decisions Sui made together:

HTTP/2 instead of HTTP/1.1. Many logical calls share one connection. No head-of-line blocking, no per-call TCP setup, first-class server push. For any workload with sustained request volume, this alone is the biggest speedup.

Protocol Buffers instead of JSON. Payloads are binary and typically several times smaller than the equivalent JSON, though the ratio depends on payload shape. Parsing is faster because there’s no text to tokenize; the wire format maps directly to structs. Bandwidth costs drop, and so does client-side CPU.

A .proto schema as the contract. Sui publishes .proto files defining every method, request, and response. Your client is generated from those files, which means “the API changed on me” moves from a runtime surprise to a compile error. This is the point serious backend teams care about most.

Side by side:

	JSON-RPC	gRPC
Transport	HTTP/1.1	HTTP/2, multiplexed
Encoding	JSON (text)	Protocol Buffers (binary)
Typing	Runtime, via convention	Compile-time, from .proto schemas
Streaming	Separate WebSocket subs	Native server-side streaming

What actually needs to move

The most common misconception about this migration is that everything has to move to gRPC. It doesn’t: filtered queries go to GraphQL. On Chainstack, Sui’s methods fall into three categories, and the first two are the real migration work.

• Migrate to gRPC — what benefits from it. Performance-sensitive reads, transaction submission, checkpoint streaming, anything on the hot path of a backend or indexer. This is where the typed clients, HTTP/2 multiplexing, and binary payloads pay off. Most JSON-RPC read and write methods have direct gRPC equivalents.
• Move to GraphQL — what has no gRPC equivalent. Filtered query methods such as suix_queryTransactionBlocks and suix_queryEvents map to GraphQL queries on Mainnet. Testnet has no GraphQL endpoint, so there they stay on JSON-RPC. WebSocket event subscriptions have no GraphQL equivalent either: stream checkpoints over gRPC and filter client-side, or keep suix_subscribeEvent on JSON-RPC until it is removed.
• Neither, on any full node — indexer and analytics methods. A small set of JSON-RPC methods return aggregated analytics that come from Sui’s indexer layer, not a full node. No provider serves them from a node, gRPC or otherwise. For these you index your own checkpoint stream or use a dedicated analytics provider.

For most applications, the third category doesn’t apply, the second needs no work, and the first is the actual migration. The Chainstack migration guide has the full method-by-method mapping if you need to plan a specific port.

How streaming subscriptions work over gRPC

Chainstack’s docs list SubscribeCheckpoints as the supported gRPC stream: it sends every new checkpoint to your client, and you filter events client-side. Sui’s newer proto also defines filtered SubscribeTransactions and SubscribeEvents methods; with server reflection enabled, run grpcurl describe sui.rpc.v2.SubscriptionService against your node to see what it serves. GraphQL has no subscriptions. JSON-RPC’s WebSocket subscriptions still work on Chainstack as a bridge until JSON-RPC is removed.

Where GraphQL fits

Sui’s GraphQL RPC is the access layer for the filtered, paginated reads gRPC doesn’t cover: transactions by address, events by type, objects by owner and type. Chainstack serves it on Sui Mainnet Global Nodes at /graphql, on the same endpoint and auth as JSON-RPC and gRPC, and each request costs 1 RU. Filtered transaction and event queries cover roughly the most recent 90 days, and Testnet nodes do not serve GraphQL. For a deeper comparison, read Sui GraphQL: what it is, and when to use it over gRPC and the Chainstack GraphQL endpoint docs.

The shape of the change, in code

The migration is smaller than it looks. Same task, both worlds — fetching the latest checkpoint:

# JSON-RPC
curl --request POST \
  --url YOUR_CHAINSTACK_ENDPOINT \
  --header 'Content-Type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "sui_getLatestCheckpointSequenceNumber",
    "params": []
  }'

# gRPC
grpcurl -H "x-token: YOUR_X_TOKEN" \
  sui-mainnet.core.chainstack.com:443 \
  sui.rpc.v2.LedgerService/GetCheckpoint

# GraphQL (Mainnet)
curl --request POST \
  --url YOUR_CHAINSTACK_ENDPOINT/graphql \
  --header 'Content-Type: application/json' \
  --data '{"query": "{ checkpoint { sequenceNumber } }"}'

Called with an empty body, GetCheckpoint returns the latest checkpoint — the gRPC equivalent of sui_getLatestCheckpointSequenceNumber, no parameter needed.

The URL becomes host:443, authentication moves from URL-embedded to a metadata header, and the method name is fully qualified with its service. From the official Mysten TypeScript SDK, migration is one import and one constructor change — SuiJsonRpcClient becomes SuiGrpcClient. The SDK’s default transport is gRPC-Web, which Chainstack serves, so browser and server code both work against Chainstack nodes out of the box; use a custom GrpcTransport only when you want native gRPC on Node.js with provider-specific auth headers. From typed languages (Go, Rust, Python), you generate stubs from Sui’s .proto files and call them over a secure channel.

For per-language connection code, see the Chainstack Sui tooling docs.

What the migration guides don’t tell you

Three things worth flagging out loud, because they’re easy to miss until you hit them.

• Response shapes are close but not identical. Field names differ, and some methods have been split, renamed, or moved between services. For example, ListBalancesRequest uses owner, not address — the field name a JSON-RPC developer would reach for by muscle memory. Pass the wrong name and grpcurl returns a parse error; in a generated client it’s a compile error. Check each request’s proto descriptor before porting. If you have monitoring dashboards or alerting rules that pattern-match on specific JSON keys, those rules need updating too.
• Browsers speak gRPC-Web, not native gRPC. Native gRPC needs HTTP/2 trailers browsers can’t produce; the fix everywhere is gRPC-Web, a distinct transport that tunnels the same protocol over standard HTTPS. Chainstack serves gRPC-Web on Sui endpoints, so the official @mysten/sui TypeScript SDK — whose default transport is gRPC-Web — works from the browser against a Chainstack node the same way it works against a Sui Foundation public fullnode. No custom transport, no backend proxy required for browser reads.
• “Enabled” is not the same as “deep.” Every serious Sui provider has flipped the gRPC switch. What varies is how far back the checkpoint history reaches on gRPC and how many object versions are retained. If your workload is a live wallet, this doesn’t matter. If it’s an indexer backfilling history or a compliance system reconstructing a token’s flow, it decides which provider you can actually use.

What this migration actually is

What Sui is doing isn’t a protocol swap — it’s a reset of what a Sui backend looks like architecturally. Typed contracts move error handling from runtime to build time. Server-side streaming makes real-time a first-class primitive instead of a polling workaround. The split between what belongs on gRPC and what stays on JSON-RPC forces teams to think about which reads belong at the edge and which belong behind a query layer.

Sui isn’t alone in this. Solana has run Yellowstone gRPC as its serious backend interface for years, ever since the Geyser plugin system landed in validator 1.9. Aptos ships its own Transaction Stream Service on gRPC. JSON-RPC won’t disappear from Web3 anytime soon, but the direction of travel is unambiguous: chains that care about backend performance are converging on gRPC for the hot path and streaming, GraphQL or REST for the browser. Teams that treat this Sui migration as a chance to build a proper protocol-abstraction layer inside their client code will move faster on every subsequent chain.

Building on Sui with Chainstack

Chainstack’s Sui infrastructure was designed for this transition. JSON-RPC, gRPC, and, on Mainnet Global Nodes, GraphQL are served on the same node, so you migrate call by call without provisioning parallel infrastructure or maintaining two credential sets. Server reflection is on, so you can browse the gRPC surface with grpcurl before writing a line of client code. Sui Global Nodes are Extended: the node holds a rolling window of checkpoints, verifiable via the lowestAvailableCheckpoint field in GetServiceInfo. On September 27, 2026, lowestAvailableCheckpoint sat at 237,661,232 against a height of 327,352,270 — about 89.7 million checkpoints, with a hard boundary: the checkpoint immediately below returns NotFound. For older data, use Sui’s archival service. Pricing is flat: every request, whether gRPC, GraphQL, or JSON-RPC, costs 1 RU, with no archive surcharge.

To deploy a Sui node:

1. Log in to the Chainstack console (or create an account).
2. Create a new project.
3. Click Deploy new node.
4. Set Protocol to Sui, Network to Mainnet or Testnet.
5. Choose Node type: Global Node or Dedicated Node.
6. Complete deployment.
7. Open Access and credentials and copy your endpoint and x-token.

For the full call-by-call migration path, the Chainstack Sui gRPC endpoint doc is the fastest starting point.

FAQ

Related reading

On Chainstack:

• Migrate Sui from JSON-RPC to gRPC and GraphQL
• Sui gRPC endpoint
• Sui GraphQL endpoint
• Sui GraphQL: what it is, and when to use it over gRPC
• Sui tooling documentation
• How to get a Sui RPC endpoint
• Best Sui RPC providers for production

External:

• Sui gRPC overview
• Sui JSON-RPC → gRPC migration guide
• Sui API reference
• Sui GraphQL RPC
• Sui proto definitions