Sui JSON-RPC vs GraphQL: Which One Should Builders Use?

JSON-RPC is canonical for transaction submission and authoritative object state reads on Sui until April 2026 sunset, making it the only option for builders who need strong consistency and finality guarantees for critical flows. JSON-RPC is officially deprecated; gRPC will replace it as the canonical Full Node API, so teams should architect for migration now to avoid last-minute rewrites as the sunset approaches (source).

GraphQL RPC with General-purpose Indexer is in public beta, designed for high-throughput, paginated queries and structured data access, and is best suited for read-heavy UIs, dashboards, and analytics workloads where eventual consistency is acceptable (source). GraphQL supports cursor-based pagination, joins, filtering, and checkpoint-consistent reads for large datasets, which are not feasible or performant with JSON-RPC.

gRPC beta supports typed Protobuf and real-time streaming via SubscriptionService, with expanding Core API coverage. gRPC SubscriptionService enables gapless, ordered checkpoint streaming for event-driven and real-time apps, which is a capability JSON-RPC and GraphQL do not offer (source). gRPC is positioned as the future-proof path for strongly-typed, low-latency, and streaming use cases as Sui’s API surface evolves.

Operational differences: JSON-RPC offers lower latency and strong consistency; GraphQL/indexer provides high-throughput, eventual consistency; gRPC targets real-time, strongly-typed streaming. Performance: JSON-RPC best for low-latency, canonical reads/writes; GraphQL/indexer for high-throughput analytics/UI; gRPC for future real-time patterns (source).

Security and permissioning: JSON-RPC/gRPC require node trust for canonical state, GraphQL/indexer is eventually consistent and not suitable for critical actions. Builders should avoid using GraphQL for anything requiring authoritative state or transaction submission, as indexer lag and eventual consistency gaps can lead to stale reads.

Migration strategy: run GraphQL and/or gRPC in parallel with JSON-RPC; keep critical flows on JSON-RPC until full migration. Reliability: monitor rate limits, noisy neighbor effects, and indexer lag across all endpoints, especially during migration, since operational characteristics differ and outages or lag can impact user experience (source).

Migration pain points: schema and field mapping mismatches, indexer lag, eventual consistency gaps, and breaking changes are all common as Sui’s API stack evolves. Builders must plan for schema evolution and breaking changes as GraphQL and gRPC mature, since Sui’s roadmap includes non-backward-compatible updates through at least 2025 (source).

GraphQL RPC + Indexer GA is targeted for December 2025, but until then, expect breaking changes and evolving schema. Migration tooling: Sui provides API docs and reference implementations, but field mapping and consistency reconciliation remain manual pain points, especially for teams with complex data models.

Operational best practice: avoid public endpoints for production; use self-hosted nodes or trusted providers for all transports. Security and reliability are only as strong as the underlying node infrastructure, and public endpoints are more susceptible to rate limiting and noisy neighbor effects.

Builders should treat JSON-RPC as canonical for all critical writes and reads until the 2026 sunset, but start building abstractions for GraphQL and gRPC now. The transition will not be seamless, but parallelizing API adoption and monitoring operational gaps is the only way to avoid last-minute breakage as Sui’s data stack matures.

gRPC beta supports typed Protobuf and real-time streaming via SubscriptionService, with expanding Core API coverage, making it the only Sui transport with native support for gapless, ordered checkpoint streaming. This is essential for event-driven and real-time apps that require strong ordering guarantees and low-latency updates, which JSON-RPC and GraphQL cannot provide.

GraphQL RPC + Indexer GA is targeted for December 2025, but until then, the schema and query surface are subject to breaking changes, which can complicate migration planning. Builders must plan for schema evolution and breaking changes as GraphQL and gRPC mature, since Sui’s roadmap includes non-backward-compatible updates through at least 2025.

Security and permissioning: JSON-RPC/gRPC require node trust for canonical state, while GraphQL/indexer is eventually consistent and not suitable for critical actions or transaction submission. Builders should avoid using GraphQL for anything requiring authoritative state, as indexer lag and eventual consistency gaps can lead to stale reads and unexpected user experience issues.

Migration strategy: run GraphQL and/or gRPC in parallel with JSON-RPC; keep critical flows on JSON-RPC until full migration. Migration pain points include schema and field mapping mismatches, indexer lag, eventual consistency gaps, and breaking changes, which are all common as Sui’s API stack evolves.