Sui JSON-RPC Shutdown: What Developers Must Change After the July 31 Migration Deadline

There’s no more runway. If your app still calls Sui’s legacy JSON-RPC, it will start failing. The Foundation set a hard cut: migrate to gRPC or GraphQL by July 31, 2026, or expect broken reads and writes.

Testnet already went dark earlier in July, which caught a lot of teams flat-footed. Mainnet is next. This guide spells out what actually changes, how to pick the right API per job, and the quick fixes that keep production stable.

Short version: swap endpoints, rework a few queries, and rethink how you fetch history. Let’s get it done.

Aspect What to Know Deadline Legacy JSON-RPC deactivates July 31, 2026 on public nodes per the Sui Foundation. Migrate to gRPC or GraphQL before then (Sui Foundation (blog)). Staged shutdown Testnet JSON-RPC dropped July 8, 2026 at noon EST; mainnet follows by July 31, 2026 (Inodra (blog)). Replacement APIs gRPC for core protocol calls and streaming, GraphQL for flexible read queries and some listings/analytics. Some JSON-RPC methods have no 1:1 gRPC equivalent (Mysten Labs / @mysten/sdk docs). Archive access Providers note deep history beyond roughly 14 epochs routes via gRPC to archive nodes on Mainnet (QuickNode (docs)). SDK changes TypeScript SDK exposes new Core API mappings. Some former JSON-RPC listings like getEpochs or getCheckpoints now require GraphQL or client-side composition (Mysten Labs / @mysten/sdk docs). Risk Hard deactivation means production outages if you do nothing. Monitor, test, and cut over behind flags.

Sui is retiring the public JSON-RPC surface on Foundation nodes and anchoring the data stack around a Core gRPC API plus a GraphQL layer. The rationale is pretty practical: gRPC gives tight, typed, binary calls and streaming for performance, while GraphQL makes the read side more expressive and future proof. The Foundation flagged the change and its new archival store as part of the stack evolution (Sui Foundation (blog)).

The shutdown happened in stages. Testnet JSON-RPC was taken down on July 8, 2026 at noon EST, which served as a canary. Mainnet public JSON-RPC is deactivated by July 31, 2026, so anything still pointing at those endpoints will error out (Inodra (blog)).

There’s also a shift in how you reach historical data. Some providers document that history past roughly 14 epochs on Mainnet now routes through gRPC to archive nodes, not the generic public endpoints. If you query old checkpoints or long-tail events, plan for that path (QuickNode (docs)).

Finally, the Mysten SDK migration notes are worth a close read. Many JSON-RPC methods have clear gRPC replacements, but some convenience listings, like paginated getEpochs or getCheckpoints, and metrics like getValidatorsApy, do not map 1:1 and may need GraphQL or client-side assembly (Mysten Labs / @mysten/sdk docs).

Glossary for this switchover

• gRPC: A binary, strongly typed RPC protocol used for Sui’s Core API. Fast, good for streaming and write paths.
• GraphQL: A query language and runtime that lets clients ask for specific fields and relationships, great for complex reads.
• Archive node: A node that stores deeper historical data beyond recent epochs, typically accessed via gRPC for heavy history pulls.
• Epoch: A fixed-duration period in Sui’s consensus schedule. Data retention and some limits are defined around epochs.
• Checkpoint: A sequence number marking consensus output. Useful anchor for historical scans and pagination.
• Cursor-based pagination: Pagination using opaque cursors or IDs rather than page numbers, common in GraphQL and some SDK lists.

Step-by-step playbook

1. Audit all JSON-RPC touches. Search your codebase and configs for legacy endpoints and method names. Include scripts, indexers, dashboards, and cron jobs.
2. Pin and upgrade the Sui SDK. Install the latest Mysten TypeScript SDK or your language binding. Use the documented Core API mappings to replace calls that have direct gRPC equivalents.
3. Decide per-call: gRPC or GraphQL. Treat writes, submissions, and streams as gRPC land. Treat complex reads and listings as GraphQL territory, especially where no 1:1 gRPC exists.
4. Rework pagination and listings. For getEpochs, getCheckpoints, and similar listings, switch to GraphQL or assemble from primitives. Expect cursor-based pagination instead of page numbers.
5. Handle history via archive paths. If you pull data older than recent epochs, route those queries to providers’ archive gRPC or your own archive node. Cache aggressively.
6. Wire observability. Add metrics for error codes, latency percentiles, and rate limits on new endpoints. Alert on any JSON-RPC fallback that still fires.
7. Stage a dark launch. Ship the new clients behind a flag, replay queries in staging, and cut over gradually. Keep a rollback plan for critical flows.
8. Update docs and access keys. Rotate credentials, update runbooks, and train your on-call team on the new failure modes.

Choosing between gRPC and GraphQL

There is no single winner. Treat this like picking the right tool for each job. Here is a clear way to split responsibilities that matches how Sui is evolving.

Use case Recommended API Why Notes Transaction submission and confirmations gRPC Typed, low-latency calls with streaming options for state changes. Keep retries idempotent and watch backoff. Event subscriptions and live feeds gRPC Server streaming is designed for this. Buffer spikes and checkpoint your cursors. Complex reads and cross-entity views GraphQL Shape the response to exactly what you need. Prefer field selection over over-fetching. Epoch or checkpoint listings GraphQL No 1:1 gRPC replacement for some JSON-RPC listings per Mysten docs. Use cursors, not pages. Cache results. Validator metrics like APY GraphQL or compute client-side Some endpoints like getValidatorsApy lack direct gRPC methods. Document assumptions and refresh cadence. Deep historical scans gRPC to archive nodes Providers route old history via archive backends. Batch and parallelize carefully.

Pro tip: do a one-week side-by-side run, logging both the old JSON-RPC calls and the new gRPC or GraphQL equivalents. You will spot pagination off-by-ones and filter gaps before go-live.

What changes in production after July 31

Expect a short-term spike in 4xx and 5xx errors where any leftover JSON-RPC paths remain. Kill those fast. On the happy path, you should see lower payload sizes and better p95 latency on hot gRPC calls, especially around submissions and event streams.

History is the other big shift. Provider docs updated in July 2026 say archive reads for data older than roughly 14 epochs will route via gRPC to archive nodes on Mainnet. That is good for correctness but it changes where you point your jobs and how you batch them (QuickNode (docs)).

On the read side, GraphQL will feel familiar if you have used it elsewhere. The trade-off is learning the schema and moving to cursor-based pagination. Once you get the hang of it, over-fetching disappears and responses are saner.

Provider or self-host: what actually shifts

If you rely on a node provider, watch their migration notes closely. Some will proxy a few JSON-RPC shapes for a while, but the official stance is that legacy JSON-RPC is gone on Foundation nodes and not the path forward (Sui Foundation (blog)).

If you self-host, plan for two tiers: a fast Core API node for current state and streaming, and an archive tier for deep queries. Keep them observable and budget for storage growth. For teams with small read footprints, GraphQL from a reputable provider plus a lean gRPC client may be enough.

Pitfalls and red flags

• Assuming method parity. Some JSON-RPC endpoints have no direct gRPC twin. Check Mysten’s mapping notes and plan GraphQL or client-side fallbacks.
• Pagination drift. Page-number assumptions will break. Move to cursors and test boundary conditions at page turns.
• Archive blind spots. Jobs that quietly scan old checkpoints may stall if you do not route them to archive gRPC or an archive node.
• Silent provider defaults. Rate limits, timeouts, and retries differ between JSON-RPC and gRPC. Tune client settings and observe p95, p99 latency.
• Mixed schemas. GraphQL schema updates can rename or deprecate fields. Pin versions where possible and lint your queries.
• Credentials and TLS. New endpoints often need new keys and TLS roots. Rotate and document everything for on-call.

Frequently Asked Questions

Is JSON-RPC really gone after July 31, 2026?

For public Foundation nodes, yes. The Foundation set a hard deactivation date and staged shutdowns already hit testnet, with mainnet completing by July 31, 2026. Plan for gRPC and GraphQL going forward.

Can a provider keep JSON-RPC alive for me?

Some providers may proxy or shim a few calls for a limited time, but that is not the supported path. Expect gaps and eventual removal. Migrate your code to the new APIs.

What do I use for long historical queries?

Route deep history through gRPC to archive nodes. Several providers documented that history beyond roughly 14 epochs on Mainnet is served that way. Batch requests and cache to manage costs.

Do I need a full rewrite?

Usually no. Many calls map one-to-one into the Core gRPC API via the latest SDKs. The heaviest lifts are listings and analytics that move to GraphQL and any custom pagination logic.

Which API should I pick for validator APY and network metrics?

There is no direct gRPC replacement for some convenience endpoints like getValidatorsApy per Mysten’s migration notes. Use GraphQL or compute it on the client.

How do I test the cutover safely?

Run the new clients behind a feature flag, replay production reads in staging, and watch error budgets. Flip traffic gradually and keep rollbacks ready for write paths.

What changed in the Sui data stack overall?

The stack leans on a Core gRPC API for performance and a GraphQL layer for flexible reads and historical access, including an archival store. This is the supported direction for builders.

Disclaimer: This article is provided for informational purposes only. It is not offered or intended to be used as legal, tax, investment, financial, or other advice.