Sui gRPC (3/3)

API reference for Sui. All methods ->

Part 3 of 3: 1 · 2 · 3

Methods list

SubscribeCheckpoints

Subscribes to a stream of newly produced checkpoints.

Parameters

• read_mask (object; optional): Field mask specifying which fields of the streamed response to include. If omitted, all default fields are returned.
  • paths (array of strings; optional): Protobuf field names to include in each SubscribeCheckpointsResponse message (for example: cursor, checkpoint, checkpoint.sequence_number, checkpoint.digest, checkpoint.summary, checkpoint.transactions). Some implementations accept "*" to return all available fields.

Returns

Stream of SubscribeCheckpointsResponse messages:

• cursor (string): Checkpoint sequence number representing the current position in the checkpoint stream.
• checkpoint (object; optional): Details of the checkpoint at the current cursor.
  • sequenceNumber (string): Height of this checkpoint.
  • digest (string): Digest of the checkpoint’s summary.
  • summary (object; optional): High-level checkpoint summary (epoch, total transactions, content digest, timestamp, etc.).
  • signature (object; optional): Validator aggregated signature that certified this checkpoint.
  • contents (object; optional): Committed transaction digests and signatures for this checkpoint.
  • transactions (array; optional): Executed transactions included in this checkpoint.
  • objects (object; optional): Objects referenced or produced by transactions in this checkpoint.

Request example

grpcurl \
  -H "x-token: token-value" \
  -d '{}' \
  sui.grpc.ankr.com:443 \
  sui.rpc.v2.SubscriptionService.SubscribeCheckpoints

Reponse example

{
  "cursor": "213938636",
  "checkpoint": {
    "sequenceNumber": "213938636",
    "digest": "6mSsq3PjZc4rK2aFT3eK6oRxmM6DPo7LcFFo7z1Doq9H",
    "summary": {
      "epoch": "951",
      "sequenceNumber": "213938636",
      "totalNetworkTransactions": "1254933841",
      "contentDigest": "9B7kLz8F8svuZ8mFyKqutMAyCcwR1R2uF3xTjv7p9QyE",
      "previousDigest": "3JfxNefB6DmSaJMj1iJXqZF4KA3VjsoUUP1gHnN9LaMR",
      "timestamp": "2025-11-19T17:42:30.554Z"
    }
  }
}

---

Transaction Execution Service:

Lets you simulate and execute transactions, fetch execution effects, run dry-runs, and retrieve transaction metadata. This is the primary service for write operations and transaction analysis.

ExecuteTransaction

Executes a signed transaction on-chain.

Parameters

• transaction (object; required): The transaction to execute.
  • bcs (object; optional): BCS-encoded transaction data.
    • name (string): Expected to be "TransactionData".
    • value (string): Base64-encoded BCS bytes of the transaction.
  • digest (string; optional): Transaction digest, if already known.
  • version (int32; optional): Transaction version.
  • kind (object; optional): Transaction kind and data (for example, programmable transaction, system transaction).
  • sender (string; optional): Sui address of the transaction sender.
  • gas_payment (object; optional): Gas payment configuration.
  • expiration (object; optional): Transaction expiration settings (for example, epoch-based).

Note: In practice, most clients construct the transaction using SDKs/wallets and send it via the bcs field, rather than manually building all nested fields.

• signatures (array; required): Set of UserSignature objects authorizing execution of the transaction. Typically, contains one or more signatures depending on the scheme (ED25519, multisig, zkLogin, passkey, etc.).
• read_mask (object; optional): Field mask specifying which parts of the executed transaction to return. If omitted, defaults to: effects.status, checkpoint.
  • paths (array of strings; optional): Names of fields to include in the ExecutedTransaction result (for example: "digest", "transaction", "signatures", "effects", "effects.status", "effects.gas_used", "checkpoint", "timestamp", "objects"). Some implementations accept "*" to return all available fields.

Returns

• transaction (object; optional): Executed transaction result (ExecutedTransaction).
  • digest (string): Digest of the executed transaction.
  • transaction (object; optional): Original transaction data (if requested).
  • signatures (array; optional): User signatures used to authorize execution.
  • effects (object; optional): Execution effects (status, gas used, changed objects, dependencies, etc.).
  • events (object; optional): Events emitted by the transaction.
  • checkpoint (string; optional): Checkpoint sequence number that includes this transaction.
  • timestamp (string; optional): Timestamp of the checkpoint containing the transaction.
  • balanceChanges (array; optional): Balance changes resulting from execution.
  • objects (object; optional): Objects referenced or produced by this transaction.

Note: The exact fields present depend on the read_mask you provide.

Request example

grpcurl \
  -H "x-token: token-value" \
  -d '{
        "transaction": {
          "bcs": {
            "name": "TransactionData",
            "value": "BASE64_BCS_TRANSACTION"
          }
        },
        "signatures": [
          {
            "scheme": "ED25519",
            "simple": {
              "scheme": "ED25519",
              "signature": "BASE64_SIGNATURE",
              "publicKey": "BASE64_PUBLIC_KEY"
            }
          }
        ],
        "read_mask": {
          "paths": [
            "digest",
            "effects.status",
            "effects.gas_used",
            "checkpoint"
          ]
        }
      }' \
  sui.grpc.ankr.com:443 \
  sui.rpc.v2.TransactionExecutionService.ExecuteTransaction

Response example

{
  "transaction": {
    "digest": "H3m2oZ4aJx9t8fV6vG3Z9KQ9XkqD4zTqLk2oQZ2V7pU",
    "transaction": {
      "sender": "0x8a1f2c1e4b3d9a55678900112233445566778899aa11223344556677889900ff",
      "gasPayment": {
        "objects": [
          {
            "objectId": "0x4e1b...02f1",
            "version": "12345",
            "digest": "Gp3qz9Ck1B4Hd8xF3vZtYc9tK1p9V5mQm29L6gC48zdK"
          }
        ],
        "owner": "0x8a1f2c1e4b3d9a55678900112233445566778899aa11223344556677889900ff",
        "price": "1000",
        "budget": "50000000"
      }
    },
    "signatures": [
      {
        "scheme": "ED25519",
        "simple": {
          "scheme": "ED25519",
          "signature": "AAAAAAAAAAAAAAAAAAAAAA==",
          "publicKey": "BBBBBBBBBBBBBBBBBBBBBB=="
        }
      }
    ],
    "effects": {
      "digest": "7rFqL4y8Bv4mMZ1HjX89U8C4o5JkF9wN1u5NQ3p4zXq",
      "version": 2,
      "status": {
        "success": true
      },
      "epoch": "951",
      "gasUsed": {
        "computationCost": "5000",
        "storageCost": "3000",
        "storageRebate": "1500",
        "nonRefundableStorageFee": "200"
      },
      "transactionDigest": "H3m2oZ4aJx9t8fV6vG3Z9KQ9XkqD4zTqLk2oQZ2V7pU",
      "changedObjects": [
        {
          "objectId": "0x0000000000000000000000000000000000000000000000000000000000000006",
          "inputState": "INPUT_OBJECT_STATE_EXISTS",
          "outputState": "OUTPUT_OBJECT_STATE_OBJECT_WRITE",
          "outputVersion": "631418222",
          "objectType": "0x2::coin::Coin<0x2::sui::SUI>"
        }
      ]
    },
    "checkpoint": "213906807",
    "timestamp": "2025-11-19T15:34:37.980Z"
  }
}

---

SimulateTransaction

Simulates a transaction without executing it.

Parameters

• transaction (object; required): The transaction to simulate (not executed on-chain).

  • bcs (object; optional): BCS-encoded transaction data.
    • name (string): Usually "TransactionData".
    • value (string): Base64-encoded BCS bytes of the transaction.
  • Other fields (digest, version, kind, sender, gas_payment, expiration) may be present, but most clients rely on bcs.

• read_mask (object; optional): Field mask specifying which parts of the simulated ExecutedTransaction to include.

  • paths (array of strings; optional): Field names to include in the response (for example: "digest", "effects", "effects.status", "effects.gas_used", "checkpoint", "objects"). Some implementations accept "*" to return all available fields.

• checks (string; optional): Controls whether validation checks are applied during simulation.

  • "ENABLED" (default): Run full transaction checks (recommended).
  • "DISABLED": Skip checks; useful for low-level analysis but may produce unrealistic results.

• do_gas_selection (boolean; optional): When true, the node estimates gas usage, selects appropriate gas coins, and includes the chosen gas payment and budget in the response. Ignored if checks is set to "DISABLED".

Returns

• transaction (object; optional): Simulated execution result in the ExecutedTransaction format.

  • digest (string): Simulated transaction digest.
  • transaction (object; optional): Transaction data (may include updated gas payment when do_gas_selection is true).
  • effects (object; optional): Simulated execution effects (status, gas usage, changed objects, dependencies, etc.).
  • events (object; optional): Events that would be emitted by this transaction.
  • checkpoint (string; optional): Simulated checkpoint position, if applicable.
  • timestamp (string; optional): Simulated timestamp.
  • balanceChanges (array; optional): Estimated balance changes.
  • objects (object; optional): Objects that would be read/changed.

• command_outputs (array): Per-command intermediate outputs from executing the programmable transaction.

  • Each entry is a CommandResult:
    • return_values (array): Outputs returned by a command.
      • argument (object): Reference to the argument this output corresponds to (kind: GAS, INPUT, or RESULT, plus index).
      • value (object): BCS-encoded value.
      • json (object): JSON rendering of the output, when available.
    • mutated_by_ref (array): Outputs for values mutated via mutable references, with the same shape as return_values.

Request example

grpcurl \
  -H "x-token: token-value" \
  -d '{
    "transaction": {
      "bcs": {
        "name": "TransactionData",
        "value": "AAm3AwAAAAAAADUiEgAAAAAAAJziwJyaAQAAIM2OI+iSHv7wsCz6HJ2NdpMelfuJGh/nlMWzDYH8lHAvAQAgefKIMDsHD3If7IXj/emWCPFZEQDIwG7nmVTP+j3M/SoAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAAAAAA=="
      }
    }
  }' \
  sui.grpc.ankr.com:443 \
  sui.rpc.v2.TransactionExecutionService.SimulateTransaction

Response example

{
  "transaction": {
    "digest": "9JvPyz9pLRuCrN8WUyj4q7LZ4E8xRCqUj9Dj3m7JrT3",
    "transaction": {
      "digest": "9JvPyz9pLRuCrN8WUyj4q7LZ4E8xRCqUj9Dj3m7JrT3",
      "sender": "0xabc...123",
      "kind": {
        "kind": "PROGRAMMABLE_TRANSACTION"
      }
    },
    "effects": {
      "status": {
        "success": true
      },
      "gasUsed": {
        "computationCost": "20000",
        "storageCost": "5000",
        "storageRebate": "1200",
        "nonRefundableStorageFee": "0"
      },
      "version": 1,
      "digest": "5tuFT5NmrFh4u9w1SwQLuRY1fJ5r93R4cdE9eWHK8n8",
      "changedObjects": [],
      "dependencies": []
    },
    "balanceChanges": [],
    "checkpoint": null,
    "timestamp": null
  },
  "command_outputs": [
    {
      "return_values": [
        {
          "argument": {
            "kind": "INPUT",
            "input": 0
          },
          "value": {
            "name": "u64",
            "value": "AAAAAA=="
          },
          "json": 42
        }
      ],
      "mutated_by_ref": []
    }
  ]
}