Sui GraphQL: what it is, and when to use it over gRPC

Sui Foundation started decommissioning its public JSON-RPC endpoints in late July 2026, and Sui removes JSON-RPC from the full node code entirely in mid-October 2026, so every call needs a new home (see the Chainstack migration guide). gRPC covers most of them; on Chainstack’s Sui nodes, Sui GraphQL is where filtered, paginated reads live, such as transactions by address or events by type. This guide covers what Sui GraphQL is, when to use it over gRPC, and how to call it on Chainstack.

What Sui GraphQL actually is

Sui GraphQL serves as the official query interface. It reads from the General Purpose Indexer‘s Postgres-compatible database, Sui’s Archival Store and Service, and a full node, rather than serving everything from raw full-node key-value stores.

Instead of replacing JSON-RPC or gRPC entirely, it runs alongside them as a parallel access layer optimized for declarative HTTP reads. Sui documents the GraphQL RPC server and the General-purpose Indexer as generally available, although its GraphQL reference is still labeled beta, so schema details can change.

Access is centralized through a single HTTP POST endpoint. On Chainstack, that is your Sui Mainnet endpoint with /graphql appended, on the same auth token as JSON-RPC and gRPC. The endpoint does not serve a GraphiQL IDE, so explore the schema through Sui’s GraphQL reference, or send queries with cURL or the SuiGraphQLClient in @mysten/sui.

The indexer and Postgres layer behind it

Sui full nodes are engineered for executing and serving chain state through fast key-value lookups. They store flat object state efficiently, but they are not built to process complex relational queries across nested balances, address transaction histories, or Move events. Executing relational joins on a full node requires an off-chain relational database like Postgres to filter and index structured state.

Routing heavy, multi-entity GraphQL queries to a dedicated General Purpose Indexer prevents execution bottlenecks on full nodes. The indexer ingests raw execution state, transforms it, and populates the Postgres database, leaving full nodes free to focus on gRPC lookups, transaction submission, and checkpoint streaming.

GraphQL vs gRPC on Sui

The two protocols solve fundamentally different problems, and that divide shows up clearly in how each one handles data movement. GraphQL runs over plain HTTP and lets the client specify the exact fields to return, letting you shape response payloads directly in the request. In contrast, gRPC operates over Protocol Buffers and HTTP/2, optimized for continuous, low-latency streaming where raw throughput takes priority over query flexibility.

• GraphQL fits filtered, paginated reads — transactions by address, events by type, objects by owner and type — plus interactive UIs and wallet views that shape several entities into one request.
• gRPC fits performance-critical execution paths: point lookups, transaction submission, and checkpoint streaming for indexing pipelines, MEV bots, and continuous chain monitoring.

	GraphQL	gRPC
Transport	HTTP	Protocol Buffers over HTTP/2
Response shape	Client-defined, per query	Fixed, per method
Best fit	Filtered, paginated, interactive reads	Streaming, low-latency, high-volume reads
Streaming	None — no subscriptions	Checkpoint streaming via SubscribeCheckpoints
Typical user	dApp frontends, explorers, wallets	Indexers, MEV bots, monitoring systems
Data source	General Purpose Indexer, Archival Store, and full node	Full node directly

Neither replaces the other: most production setups run both on the same node, gRPC for the fast path and GraphQL for filtered reads.

Limitations and history windows

Building production dApps against Sui GraphQL means working within fixed limits rather than querying an unthrottled database. Sui still labels its GraphQL reference beta, so review Sui’s release notes and re-test your queries after SDK upgrades.

On Chainstack, GraphQL is available on Sui Mainnet only. Sui Testnet nodes do not serve /graphql. History also depends on the query type (see the windows below), and a query outside its window returns an empty result, not an error, so read the window before you read an empty result as “no data.”

Servers also enforce complexity caps. On Chainstack today a page holds up to 50 items, a query payload up to 5,000 bytes, nesting depth up to 20, up to 300 query nodes, and a query times out after 40 seconds. You can read these limits from your own node through the serviceConfig field, and a query over a limit fails with a GRAPHQL_VALIDATION_FAILED error that names the limit.

There is no streaming over GraphQL. The endpoint does not accept WebSocket connections, so GraphQL subscriptions are not available. To stream new checkpoints, use gRPC SubscriptionService/SubscribeCheckpoints on the same node.

What GraphQL is actually good for

Complex composable UI fetches

Instead of chaining multiple RPC requests to construct a single dashboard view, GraphQL retrieves nested records in a single round trip. Frontends can fetch an account, resolve its native token balance, and pull owned Move objects without overfetching data.

Point-in-time snapshot consistency

Queries execute scoped to a specific checkpoint state. This prevents race conditions where an account balance reflects block N while its owned objects reflect block N + 1, ensuring exact data alignment across related entities. On Chainstack, live balances and owned objects support atCheckpoint reads across a short window of recent checkpoints.

Interactive explorer and wallet views

Block explorers, wallet extensions, and portfolio trackers benefit from schema introspection and flexible pagination. Developers request only the fields needed for the current viewport, saving bandwidth and improving app responsiveness.

This advantage shows up clearly when fetching multi-entity state, where a single declarative payload replaces multiple client calls:

query GetAddressOverview($owner: SuiAddress!) {
  address(address: $owner) {
    balances {
      nodes {
        coinType {
          repr
        }
        totalBalance
      }
    }
    objects(first: 5) {
      nodes {
        address
        digest
        version
        contents {
          type {
            repr
          }
        }
      }
    }
  }
}

One request replaces two round trips. On Sui, though, these two reads also have gRPC equivalents (StateService/ListBalances and StateService/ListOwnedObjects), so the case for GraphQL is strongest for filtered reads, such as the latest event of a given type. Chainstack’s docs list filtered transaction and event queries as GraphQL-only on its nodes, even though Sui’s upstream gRPC API also defines ListEvents and ListTransactions:

query ($type: String!) {
  events(last: 1, filter: { type: $type }) {
    nodes {
      timestamp
      transaction { digest }
      contents { json }
    }
  }
}

This is the GraphQL replacement for JSON-RPC’s suix_queryEvents. Transactions filtered by address, kind, or function replace suix_queryTransactionBlocks the same way.

Where GraphQL sits in the Chainstack Sui stack

Chainstack already serves Sui JSON-RPC and gRPC from the same node, and since September 28, 2026, Sui Mainnet Global Nodes serve GraphQL at /graphql on the same endpoint and auth token. You can authenticate with the token in the URL, Basic auth, or the x-token header.

To find the URL, open your Sui Mainnet Global Node and copy the GraphQL endpoint row under Access and credentials. Then send a query with a plain HTTP POST:

curl --request POST \
  --url YOUR_CHAINSTACK_ENDPOINT/graphql \
  --header 'Content-Type: application/json' \
  --data '{"query": "{ chainIdentifier checkpoint { sequenceNumber timestamp } }"}'

Each GraphQL request is 1 RU, the same as a gRPC or JSON-RPC call on Sui. Sui has no archive billing split, so a query that reaches back to the start of its window costs the same as one at the tip. How far back a query reaches depends on its type:

Query type	Window
Point lookups and unfiltered lists — checkpoint, transaction, object, and checkpoints or transactions without a filter	Starts at the node’s retention floor (January 2026) and grows as the chain grows
Filtered transactions and all events	Rolling window of up to the most recent 90 days
Live balances and owned objects	Current state, plus a short window of recent checkpoints
Move packages	Every package since genesis

The windows move, so read serviceConfig.availableRange at runtime instead of hard-coding checkpoint numbers. For data older than these windows, query an archival service — see Sui’s Archival Store and Service. The full details, and the JSON-RPC to GraphQL method mapping, are in the Chainstack Sui GraphQL endpoint docs and the migration guide.

Conclusion

Sui did not replace JSON-RPC with one API, so port each call by what it does:

• Point lookups, transaction submission, checkpoint streaming: gRPC.
• Filtered, paginated reads (transactions by address, events by type, objects by owner and type): GraphQL on Mainnet. Testnet has no GraphQL, so those calls stay on JSON-RPC there.
• Anything you have not ported yet: JSON-RPC still works on Chainstack, but Sui removes it from the full node code in mid-October 2026, so plan to finish.

All three run on the same Chainstack Sui node, so you can migrate call by call without switching providers or re-syncing.

Frequently asked questions

Additional resources

• Sui GraphQL endpoint — Chainstack docs: authentication, filters, history windows, and limits
• Migrate Sui from JSON-RPC to gRPC and GraphQL — method-by-method mapping
• Chainstack updates: September 28, 2026
• GraphQL for Sui RPC — Sui’s own guide and schema reference
• Sui gRPC developer guide: what to migrate, and how it works
• Best Sui RPC providers for production in 2026
• How to get a Sui RPC endpoint for gaming (2026 guide)
• How to get a Sui RPC endpoint for DeFi (2026 guide)