Skip to main content

Sui GraphQL Overview

Updated on
Oct 26, 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 provides an alternative to the removed Sui JSON-RPC service. 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.

Availability: Sui GraphQL is available in beta on Mainnet. JSON-RPC has been removed from both Mainnet and Testnet. Use gRPC on either network.

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 the gRPC API.

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/YOUR_TOKEN/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/YOUR_TOKEN/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query ($address: SuiAddress!) { address(address: $address) { balance(coinType: \"0x2::sui::SUI\") { totalBalance coinMetadata { name symbol decimals } } } }",
    "variables": {
      "address": "0x5"
    }
  }'

Example Response:

{
  "data": {
    "address": {
      "balance": {
        "totalBalance": "31018584912",
        "coinMetadata": {
          "name": "Sui",
          "symbol": "SUI",
          "decimals": 9
        }
      }
    }
  }
}

Service Limits & Data Retention​

Service Limits:

  • Request Size: 175KB max for transaction payloads, 5KB for other query components
  • Timeout: 74 seconds for execution queries, 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
  • Rich Queries: Maximum of 5 queries per request that require dedicated database access

Data Retention:

  • Consistent Store: All data is available
  • Database: 90 days of checkpoint data
  • Archival: 90 days of data

Getting Started​

Derived objects, dynamic fields, and balances​

The Quicknode Mainnet GraphQL schema supports derivedObject and multiGetDerivedObjects on IAddressable (including addresses and objects). These look up derived objects by name and return null for a key without a matching object. Use Query.multiGetDynamicFields(keys: ...) to fetch dynamic fields from multiple parent objects in one request. Each key supplies a parent address and a name, with optional version or checkpoint bounds. Balance.coinMetadata returns coin details when metadata is available and otherwise resolves to null. These fields were added in Sui Mainnet v1.81.1.

To fetch dynamic fields across parent objects, provide one key per parent. The response has one result per key, in the same order; an unmatched key returns null.

curl -X POST https://your-endpoint.sui-mainnet.quiknode.pro/YOUR_TOKEN/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query ($keys: [NameKey!]!) { multiGetDynamicFields(keys: $keys) { name { type { repr } bcs } } }",
    "variables": {
      "keys": [
        {
          "parent": "0xb57fba584a700a5bcb40991e1b2e6bf68b0f3896d767a0da92e69de73de226ac",
          "name": { "type": "0x2::kiosk::Lock", "bcs": "NLArx1UJguOUYmXgNG8Pv8KbKXLjWtCi6i0Yeq1Vhfw=" }
        },
        {
          "parent": "0x27c4fdb3b846aa3ae4a65ef5127a309aa3c1f466671471a806d8912a18b253e8",
          "name": { "type": "vector<u8>", "bcs": "BGV3bWE=" }
        }
      ]
    }
  }'

Each NameKey contains parent and name. The name can provide a Move type and its BCS-encoded bcs value.

Example queries​

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:

Last updated on