Migrating to GraphQL

info

The GraphQL RPC service is currently under development. The MVP is scheduled to be launched at the end of January 2024.

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 APIs, 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.