Skip to main content

Sui GraphQL Overview

Updated on
Mar 24, 2026

Overview​

Sui GraphQL is a flexible query interface for accessing Sui network data. It provides a complete toolbox for fetching blockchain data and executing transactions through a GraphQL-based query language.

Unlike traditional RPC methods with fixed endpoints, GraphQL allows you to request exactly the data you need in a single query, making it more efficient for complex data requirements. GraphQL represents the modern approach to accessing Sui blockchain data, replacing the deprecated JSON-RPC standard. It enables flexible, composable queries that reduce overfetching and allow you to retrieve multiple data entities in a single request or in a consistent fashion across multiple requests.

Current Status: Sui GraphQL is in beta as of September 2025. The JSON-RPC standard is deprecated and will be fully deactivated by July 2026.

For more detailed information about Sui GraphQL architecture and implementation, see the official Sui GraphQL documentation.

Key Features​


  • Flexible Queries: Request only the fields you need, reducing bandwidth and improving performance. GraphQL allows precise field selection, eliminating the overfetching common with traditional REST or RPC APIs.
  • Nested Data Access: Retrieve related objects and their properties in a single query without multiple round trips. Query transactions with their effects, balance changes, and related objects all at once.
  • Pagination Support: Built-in cursor-based pagination for efficiently navigating large result sets. Paginate through checkpoints, transactions, and dynamic fields with consistent cursors.
  • Historical Queries: Query blockchain state at specific checkpoints for consistent, point-in-time data access. This enables snapshot-consistent queries across multiple requests.
  • Type Safety: GraphQL's strongly-typed schema provides clear documentation, auto-completion support, and validation of queries before execution.

Network Support & Endpoint​

Sui GraphQL is available on Sui Mainnet only. For Testnet, use gRPC or JSON-RPC APIs.

You can use your Sui Mainnet endpoint for GraphQL queries. If you don't have an endpoint, create one from the QuickNode Dashboard:

  1. Log in to the dashboard
  2. Go to the Endpoints section in the sidebar
  3. Click Create a new endpoint
  4. Choose Sui and Sui Mainnet

Your GraphQL endpoint will be in the format:

https://your-endpoint.sui-mainnet.quiknode.pro/graphql

All queries are sent as POST requests with a JSON body containing your GraphQL query and optional variables.

Example Request:

curl -X POST https://your-endpoint.sui-mainnet.quiknode.pro/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query ($address: SuiAddress!) { address(address: $address) { balance { totalBalance } } }",
    "variables": {
      "address": "0x5"
    }
  }'

Example Response:

{
  "data": {
    "address": {
      "balance": {
        "totalBalance": "5000000000"
      }
    }
  }
}

Service Limits & Data Retention​

Service Limits:

  • Request Size: 175KB max for transaction payloads, 5KB for other components
  • Timeout: 74 seconds for execution, 40 seconds for read queries
  • Query Complexity: 300 max input nodes/field names, 20-level nesting depth
  • Output: 1,000,000 max estimated output nodes
  • Pagination: 50 items per page (default), 200 for multi-get operations

Data Retention:

  • Consistent Store: ~1 hour of recent data
  • Database: 30-90 days of checkpoint data
  • Archival: Indefinite (if configured)

Getting Started​

Explore the example queries below to learn common patterns for working with Sui GraphQL. Each example includes code snippets in multiple languages (cURL, JavaScript, Python, and Ruby).

Example queries:

We ❤️ Feedback!​

If you have any feedback or questions about this documentation, let us know. We'd love to hear from you!

Last updated on
Share this doc