GraphQL

Overview

GraphQL RPC is a flexible, ergonomic interface for reading data from the Sui blockchain, submitting transactions, and simulating transactions. Instead of a fixed set of methods, GraphQL lets you request exactly the fields you need — across transactions, objects, events, balances, and checkpoints — in a single composable query, reducing overfetching and round trips.

Under the hood, our GraphQL service is backed by the Sui General-purpose Indexer, which ingests checkpoint data into a Postgres-compatible database and serves it through a strongly typed schema. It is the best fit for frontends, explorers, dashboards, and any data-driven application that benefits from filtered, nested, or point-in-time queries.

Note: JSON-RPC is deprecated and will be deactivated in October 2026. GraphQL RPC and gRPC are the two supported replacements. Migrating to either is strongly recommended for all production integrations.

---

When to use GraphQL

GraphQL is the best choice when your application:

• Needs to render structured results in a frontend, such as wallets, explorers, and dashboards.

• Benefits from flexible, composable queries that fetch only the fields you need and combine multiple entities (transactions, objects, events, balances) in one request.

• Requires filtered historical access, such as all transactions sent by an address, all transactions that called a given function, or all live objects of a given type.

• Wants consistent, point-in-time reads across one or more requests, as if the responses came from a snapshot at a specific checkpoint.

For high-performance, low-latency point lookups and real-time checkpoint streaming, use gRPC instead. Many production stacks use both: gRPC for hot-path lookups and streaming, GraphQL for flexible reads and frontends.

---

How it works

The GraphQL service answers each request from one of two backing data sources, each with its own retention window. Understanding which source serves which query helps you set the right expectations for data availability:

Data source	Example queries	Retention on our service
Consistent store	Live objects owned by an address, live objects by type, address balances	~1 hour (recent checkpoints)
Indexed database (Postgres)	transactions, events, checkpoints, and filtered historical queries	30 days

Important: GraphQL queries are served exclusively from the Consistent Store and the Postgres-indexed database — they never reach beyond these two sources. Our service retains 30 days of indexed checkpoint data, so filtered and historical GraphQL queries (transactions, events, checkpoints) resolve only within this 30-day window. There is no automatic fallback to Archival. For records older than 30 days, query our Archival Storage and Services endpoint directly — it serves the complete history of Sui mainnet from genesis via the gRPC LedgerService interface.

---

Endpoints

The GraphQL service is served over HTTPS at the /graphql path on your Sui endpoint. All queries are sent as POST requests with a JSON body containing your GraphQL query and optional variables.

Free Test Endpoint (Mainnet — rate-limited)

We provide a free shared GraphQL endpoint for testing and evaluation. It is strictly rate-limited and intended for development use only, not for production traffic.

https://mainnet.sui.rpcpool.com/graphql

No authentication token is required for this endpoint.

---

Shared Clients

Shared plan clients access GraphQL via the standard shared endpoint. Your unique endpoint hostname is available in the client panel.

Endpoint format:

https://XXX.sui.rpcpool.com/graphql

Replace XXX with your specific endpoint slug shown in the panel.

Authentication is required via the X-Token header:

X-Token: <your-token>

Both your endpoint and token can be found in your client panel.

---

Dedicated Clients

Dedicated plan clients have a private endpoint provisioned exclusively for their use.

Endpoint format:

https://XXX.sui.rpcpool.com/graphql

Replace XXX with your dedicated endpoint slug shown in the panel.

Authentication is required via the X-Token header:

X-Token: <your-token>

Both your endpoint and token can be found in your client panel.

---

Authentication

All non-free endpoints require authentication with your token — the same token used for your standard gRPC endpoint. You can find it in the client panel. There are two equivalent ways to supply it.

Option 1 — X-Token header:

curl -X POST https://XXX.sui.rpcpool.com/graphql \
  -H "X-Token: <your-token>" \
  -H "Content-Type: application/json" \
  -d '{ "query": "{ epoch { referenceGasPrice } }" }'

Option 2 — token in the URL:

curl -X POST https://XXX.sui.rpcpool.com/<your-token>/graphql \
  -H "Content-Type: application/json" \
  -d '{ "query": "{ epoch { referenceGasPrice } }" }'

The URL form is convenient for tools that can only set a URL and not custom headers. Both methods are equivalent — use whichever fits your client.

The free test endpoint accepts the same requests with no token at all:

curl -X POST https://mainnet.sui.rpcpool.com/graphql \
  -H "Content-Type: application/json" \
  -d '{ "query": "{ epoch { referenceGasPrice } }" }'

---

Quickstart

A GraphQL request is a JSON object with a query string and, optionally, a variables object. Below are the two most common request shapes.

A simple query

This query reads only current chain state — the chain identifier and the reference gas price for the current epoch — so it returns immediately without touching historical or archival data.

curl -X POST https://XXX.sui.rpcpool.com/graphql \
  -H "X-Token: <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ chainIdentifier epoch { referenceGasPrice } }"
  }'

Response:

{
  "data": {
    "chainIdentifier": "4btiuiMPvEENsttpZC7CZ53DruC3MAgfznDbASZ7DR6S",
    "epoch": {
      "referenceGasPrice": "100"
    }
  }
}

---

Example Queries

The following examples cover common tasks. Each is a GraphQL document you send as the query field of a request; where a query declares variables, supply them in the request's variables object.

Reference gas price for the latest epoch

query {
  epoch {
    referenceGasPrice
  }
}

A transaction by its digest

Fetch a transaction and its effects — gas sponsor, gas price and budget, execution status, and the checkpoint it landed in.

query ($digest: String!) {
  transaction(digest: $digest) {
    gasInput {
      gasSponsor { address }
      gasPrice
      gasBudget
    }
    effects {
      status
      timestamp
      checkpoint { sequenceNumber }
      epoch { epochId referenceGasPrice }
    }
  }
}

Variables:

{ "digest": "<transaction-digest>" }

Coins and balances owned by an address

query ($address: SuiAddress!) {
  address(address: $address) {
    balance {
      totalBalance
      coinType { repr }
    }
  }
}

All transactions that touched an object

Trace every transaction that modified, transferred, or deleted a given object — useful for following a Coin, StakedSui, or NFT.

query ($objectID: SuiAddress!) {
  transactions(filter: { affectedObject: $objectID }) {
    pageInfo { hasNextPage endCursor }
    nodes {
      digest
      sender { address }
      effects {
        objectChanges {
          nodes { address }
        }
      }
    }
  }
}

Filter transactions by function

Find the last 10 transactions that called a specific Move function.

query {
  transactions(
    last: 10
    filter: { function: "0x2::transfer::public_transfer" }
  ) {
    nodes { digest }
  }
}

Execute a transaction

GraphQL is not read-only. executeTransaction submits a signed transaction, and you can select fields from effects in the same request to read the result immediately, without waiting for a separate indexed query.

mutation ($tx: String!, $sigs: [String!]!) {
  executeTransaction(transactionDataBcs: $tx, signatures: $sigs) {
    errors
    effects {
      status
      gasEffects {
        gasSummary { computationCost }
      }
    }
  }
}

transactionDataBcs is the serialized unsigned transaction data (for example, from sui client call --serialize-unsigned-transaction), and signatures come from signing that data (for example, with sui keytool sign).

Simulate a transaction

Use simulateTransaction to preview effects, estimate gas, or test logic without committing onchain.

query ($tx: JSON!) {
  simulateTransaction(transaction: $tx, checksEnabled: true, doGasSelection: true) {
    effects {
      status
      gasEffects {
        gasSummary { computationCost storageCost }
      }
    }
    outputs {
      returnValues { value { json } }
    }
  }
}

---

Key Concepts

Pagination and connections

Fields that return multiple results are connections following the GraphQL Cursor Connections Specification. They accept first/after (forward) or last/before (backward) arguments and return pageInfo (with hasNextPage and endCursor) alongside nodes. Read the first page, then pass the returned endCursor as after to fetch the next page. Cursors are opaque — only use a cursor value returned by a previous response.

query ($after: String) {
  checkpoints(first: 5, after: $after) {
    pageInfo { hasNextPage endCursor }
    nodes { digest timestamp }
  }
}

Scope and consistency

Every request is evaluated as of a single checkpoint. By default this is the latest checkpoint the service has fully indexed. You can pin queries to an earlier checkpoint for historical reads using checkpoint(sequenceNumber: ...) { query { ... } }, and cursors for live-object queries encode the checkpoint at which pagination began, so later pages remain consistent even as new checkpoints arrive.

Limits

Requests are validated against complexity and payload rules (query depth, input/output node counts, page sizes, and request timeouts) in addition to rate limits. You can query the active limits at runtime:

{
  serviceConfig {
    maxQueryDepth
    maxQueryNodes
    maxOutputNodes
    maxPageSize(type: "Query", field: "objects")
    queryTimeoutMs
  }
}

Checking the available range

Because retention varies by data source, check the available checkpoint range before starting a long pagination run or a historical query:

{
  serviceConfig {
    availableRange(type: "Query", field: "transactions", filters: ["affectedAddress"]) {
      first { sequenceNumber }
      last { sequenceNumber }
    }
  }
}

If a query requests data outside the available range, it returns an "outside available range" error — use fresh cursors and keep your checkpoint bounds within the 30-day window.

---

Data Retention and Historical Data

Our GraphQL service retains 30 days of indexed checkpoint data. This covers the overwhelming majority of frontend, dashboard, and analytics workloads without the cost and latency of full historical indexing.

For data older than 30 days, use the Archival Storage and Services endpoint. Archival serves the complete history of Sui mainnet from genesis and exposes the gRPC LedgerService interface for point lookups of transactions, checkpoints, and historical object states.

Note: GraphQL does not automatically fall back to Archival for pruned data. If your application needs records older than 30 days, query the Archival endpoint directly. A common pattern is to serve recent data from GraphQL and route deep-history point lookups to Archival.

---

Exploring the schema

The Sui GraphQL schema is introspectable, so any GraphQL client library can discover the full set of available types and fields programmatically via a standard introspection query. For the complete, human-readable schema — every query, mutation, type, and field — see the official Sui GraphQL reference.

---

Endpoint Summary

Plan	GraphQL Endpoint	Auth
Free test	https://mainnet.sui.rpcpool.com/graphql	None (rate-limited)
Shared	https://XXX.sui.rpcpool.com/graphql	X-Token header or token in URL
Dedicated	https://XXX.sui.rpcpool.com/graphql	X-Token header or token in URL

XXX is your unique endpoint slug, visible in the client panel. The token is the same one used for your gRPC and Archival endpoints.

---

Resources

• gRPC — high-performance point lookups and streaming

• Archival Storage and Services — full historical data beyond 30 days

• Official: GraphQL for Sui RPC

• Official: Querying Data with GraphQL RPC

• Sui GraphQL schema reference