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 marked JSON-RPC as deprecated. What that actually means depends on which provider you’re on, which of your calls really need to move, and where JSON-RPC continues to live. 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 actually being deprecated: Sui Foundation’s public JSON-RPC endpoints. JSON-RPC in the sui-node software is deprecated but not removed — node operators can keep serving it.
• The practical migration: Not everything needs to move. Port to gRPC what benefits from it, leave the rest on JSON-RPC.

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. On any provider that continues to serve JSON-RPC — Chainstack does — Sui’s methods fall into three categories, and only the first one is 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.
• Keep on JSON-RPC — what has no gRPC equivalent. A handful of filtered query methods and the WebSocket event subscriptions don’t map to gRPC. They keep working on any full node still serving JSON-RPC. You don’t move them; you don’t need to.
• 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.

One streaming caveat worth flagging

gRPC exposes exactly one subscription on Sui — checkpoint streaming. There is no per-event or per-transaction subscription over gRPC. If your app currently relies on real-time filtered event streams, either keep those subscriptions on the JSON-RPC WebSocket, or subscribe to checkpoints over gRPC and filter events client-side. This surprises teams who assume “gRPC has streaming” means gRPC has their streaming.

Where GraphQL fits

Sui Foundation also runs a GraphQL RPC service backed by the General-Purpose Indexer. It’s an alternative access layer, useful for complex filtered queries and aggregations that neither JSON-RPC nor gRPC does well — historical scans across many transactions, flexible client-defined response shapes, cross-cutting analytics reads. It isn’t part of the JSON-RPC → gRPC migration on Chainstack. If JSON-RPC keeps running on your node, you already have coverage for the methods that don’t fit gRPC; GraphQL becomes relevant when the shape of your query matters more than the protocol you use to send it.

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

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. Both gRPC and JSON-RPC 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. Checkpoint retention is deep enough for indexer backfills and archival reads that most competitors can’t handle from a live node — and directly verifiable via the lowestAvailableCheckpoint field in GetServiceInfo. At time of writing, lowestAvailableCheckpoint sits at 237,661,232 against a current height of ~302,477,000 — roughly 64.8 million checkpoints of live archive depth, with a hard boundary: the checkpoint immediately below returns NotFound. Pricing is flat 1 RU per full-node call, 2 RU per archive call, no compute-unit math.

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
• Sui gRPC endpoint
• 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