Migrating to GraphQL

This guide compares JSON-RPC queries to their equivalent GraphQL counterpart. While it is possible to systematically rewrite JSON-RPC queries (for example, sui_getTotalTransactionBlocks) to their GraphQL counterparts using this guide, it is recommended that you revisit your application's query patterns to take full advantage of the flexibility that GraphQL offers in serving queries that touch multiple potentially nested endpoints (for example transactions, balances, coins), and use the following examples to get a flavor of how the two APIs express similar concepts.

For a comprehensive list of all available GraphQL features, consult the reference.

Example 1: Get total transaction blocks

The goal is to get the total number of transaction blocks in the network.

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "sui_getTotalTransactionBlocks",
  "params": []
}

GraphQL

query {
  checkpoint {
    networkTotalTransactions
  }
}

Example 2: Get a specific transaction block

The goal is to get the transaction block by its digest.

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "sui_getTransactionBlock",
  "params": [
    "Hay2tj3GcDYcE3AMHrej5WDsHGPVAYsegcubixLUvXUF",
    {
      "showInput": true,
      "showRawInput": false,
      "showEffects": true,
      "showEvents": true,
      "showObjectChanges": false,
      "showBalanceChanges": false
    }
  ]
}

GraphQL

query {
  transactionBlock(digest: "Hay2tj3GcDYcE3AMHrej5WDsHGPVAYsegcubixLUvXUF") {
    gasInput {
      gasSponsor {
        address
      }
      gasPrice
      gasBudget
    }
    effects {
      status
      timestamp
      checkpoint {
        sequenceNumber
      }
      epoch {
        epochId
        referenceGasPrice
      }
    }
  }
}

Example 3: Get coin objects owned by an address

The goal is to return all Coin<0x2::sui::SUI> objects an address owns.

JSON-RPC

query {
  "jsonrpc": "2.0",
  "id": 1,
  "method": "suix_getCoins",
  "params": [
    "0x5094652429957619e6efa79a404a6714d1126e63f551f4b6c7fb76440f8118c9", //owner
    "0x2::sui::SUI",                                                      //coin type
    "0xe5c651321915b06c81838c2e370109b554a448a78d3a56220f798398dde66eab", //cursor
    3 //limit
  ]
}

GraphQL

query {
  address(address: "0x5094652429957619e6efa79a404a6714d1126e63f551f4b6c7fb76440f8118c9") {
    coins(
      first: 3,
      after: "IAB3ha2PEA4ESRF4UErsJufJEwYpmSbCq7UNpxIHnLhG",
      type: "0x2::sui::SUI"
    ) {
      nodes {
        address
      }
    }
  }
}

info

The cursor is now passed in the after (or before) fields on the connection, and the limit in the first or last fields.

Related links

• GraphQL reference: Auto-generated GraphQL reference for Sui RPC.
• GraphQL quick-start: Querying Sui RPC with GraphQL gets you started using GraphQL to query the Sui RPC for on-chain data.
• GraphQL concepts: GraphQL for Sui RPC examines the elements of GraphQL that you should know to get the most from the service.