Sui - GraphQL

Query the Sui blockchain with Tatum's GraphQL endpoint, accessing objects, transactions, checkpoints, and on-chain state with precise field selection and nested resolution in a single request.

Overview

The Sui GraphQL API provides a comprehensive interface for querying blockchain data using GraphQL.

Key benefits include:

Efficient Data Retrieval: Query only the specific fields you need, reducing bandwidth and improving response times
Flexible Querying: Access multiple data types and operations through a single, unified endpoint
Self-Documenting Schema: Built-in introspection capabilities allow you to explore available queries and data structures in real-time
Simplified Integration: Strongly-typed schema ensures type safety and reduces integration errors

Known Limitations

WebSocket subscriptions are not currently supported on GraphQL endpoints

Sui GraphQL endpoint

Interface	Endpoint
Mainnet	`https://sui-mainnet.gateway.tatum.io/graphql`
Testnet	`https://sui-testnet.gateway.tatum.io/graphql`
Devnet	`https://sui-devnet.gateway.tatum.io/graphql`

For gRPC and the full network list, see Sui gRPC.

Getting Started

The GraphQL endpoint automatically loads the complete schema, allowing you to query all available data types and operations through a single URL.

Schema Introspection

The GraphQL schema is self-documenting. You can introspect the schema to discover:

Available queries
Object types and fields
Input types and arguments
Mutations and subscriptions
Enums and scalar types

Common Queries

Query Objects

All GraphQL queries are performed against the root Query type, which provides access to:

Account information
Transaction data
Object states
Event logs
Validator information
Network statistics

Example Query Structure

query {
  # Your query fields here
}

Authentication

Include your API key in the request headers when making queries to the endpoint.

Response Format

All responses are returned in JSON format with the following structure:

{
  "data": {
    // Query results
  },
  "errors": [
    // Any errors encountered
  ]
}

Queries

chainIdentifier

Returns the network's genesis checkpoint digest (Base58-encoded), uniquely identifying this network.

query ChainIdentifier {
    chainIdentifier
}

{
    "data": {
        "chainIdentifier": "4btiuiMPvEENsttpZC7CZ53DruC3MAgfznDbASZ7DR6S"
    }
}

address

Dry-run a transaction to preview its effects without executing on-chain. Accepts a JSON transaction matching the Sui gRPC API schema, or BCS-encoded data as {"bcs": {"value": "<base64>"}}. No signatures required.

Argument	Type	Description
`address`	`SuiAddress`	The hex address to look up
`name`	`String`	Sui Name Service domain (alternative to address)
`rootVersion`	`UInt53`	Bound dynamic field access at or before this version
`atCheckpoint`	`UInt53`	Fetch at the latest version as of this checkpoint

Note: Specify either address or name, not both. rootVersion disables pagination of owned objects and dynamic fields.

query Address {
    address(address: "0x2") {
        address
        balance(coinType: "0x2::sui::SUI") {
            totalBalance
        }
    }
}

{
    "data": {
        "address": {
            "address": "0x00000...",
            "balance": {
                "totalBalance": "2400568446767"
            }
        }
    }
}

object

Fetch a single on-chain object by its address. Optionally pin to an exact version, a root-bounded version, or a specific checkpoint.

Argument	Type	Description
`address`	`SuiAddress!`	Required
`version`	`UInt53`	Exact object version
`rootVersion`	`UInt53`	Latest version at or before this root version
`atCheckpoint`	`UInt53`	Latest version as of this checkpoint

Note: At most one of version, rootVersion, or atCheckpoint may be specified. Setting version or rootVersion disables nested pagination of owned objects and dynamic fields.

query Object {
    object(address: "0x5") {
        address
        version
        digest
        owner { __typename }
    }
}

{
    "data": {
        "object": {
            "address": "0x00000...",
            "version": 1054471530,
            "digest": "4z9eD...",
            "owner": {
                "__typename": "Shared"
            }
        }
    }
}

objects

Paginate the live object set, filtered by owner and/or type.

Argument	Type	Description
`first`	`Int`	Page size (forward)
`after`	`String`	Cursor for forward pagination
`last`	`Int`	Page size (backward)
`before`	`String`	Cursor for backward pagination
`filter`	`ObjectFilter!`	Required

query Objects {
    objects(first: 2, filter: { owner: "0x2", type: "0x2::coin::Coin" }) {
        nodes {
            address
            version
        }
        pageInfo { 
            hasNextPage 
            endCursor 
        }
    }
}

{
    "data": {
        "objects": {
            "nodes": [
                {
                    "address": "0x797b7...",
                    "version": 849872256
                },
                {
                    "address": "0x726b7...",
                    "version": 387286118
                }
            ],
            "pageInfo": {
                "hasNextPage": true,
                "endCursor": "yPICF..."
            }
        }
    }
}

objectVersions

Paginate all historical versions of an object at a given address.

Argument	Type	Description
`address`	`SuiAddress!`	Required
`first` / `after` / `last` / `before`	`Int` / `String`	Pagination
`filter`	`VersionFilter`	afterVersion / beforeVersion bounds

transaction

Fetch a single transaction by its digest.

Argument	Type	Description
`digest`	`String!`	Required — Transaction digest

query Transaction {
   transaction(digest: "GHAuBeydSov1zyT6sUKS2cFxWtNWkeamtKANsHwZJHve") {
     digest
     sender { address }
     gasInput { gasBudget gasPrice }
     effects {
       status
       timestamp
       gasEffects { gasSummary { computationCost storageCost } }
       balanceChanges(first: 5) {
         nodes { owner { address } amount coinType { repr } }
       }
     }
   }
 }

{
    "data": {
        "transaction": {
            "digest": "GHAuB...",
            "sender": null,
            "gasInput": {
                "gasBudget": "0",
                "gasPrice": "1"
            },
            "effects": {
                "status": "SUCCESS",
                "timestamp": "2026-01-23T22:30:07.386Z",
                "gasEffects": {
                    "gasSummary": {
                        "computationCost": 0,
                        "storageCost": 0
                    }
                },
                "balanceChanges": {
                    "nodes": []
                }
            }
        }
    }
}

transactions

Paginate transactions on the network with optional filters.

Argument	Type	Description
`first` / `after` / `last` / `before`	`Int` / `String`	Pagination
`filter`	`TransactionFilter`	Checkpoint range, function, kind, affected address/object, sender

query Transactions {
  transactions(first: 5, filter: { affectedAddress: "0x2" }) {
    nodes { digest sender { address } }
    pageInfo { hasNextPage endCursor }
  }
}

{
    "data": {
        "transactions": {
            "nodes": [
                {
                    "digest": "FXNxw...",
                    "sender": {
                        "address": "0x3c631..."
                    }
                },
                {
                    "digest": "Ai3jK...",
                    "sender": {
                        "address": "0x3c631..."
                    }
                }
            ],
            "pageInfo": {
                "hasNextPage": true,
                "endCursor": "KAE6C..."
            }
        }
    }
}

transactionEffects

Fetch the effects of a transaction by its digest — status, balance changes, object changes, gas, events.

Argument	Type	Description
`digest`	`String!`	Required

query TransactionEffects {
  transactionEffects(digest: "EtcivnTBj54akfucVxpDxZXhE8vgi8T7BG7U1wFsYoQi") {
    digest
    status
    timestamp
    epoch { epochId }
    checkpoint { sequenceNumber }
    gasEffects {
      gasSummary {
        computationCost
        storageCost
        storageRebate
        nonRefundableStorageFee
      }
    }
  }
}

{
    "data": {
        "transactionEffects": {
            "digest": "Etciv...",
            "status": "SUCCESS",
            "timestamp": "2026-07-22T06:49:36.288Z",
            "epoch": {
                "epochId": 1196
            },
            "checkpoint": {
                "sequenceNumber": 301524475
            },
            "gasEffects": {
                "gasSummary": {
                    "computationCost": 118000,
                    "storageCost": 55054400,
                    "storageRebate": 52133796,
                    "nonRefundableStorageFee": 526604
                }
            }
        }
    }
}

checkpoint

Fetch a checkpoint by sequence number or digest. Returns the latest checkpoint if neither is provided.

Argument	Type	Description
`sequenceNumber`	`UInt53`	Checkpoint sequence number
`digest`	`String`	Checkpoint digest (mutually exclusive with sequenceNumber)

query Checkpoint {
  checkpoint {
    sequenceNumber
    digest
    timestamp
    networkTotalTransactions
    epoch { epochId }
  }
}

{
    "data": {
        "checkpoint": {
            "sequenceNumber": 335740553,
            "digest": "8daQG...",
            "timestamp": "2026-10-19T12:04:24.057Z",
            "networkTotalTransactions": 6278383494,
            "epoch": {
                "epochId": 1285
            }
        }
    }
}

checkpoints

Paginate checkpoints, optionally bounded to a specific epoch.

Argument	Type	Description
`first` / `after` / `last` / `before`	`Int` / `String`	Pagination
`filter`	`CheckpointFilter`	Epoch / checkpoint range bounds

query Checkpoints {
  checkpoints(first: 2) {
    nodes {
      sequenceNumber digest timestamp networkTotalTransactions epoch {
        epochId
      }
    }
    pageInfo {
      hasNextPage endCursor
    }
  }
}

{
    "data": {
        "checkpoints": {
            "nodes": [
                {
                    "sequenceNumber": 237661232,
                    "digest": "6WUG6...",
                    "timestamp": "2026-01-23T22:30:07.386Z",
                    "networkTotalTransactions": 4717398407,
                    "epoch": {
                        "epochId": 1017
                    }
                },
                {
                    "sequenceNumber": 237661233,
                    "digest": "3a34a...",
                    "timestamp": "2026-01-23T22:30:07.683Z",
                    "networkTotalTransactions": 4717398425,
                    "epoch": {
                        "epochId": 1017
                    }
                }
            ],
            "pageInfo": {
                "hasNextPage": true,
                "endCursor": "KAEyB..."
            }
        }
    }
}

epoch

Fetch an epoch by its ID, or the latest epoch if none is provided. Contains validator set, gas summary, stake rewards, fund flows, and system state.

Argument	Type	Description
`epochId`	`UInt53`	Omit for the latest epoch

query Epoch {
  epoch {
    epochId
    startTimestamp
    endTimestamp
    referenceGasPrice
    totalTransactions
    totalGasFees
  }
}

{
    "data": {
        "epoch": {
            "epochId": 1285,
            "startTimestamp": "2026-10-19T00:05:42.938Z",
            "endTimestamp": null,
            "referenceGasPrice": "100",
            "totalTransactions": 4974387,
            "totalGasFees": null
        }
    }
}

epochs

Returns: EpochConnection

Argument	Type	Description
`first` / `after` / `last` / `before`	`Int` / `String`	Pagination

query Epochs {
    epochs(first: 1) {
        pageInfo {
            hasPreviousPage
            hasNextPage
            startCursor
            endCursor
        }
        nodes {
            id
            epochId
            endTimestamp
            fundInflow
            fundOutflow
            fundSize
            liveObjectSetDigest
            netInflow
            referenceGasPrice
            startTimestamp
            totalCheckpoints
            totalGasFees
            totalStakeRewards
            totalStakeSubsidies
            totalTransactions
        }
    }
}

{
    "data": {
        "epochs": {
            "pageInfo": {
                "hasPreviousPage": false,
                "hasNextPage": true,
                "startCursor": "MA==",
                "endCursor": "MA=="
            },
            "nodes": [
                {
                    "id": "BAAAA...",
                    "epochId": 0,
                    "endTimestamp": null,
                    "fundInflow": null,
                    "fundOutflow": null,
                    "fundSize": null,
                    "liveObjectSetDigest": null,
                    "netInflow": null,
                    "referenceGasPrice": "1000",
                    "startTimestamp": "2023-04-12T17:00:00Z",
                    "totalCheckpoints": 335742322,
                    "totalGasFees": null,
                    "totalStakeRewards": null,
                    "totalStakeSubsidies": null,
                    "totalTransactions": 6278441641
                }
            ]
        }
    }
}

events

Paginate events emitted on the network. Filter by checkpoint range, sender, emitting module, or event type.

Argument	Type	Description
`first` / `after` / `last` / `before`	`Int` / `String`	Pagination
`filter`	`EventFilter`	Checkpoint range, sender, module, type

query Events {
  events(first: 2, filter: { module: "0x2::coin" }) {
    nodes {
      transactionModule { name }
      contents { type { repr } }
      timestamp
    }
  }
}

{
    "data": {
        "events": {
            "nodes": [
                {
                    "transactionModule": {
                        "name": "coin"
                    },
                    "contents": {
                        "type": {
                            "repr": "0x00000...::deny_list::PerTypeConfigCreated"
                        }
                    },
                    "timestamp": "2026-07-28T18:19:20.849Z"
                },
                {
                    "transactionModule": {
                        "name": "coin"
                    },
                    "contents": {
                        "type": {
                            "repr": "0x00000...::deny_list::PerTypeConfigCreated"
                        }
                    },
                    "timestamp": "2026-07-31T17:08:15.319Z"
                }
            ]
        }
    }
}

coinMetadata

Fetch metadata for a coin type: name, symbol, decimals, description, icon, supply, and regulatory state.

Argument	Type	Description
`coinType`	`String!`	Required — e.g. `"0x2::sui::SUI"`

query CoinMetadata {
  coinMetadata(coinType: "0x2::sui::SUI") {
    name
    symbol
    decimals
    description
    iconUrl
    supply
    regulatedState
  }
}

{
    "data": {
        "coinMetadata": {
            "name": "Sui",
            "symbol": "SUI",
            "decimals": 9,
            "description": "",
            "iconUrl": "",
            "supply": "10000000000000000000",
            "regulatedState": "UNREGULATED"
        }
    }
}

package

Fetch a Move package by address. Exposes modules, type definitions, functions, linkage, and dependencies.

Argument	Type	Description
`address`	`SuiAddress!`	Required
`version`	`UInt53`	Specific package version
`atCheckpoint`	`UInt53`	Latest version as of this checkpoint

Note: Package versioning differs from object versioning — non-system upgrades create new object IDs. To use object versioning semantics, use Query.object → asMovePackage.

query Package {
  package(address: "0x2") {
    address
    version
    modules(first: 2) {
      nodes {
        name
      }
    }
  }
}

{
    "data": {
        "package": {
            "address": "0x00000...",
            "version": 60,
            "modules": {
                "nodes": [
                    {
                        "name": "accumulator"
                    },
                    {
                        "name": "accumulator_metadata"
                    }
                ]
            }
        }
    }
}

packages

Paginate all packages published on-chain, optionally bounded by checkpoint range.

Argument	Type	Description
`first` / `after` / `last` / `before`	`Int` / `String`	Pagination
`filter`	`PackageCheckpointFilter`	afterCheckpoint / beforeCheckpoint

query Packages {
    packages(first: 2) {
        pageInfo {
            hasPreviousPage
            hasNextPage
            startCursor
            endCursor
        }
        nodes {
            address
            id
            version
        }
    }
}

{
    "data": {
        "packages": {
            "pageInfo": {
                "hasPreviousPage": false,
                "hasNextPage": true,
                "startCursor": "AAAAA...",
                "endCursor": "AAAAA..."
            },
            "nodes": [
                {
                    "address": "0x00000...",
                    "id": "BwAAA...",
                    "version": 1
                },
                {
                    "address": "0x00000...",
                    "id": "BwAAA...",
                    "version": 1
                }
            ]
        }
    }
}

packageVersions

Paginate all versions of a package at a given address. Different versions may have different object IDs (except system packages) but share the same original ID.

Returns: MovePackageConnection

Argument	Type	Description
`address`	`SuiAddress!`	Required
`first` / `after` / `last` / `before`	`Int` / `String`	Pagination
`filter`	`VersionFilter`	afterVersion / beforeVersion

query PackageVersions {
    packageVersions(first: 2, address: "0x2") {
      nodes {
        address
        version
        digest
      }
      pageInfo { hasNextPage endCursor }
    }
  }

{
    "data": {
        "packageVersions": {
            "nodes": [
                {
                    "address": "0x00000...",
                    "version": 1,
                    "digest": "FzmqH..."
                },
                {
                    "address": "0x00000...",
                    "version": 2,
                    "digest": "HU6o4..."
                }
            ],
            "pageInfo": {
                "hasNextPage": true,
                "endCursor": "Mg=="
            }
        }
    }
}

nameRecord

Look up a Sui Name Service registration by domain name.

Argument	Type	Description
`name`	`String!`	Required — e.g. `"example.sui"`

query NameRecord {
    nameRecord(name: "mysten.sui") {
        domain
        contents {
            bcs
        }
    }
}

{
    "data": {
        "nameRecord": {
            "domain": "mysten.sui",
            "contents": {
                "bcs": "FEXqjf0Ovw+wuSc94oSrOksNBgHVHRRfpo0udXY7ocgCA3N1aQZteXN0ZW6dws197MkuyKZroyFn+37CebMLw2wyFglgNdt9dQqon5ryZ2e0AQAAAAA="
            }
        }
    }
}

node

Fetch any node by its globally unique ID (GraphQL Global Object Identification spec).

Argument	Type	Description
`id`	`ID!`	Required

query Node {
    node(
        id: "CQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFhnLZPgAAAAAgcfrOwlz/pjgIrTpzq+wTNsyF/ZDzQ427x3IOVLhUYzw="
    ) {
        ... on Object {
            id
            address
            version
            digest
        }
    }
}

{
    "data": {
        "node": {
            "id": "CQAAA...",
            "address": "0x00000...",
            "version": 1054438022,
            "digest": "8fvtM..."
        }
    }
}

type

Fetch a structured representation of a concrete Move type, including layout, abilities, and canonical signature. Types are canonicalized to the package that first defines them.

Argument	Type	Description
`type`	`String!`	Required — e.g. `"0x2::coin::Coin<0x2::sui::SUI>"`

query Type {
    type(type: "0x2::coin::Coin<0x2::sui::SUI>") {
        repr
        abilities
    }
}

{
    "data": {
        "type": {
            "repr": "0x00000...::coin::Coin<0x00000...::sui::SUI>",
            "abilities": [
                "STORE",
                "KEY"
            ]
        }
    }
}

protocolConfigs

Fetch the protocol configuration (feature flags and config parameters) for a given protocol version, or the latest if not specified. These values change only at epoch boundaries during protocol upgrades.

Argument	Type	Description
`version`	`UInt53`	Protocol version (omit for latest)

query ProtocolConfigs {
    protocolConfigs {
        protocolVersion
    }
}

{
    "data": {
        "protocolConfigs": {
            "protocolVersion": 138
        }
    }
}

serviceConfig

Returns the RPC service configuration: timeouts, max query depth/nodes, page sizes, payload limits, and the available data range.

query ServiceConfig {
  serviceConfig {
    maxQueryDepth
    maxQueryNodes
    maxPageSize(type: "Query", field: "transactions")
    queryTimeoutMs
    maxMultiGetSize
  }
}

{
    "data": {
        "serviceConfig": {
            "maxQueryDepth": 20,
            "maxQueryNodes": 300,
            "maxPageSize": 50,
            "queryTimeoutMs": 40000,
            "maxMultiGetSize": 200
        }
    }
}

simulateTransaction

Argument	Type	Description
`transaction`	`JSON!`	Required — Transaction data (JSON or BCS)
`checksEnabled`	`Boolean`	Enable validation checks (default: `true`)
`doGasSelection`	`Boolean`	Auto gas coin selection and budget estimation (default: `false`)


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

Variables

To simulate a BCS-encoded transaction, pass it in the bcs form:

{
  "tx": { "bcs": { "value": "<base64>" } }
}

verifySignature

Verify a signature from a given author. Supports Ed25519, Secp256k1, Secp256r1, MultiSig, ZkLogin, and Passkey. Returns successfully if valid; returns an error with the failure reason if invalid.

Argument	Type	Description
`message`	`Base64!`	Required — Serialized personal message or TransactionData
`signature`	`Base64!`	Required — Serialized signature
`intentScope`	`IntentScope!`	Required — `TRANSACTION_DATA` or `PERSONAL_MESSAGE`
`author`	`SuiAddress!`	Required — Signer's address

Mutation

executeTransaction

Execute a signed transaction and commit its effects on chain. The call waits until the transaction reaches finality and then returns its effects. If finality can't be reached, it returns the error that prevented it. A transaction is final when its effects are guaranteed on chain and can't be revoked.

Argument	Type	Description
`transactionDataBcs`	`Base64!`	Required. BCS-encoded `TransactionData`, Base64-encoded
`signatures`	`[Base64!]!`	Required. List of `flag \|\| signature \|\| pubkey` bytes, each Base64-encoded

ExecutionResult has one field, effects (TransactionEffects). It exposes the same fields as transactionEffects: digest, status, timestamp, gasEffects, balanceChanges, objectChanges, events and others.

📘
Note
Effects may take a moment to appear in GraphQL queries after finality, even in the request that sent the transaction. If a query depends on indexed chain state, poll Query.transaction with the returned digest until it resolves. Examples of such state are output object contents and address balances at the time of the transaction.


mutation ExecuteTransaction($txBytes: Base64!, $signatures: [Base64!]!) {
  executeTransaction(transactionDataBcs: $txBytes, signatures: $signatures) {
    effects {
      digest
      status
      timestamp
      checkpoint { sequenceNumber }
      gasEffects {
        gasSummary {
          computationCost
          storageCost
          storageRebate
          nonRefundableStorageFee
        }
      }
      balanceChanges(first: 5) {
        nodes { owner { address } amount coinType { repr } }
      }
    }
  }
}

{
    "data": {
        "executeTransaction": {
            "effects": {
                "digest": "3Fh8W...",
                "status": "SUCCESS",
                "timestamp": "2026-11-11T09:12:44.118Z",
                "checkpoint": {
                    "sequenceNumber": 342118907
                },
                "gasEffects": {
                    "gasSummary": {
                        "computationCost": 1000000,
                        "storageCost": 1976000,
                        "storageRebate": 978120,
                        "nonRefundableStorageFee": 9880
                    }
                },
                "balanceChanges": {
                    "nodes": [
                        {
                            "owner": { "address": "0x7d20d..." },
                            "amount": "-102997880",
                            "coinType": { "repr": "0x00000...::sui::SUI" }
                        },
                        {
                            "owner": { "address": "0x3c631..." },
                            "amount": "100000000",
                            "coinType": { "repr": "0x00000...::sui::SUI" }
                        }
                    ]
                }
            }
        }
    }
}

Best Practices

Use query aliases to fetch multiple related data in a single request
Leverage fragments to reuse common field selections
Request only the fields you need to optimize performance
Use variables for dynamic query parameters