> For the complete documentation index, see [llms.txt](https://docs.triton.one/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.triton.one/chains/sui/graphql.md). # 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](https://docs.triton.one/chains/sui/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](https://docs.triton.one/chains/sui/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](https://docs.triton.one/chains/sui/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](https://customers.triton.one/). **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: ``` Both your endpoint and token can be found in your [client panel](https://customers.triton.one/). *** **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: ``` Both your endpoint and token can be found in your [client panel](https://customers.triton.one/). *** #### 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](https://customers.triton.one/). There are two equivalent ways to supply it. **Option 1 — `X-Token` header:** ```bash curl -X POST https://XXX.sui.rpcpool.com/graphql \ -H "X-Token: " \ -H "Content-Type: application/json" \ -d '{ "query": "{ epoch { referenceGasPrice } }" }' ``` **Option 2 — token in the URL:** ```bash curl -X POST https://XXX.sui.rpcpool.com//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: ```bash 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. ```bash curl -X POST https://XXX.sui.rpcpool.com/graphql \ -H "X-Token: " \ -H "Content-Type: application/json" \ -d '{ "query": "{ chainIdentifier epoch { referenceGasPrice } }" }' ``` **Response:** ```json { "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** ```graphql 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. ```graphql query ($digest: String!) { transaction(digest: $digest) { gasInput { gasSponsor { address } gasPrice gasBudget } effects { status timestamp checkpoint { sequenceNumber } epoch { epochId referenceGasPrice } } } } ``` **Variables:** ```json { "digest": "" } ``` **Coins and balances owned by an address** ```graphql 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. ```graphql 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. ```graphql 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. ```graphql 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. ```graphql 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](https://relay.dev/graphql/connections.htm). 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. ```graphql 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: ```graphql { 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: ```graphql { 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](https://docs.triton.one/chains/sui/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](https://docs.sui.io/references/sui-graphql). *** #### 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](https://customers.triton.one/). The token is the same one used for your gRPC and Archival endpoints. *** #### Resources * [gRPC](https://docs.triton.one/chains/sui/grpc) — high-performance point lookups and streaming * [Archival Storage and Services](https://docs.triton.one/chains/sui/archival-storage-and-services) — full historical data beyond 30 days * [Official: GraphQL for Sui RPC](https://docs.sui.io/develop/accessing-data/graphql/graphql-rpc) * [Official: Querying Data with GraphQL RPC](https://docs.sui.io/develop/accessing-data/graphql/query-with-graphql) * [Sui GraphQL schema reference](https://docs.sui.io/references/sui-graphql) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.triton.one/chains/sui/graphql.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.