For AI agents: an LLM-friendly Markdown version of every page is available by appending .md to its URL or by sending an Accept: text/markdown request header. The full documentation index is at https://www.ankr.com/docs/llms.txt
Skip to main content

Sui gRPC (1/3)

API reference for Sui. All methods ->

Part 1 of 3: 1 · 2 · 3


Sui gRPC API is available on Web3 API platform.

The Sui gRPC API provides a fast, type-safe, and efficient interface for interacting with the Sui blockchain. Designed for power users, indexers, explorers, and decentralized apps, this API enables access to Sui data with high performance and low latency.

gRPC offers a high-performance communication protocol that uses Protocol Buffers for fast, compact data serialization. Protocol Buffers enforce strict request and response schemas that match Sui’s RPC definitions exactly — reducing runtime errors, improving compatibility, and enabling automatic client generation. With built-in support for code generation, you can scaffold clients in TypeScript, Go, Rust, and more, making it ideal for scalable backend systems such as indexers, blockchain explorers, and data-intensive decentralized apps.

In addition to standard request–response calls, gRPC supports server-side streaming, enabling real-time data delivery without constant polling. This is especially useful when tracking events, checkpoints, or transactions live. The binary format used by Protocol Buffers is significantly faster and more bandwidth-efficient than JSON.

The Sui gRPC server fully supports server reflection, allowing tools like grpcurl to discover available services and methods at runtime without requiring local .proto files.

Endpoints

NetworkEndpointDescription
Mainnetsui.grpc.ankr.com:443Standard gRPC
Testnetsui-testnet.grpc.ankr.com:443Testnet gRPC
Mainnet Archivearchive.sui.grpc.ankr.com:443Historical data access

For Premium users, pass your token via the x-token header (e.g., -H "x-token: your-token").

Regions

Sui gRPC services are served from Ankr's standard regions — New York, Los Angeles, Frankfurt, Tokyo, and Singapore — and each request is routed to the closest healthy region automatically. You connect to the single global endpoint above; there's no region-specific hostname to choose.

For the full, canonical list of serving regions and how routing and failover work, see Regions & Routing.

Archive endpoint — provides access to historical Sui data that standard full nodes may have pruned. It exposes the same LedgerService API, so you can use the same client code. Use it when querying older transactions, checkpoints, or objects that are no longer available on current nodes.

Methods list

Ledger Service:

Provides read access to global ledger metadata such as chain identifiers, epochs, checkpoints, timestamps, and system-level information.


Move Package Service:

Exposes Move package metadata, allowing you to query on-chain modules and published Move code.


Signature Verification Service:

Performs cryptographic verification for signatures, proofs, and signed messages.


State Service:

Provides access to detailed on-chain state including objects, balances, ownership, object layouts, dynamic fields, and protocol configuration. This is the main service for querying Sui state data.


Subscription Service:

Supports server-side streaming for real-time updates. Use it to subscribe to events, transactions, checkpoints, or other continuous data feeds.

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.


Ledger Service

Provides read access to global ledger metadata such as chain identifiers, epochs, checkpoints, timestamps, and system-level information.

BatchGetObjects

Retrieves multiple objects in one request.

Parameters

  • requests (array; required): List of objects to retrieve. Each entry is a GetObjectRequest.

    • object_id (string; required): ID of the object to fetch.
    • version (uint64; optional): Specific version to return. Latest version is used if omitted.
    • read_mask (object; optional): Field mask for this specific request.
  • read_mask (object; optional): Field mask specifying which object fields to include.

    • paths (array of strings; optional): Protobuf field names to include (for example: object_id, version, digest, owner, object_type, previous_transaction, storage_rebate, json). Some implementations accept "*" to return all available fields.

Returns

  • objects (array): Results for each requested object, in the same order as requests.
    • object (object; optional): Object data when the lookup succeeds.
      • objectId (string): Unique identifier of the object.
      • version (string): Version of the object at the time it was fetched.
      • digest (string): Digest of this object state.
      • owner (object; optional): Ownership information.
        • kind (string; optional): Ownership kind (e.g., ADDRESS, OBJECT, SHARED, IMMUTABLE, CONSENSUS_ADDRESS).
        • address (string; optional): Owner or consensus address, when applicable.
        • version (string; optional): Version marker associated with ownership (mainly for shared objects).
      • objectType (string; optional): Type of the object (e.g., fully qualified Move struct type or package).
      • storageRebate (string; optional): Storage rebate amount returned if the object is deleted.
      • balance (string; optional): Balance value for coin objects (e.g., 0x2::coin::Coin<T>), when applicable.
      • bcs (object; optional): BCS-encoded representation of the object.
        • name (string; optional): Label of the BCS payload.
        • value (string; optional): Base64-encoded BCS bytes.
      • contents (object; optional): BCS-encoded contents of the underlying Move struct for non-package objects.
        • name (string; optional): Type name of the contents.
        • value (string; optional): Base64-encoded serialized data.
      • package (object; optional): Package metadata when the object is a Move package.
      • json (object; optional): JSON rendering of the object’s data, when available.
    • error (object; optional): Error information if the object could not be retrieved.

Request example

grpcurl \
-H "x-token: token-value" \
-d '{
"requests": [
{ "object_id": "0x0000000000000000000000000000000000000000000000000000000000000006"}
],
"read_mask": { "paths": ["*"] }
}' \
sui.grpc.ankr.com:443 \
sui.rpc.v2.LedgerService.BatchGetObjects

Response example

{
"objects": [
{
"object": {
"bcs": {
"name": "Object",
"value": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgVjbG9jawVDbG9jawAAcUe1JQAAAAAoAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAbyXYShmgEAAAIBAAAAAAAAACDB7K0J+aEqTtdTNV6fyXp81uAAUxcbRAl2UsKvtr/TigAAAAAAAAAA"
},
"objectId": "0x0000000000000000000000000000000000000000000000000000000000000006",
"version": "632637297",
"digest": "GZ4vSjvoMLXj9BoiBsmJ52YKCR4nRTK2oEYMjMyCvBMk",
"owner": {
"kind": "SHARED",
"version": "1"
},
"objectType": "0x0000000000000000000000000000000000000000000000000000000000000002::clock::Clock",
"hasPublicTransfer": false,
"contents": {
"name": "0x0000000000000000000000000000000000000000000000000000000000000002::clock::Clock",
"value": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAbyXYShmgEAAA=="
},
"previousTransaction": "E411BJgW1RbuBePFkJ4BYaWVgF7g87wC46TjjYzH5Z1B",
"storageRebate": "0",
"json": {
"id": "0x0000000000000000000000000000000000000000000000000000000000000006",
"timestamp_ms": "1763646397938"
}
}
}
]
}

Methods list

BatchGetTransactions

Retrieves multiple transactions by digest.

Parameters

  • digests (array of strings; required): List of transaction digests to retrieve.
  • read_mask (object; optional): Field mask specifying which transaction fields to include.
    • paths (array of strings; optional): Protobuf field names to include (for example: digest, transaction, transaction.sender, transaction.kind, effects, effects.status, effects.changed_objects, events, balance_changes, checkpoint, timestamp). Some implementations accept "*" to return all available fields.

Returns

  • transactions (array): Results for each requested digest, in the same order as digests.
    • transaction (object; optional): Full transaction data when the lookup succeeds.
      • digest (string): Digest of the transaction.
      • transaction (object; optional): The transaction payload, including sender, gas settings, and transaction kind.
        • sender (string; optional): Address of the sender.
        • gasPayment (object; optional): Gas payment details (objects used to pay gas, owner, price, budget).
        • kind (object; optional): High-level transaction kind (e.g., ProgrammableTransaction, ConsensusCommitPrologue, etc.).
      • signatures (array; optional): User signatures authorizing the transaction.
        • Each entry may contain scheme, signature, publicKey, or a multisig/zkLogin/passkey structure.
      • effects (object; optional): Execution effects.
        • status (object; optional): Execution status, typically { success: true } or { success: false }.
        • changedObjects (array; optional): Objects created, mutated, or deleted by the transaction.
        • gasUsed (object; optional): Breakdown of gas usage (computation, storage, rebate).
        • transactionDigest (string; optional): Digest of the executed transaction.
        • dependencies (array of strings; optional): Digests of dependency transactions.
      • events (object; optional): Events generated by this transaction, if any.
      • balanceChanges (array; optional): Per-address balance updates produced by the transaction.
      • checkpoint (string; optional): Checkpoint sequence number containing this transaction.
      • timestamp (string; optional): Timestamp of the checkpoint (ISO-8601 format).
      • objects (object; optional): Objects referenced or produced by this transaction (may be omitted when returned at checkpoint level).
    • error (object; optional): Error information if the transaction could not be retrieved.

Request example

grpcurl \
-H "x-token: token-value" \
-d '{
"digests": ["hSwNywhBjUhHvSsZT5PhVFz5iZgMR24onKQKFSyubVu"],
"read_mask": { "paths": ["*"] }
}' \
sui.grpc.ankr.com:443 \
sui.rpc.v2.LedgerService.BatchGetTransactions

Response example

{
"transactions": [
{
"transaction": {
"digest": "hSwNywhBjUhHvSsZT5PhVFz5iZgMR24onKQKFSyubVu",
"transaction": {
"digest": "hSwNywhBjUhHvSsZT5PhVFz5iZgMR24onKQKFSyubVu",
"version": 1,
"kind": {
"kind": "CONSENSUS_COMMIT_PROLOGUE_V4",
"consensusCommitPrologue": {
"epoch": "951",
"round": "1188405",
"commitTimestamp": "2025-11-19T15:34:37.980Z",
"consensusCommitDigest": "EqQHgXytDRK7Api3bw9AmwSaJ26s81bMBYY7Hs4gQJ2i"
}
},
"sender": "0x0000000000000000000000000000000000000000000000000000000000000000",
"gasPayment": {
"objects": [
{
"objectId": "0x0000000000000000000000000000000000000000000000000000000000000000",
"version": "0",
"digest": "11111111111111111111111111111111"
}
],
"owner": "0x0000000000000000000000000000000000000000000000000000000000000000",
"price": "1",
"budget": "0"
},
"expiration": {
"kind": "NONE"
}
},
"effects": {
"digest": "75dAW4QrYV6Vt9ngQA4g14DDnmCCWF5BgE3dsgvtgzwy",
"version": 2,
"status": {
"success": true
},
"epoch": "951",
"gasUsed": {
"computationCost": "0",
"storageCost": "0",
"storageRebate": "0",
"nonRefundableStorageFee": "0"
},
"transactionDigest": "hSwNywhBjUhHvSsZT5PhVFz5iZgMR24onKQKFSyubVu",
"dependencies": [
"FRS9rMUZ2ycrVYFdtS2wiWE12JMwuVWKSZy3wpFd5ifD"
],
"changedObjects": [
{
"objectId": "0x0000000000000000000000000000000000000000000000000000000000000006",
"inputState": "INPUT_OBJECT_STATE_EXISTS",
"outputState": "OUTPUT_OBJECT_STATE_OBJECT_WRITE",
"objectType": "0x2::clock::Clock"
}
]
},
"checkpoint": "213906807",
"timestamp": "2025-11-19T15:34:37.980Z"
}
}
]
}

GetCheckpoint

Retrieves a checkpoint by sequence or digest.

Parameters

  • sequence_number (uint64; optional): Sequence number of the checkpoint to fetch. If both sequence_number and digest are omitted, the latest checkpoint is returned.
  • digest (string; optional): Digest of the checkpoint to fetch.
  • read_mask (object; optional): Field mask specifying which checkpoint fields to include in the response.
    • paths (array of strings; optional): Protobuf field names to include (for example: sequence_number, digest, summary, summary.timestamp, summary.epoch, transactions, objects). Some implementations accept "*" to return all available fields.

Returns

  • checkpoint (object; optional): Checkpoint data for the requested identifier, or the latest checkpoint if no identifier was provided.
    • sequenceNumber (string): Height of this checkpoint.
    • digest (string): Digest of this checkpoint’s summary.
    • summary (object; optional): Compact header describing the checkpoint.
      • epoch (string; optional): Epoch that this checkpoint belongs to.
      • totalNetworkTransactions (string; optional): Total number of transactions committed since genesis, including this checkpoint.
      • contentDigest (string; optional): Digest of the checkpoint contents.
      • previousDigest (string; optional): Digest of the previous checkpoint summary (empty for genesis).
      • timestamp (string; optional): Timestamp of the checkpoint (ISO-8601).
    • signature (object; optional): Aggregated validator signature certifying this checkpoint.
      • epoch (string; optional): Epoch in which the aggregated signature was produced.
      • signature (string; optional): Aggregated BLS signature bytes (base64-encoded).
    • contents (object; optional): Committed contents of this checkpoint.
      • digest (string; optional): Digest of the checkpoint contents.
      • transactions (array; optional): List of transaction/effects digests included in this checkpoint.
    • transactions (array; optional): Executed transactions included in this checkpoint. Each entry has the same structure as ExecutedTransaction returned by transaction-related methods.
    • objects (object; optional): Set of objects referenced or produced by transactions in this checkpoint, returned as a collection of object records when requested.

Request example

grpcurl \
-H "x-token: token-value" \
-d '{
"read_mask": {
"paths": [
"sequence_number",
"digest",
"summary"
]
}
}' \
sui.grpc.ankr.com:443 \
sui.rpc.v2.LedgerService.GetCheckpoint

Response example

{
"checkpoint": {
"sequenceNumber": "214225619",
"digest": "GNSviTUX6DXkiCPKYDo1uihJsm5oRcjtvrkT8mVQyay8",
"summary": {
"bcs": {
"name": "CheckpointSummary",
"value": "uAMAAAAAAADT0sQMAAAAADnoOwgBAAAAIPstfiDnwCpkcFlrp8nRs5js5xXtg0tbEcIIcaE+c+ldASDIgYxj9sUG3w0UPAMjIBpRGWeo4PV/1D5fw6pQLRm0VefE2UCSBwAAcCuegkRtAAC8pNR6PmsAABT/ZlEVAQAA/fdQoZoBAAAAAAoAAdn2AQAAAAAA"
},
"digest": "GNSviTUX6DXkiCPKYDo1uihJsm5oRcjtvrkT8mVQyay8",
"epoch": "952",
"sequenceNumber": "214225619",
"totalNetworkTransactions": "4433111097",
"contentDigest": "HuVZqNZXeitWwTsHdNKT5JcjcsHZfT28CJAgpCFxy3kg",
"previousDigest": "EVh7YWQnfvF89gg48v7tYDtX12SVyWSWQb5YtbCzJaxc",
"epochRollingGasCostSummary": {
"computationCost": "8324734633191",
"storageCost": "120141016607600",
"storageRebate": "117916092900540",
"nonRefundableStorageFee": "1191071645460"
},
"timestamp": "2025-11-20T12:50:29.501Z",
"versionSpecificData": "AAHZ9gEAAAAAAA=="
}
}
}

GetEpoch

Retrieves details for a specific epoch.

Parameters

  • epoch (uint64; optional): The epoch number to fetch. If omitted, the service returns the current epoch.
  • read_mask (object; optional): Field mask specifying which epoch fields to include in the response.
    • paths (array of strings; optional): Protobuf field names to include (for example: epoch, protocol_version, reference_gas_price, validator_set, validator_set.members, system_state). Some implementations accept "*" to return all available fields.

Returns

  • epoch (object; optional): Information about the requested epoch.
    • epoch (string): Epoch number.
    • firstCheckpoint (string; optional): Sequence number of the first checkpoint in this epoch.
    • lastCheckpoint (string; optional): Sequence number of the last checkpoint in this epoch.
    • start (string; optional): Start timestamp of the epoch (ISO-8601 format).
    • end (string; optional): End timestamp of the epoch (ISO-8601 format).
    • referenceGasPrice (string; optional): Reference gas price for this epoch.
    • protocolConfig (object; optional): Protocol configuration active in this epoch.
      • protocolVersion (string; optional): Protocol version number.

Request example

grpcurl \
-H "x-token: token-value" \
-d '{
"epoch": "951"
}' \
sui.grpc.ankr.com:443 \
sui.rpc.v2.LedgerService.GetEpoch

Response example

{
"epoch": {
"epoch": "951",
"firstCheckpoint": "213579473",
"lastCheckpoint": "213938636",
"start": "2025-11-18T17:42:29.619Z",
"end": "2025-11-19T17:42:30.554Z",
"referenceGasPrice": "500",
"protocolConfig": {
"protocolVersion": "101"
}
}
}

GetObject

Retrieves a single object by ID.

Parameters

  • object_id (string; required): The ObjectId of the object to retrieve.
  • version (uint64; optional): The specific version of the object to return. If omitted and the object is live, the latest version is returned.
  • read_mask (object; optional): Field mask specifying which object fields to include in the response.
    • paths (array of strings; optional): Protobuf field names to include (for example: object_id, version, digest, owner, object_type, previous_transaction, storage_rebate, json). Some implementations accept "*" to return all available fields.

Returns

  • object (object; optional): The returned object data if the lookup succeeds.
    • objectId (string): ID of the object.
    • version (string): Version of the object.
    • digest (string): Digest of this object state.
    • owner (object; optional): Ownership information.
      • May include fields such as address, version, or ownership kind (shared, immutable, object, etc.).
    • objectType (string): Type of the object (e.g., Move struct tag or package).
    • bcs (object; optional): Raw BCS representation of the object.
      • name (string): Name of the BCS-encoded type.
      • value (string): Base64-encoded BCS bytes.
    • contents (object; optional): BCS bytes of a Move struct value.
    • package (object; optional): Package information (present for Move packages).
    • previousTransaction (string; optional): Digest of the transaction that last mutated this object.
    • storageRebate (string; optional): Storage rebate amount associated with this object.
    • json (object; optional): JSON rendering of the object.
    • balance (string; optional): Current balance if the object is a 0x2::coin::Coin<T>.

Request example

grpcurl \
-H "x-token: token-value" \
-d '{
"object_id": "0x0000000000000000000000000000000000000000000000000000000000000006"
}' \
sui.grpc.ankr.com:443 \
sui.rpc.v2.LedgerService.GetObject

Response example

{
"object": {
"objectId": "0x0000000000000000000000000000000000000000000000000000000000000006",
"version": "632658683",
"digest": "H7BP9CsjCWqWdV459C7bAzECD5ozmFBfhSgb1KxXb5L7"
}
}

GetServiceInfo

Retrieves node, chain, and service metadata.

Parameters

None.

Returns

  • chainId (string): Chain identifier (digest of the genesis checkpoint).
  • chain (string): Human-readable chain name (e.g., "mainnet").
  • epoch (string): Current epoch of the node.
  • checkpointHeight (string): Height of the most recently executed checkpoint.
  • timestamp (string): Timestamp of the latest executed checkpoint (ISO-8601 format).
  • lowestAvailableCheckpoint (string): Lowest checkpoint height for which checkpoint and transaction data are available.
  • lowestAvailableCheckpointObjects (string): Lowest checkpoint height for which object data is available.
  • server (string): Software version string for this service.

Request example

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

Response example

{
"chainId": "4btiuiMPvEENsttpZC7CZ53DruC3MAgfznDbASZ7DR6S",
"chain": "mainnet",
"epoch": "952",
"checkpointHeight": "214248984",
"timestamp": "2025-11-20T14:23:54.546Z",
"lowestAvailableCheckpoint": "130842232",
"lowestAvailableCheckpointObjects": "213684741",
"server": "sui-node/1.60.1-49d95e90e36e"
}

GetTransaction

Retrieves a single transaction by digest.

Parameters

  • digest (string; required): Digest of the transaction to retrieve.
  • read_mask (object; optional): Field mask specifying which transaction fields to include in the response.
    • paths (array of strings; optional): Protobuf field names to include (for example: digest, transaction, transaction.sender, transaction.kind, effects, effects.status, effects.changed_objects, events, balance_changes, checkpoint, timestamp, objects). Some implementations accept "*" to return all available fields.

Returns

  • transaction (object; optional): Executed transaction data if the lookup succeeds.
    • digest (string): Digest of the transaction.
    • transaction (object; optional): Transaction payload.
      • sender (string; optional): Address of the transaction sender.
      • gasPayment (object; optional): Gas payment configuration (gas objects, owner, price, budget).
      • kind (object; optional): Transaction kind (for example, programmable transaction, consensus commit prologue).
    • signatures (array; optional): User signatures authorizing the transaction.
    • effects (object; optional): Execution effects for this transaction.
      • status (object; optional): Execution status (for example, success: true).
      • changedObjects (array; optional): Objects created, mutated, or deleted by the transaction.
      • gasUsed (object; optional): Gas usage breakdown (computation, storage, rebate).
      • transactionDigest (string; optional): Digest of the executed transaction.
      • dependencies (array of strings; optional): Digests of dependency transactions.
    • events (object; optional): Events emitted during transaction execution, if any.
    • balanceChanges (array; optional): Per-address, per-coin-type balance updates caused by this transaction.
    • checkpoint (string; optional): Checkpoint sequence number containing this transaction.
    • timestamp (string; optional): Timestamp of the checkpoint that includes this transaction (ISO-8601 format).
    • objects (object; optional): Objects referenced as inputs or produced as outputs by this transaction.

Request example

grpcurl \
-H "x-token: token-value" \
-d '{
"digest": "hSwNywhBjUhHvSsZT5PhVFz5iZgMR24onKQKFSyubVu",
"read_mask": {
"paths": ["*"]
}
}' \
sui.grpc.ankr.com:443 \
sui.rpc.v2.LedgerService.GetTransaction

Response example

{
"transaction": {
"digest": "hSwNywhBjUhHvSsZT5PhVFz5iZgMR24onKQKFSyubVu",
"effects": {
"bcs": {
"name": "TransactionEffects",
"value": "AQC3AwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAIApcj2B2cnBzLKo2O9lBRpzwZh0U+NBGVIDtATtFaKEUAAABINZF/xw55sjHgk8nWetzMPXVfvvmQQQazN0LJEwBiOfMbq2iJQAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAYBba2iJQAAAAAgA4c8QzpRZ3K7ARu5evaUjapDn2phY9m2brwDZ7zIfAwCAQAAAAAAAAABIF4Fipa86aBJjMYj9zfd72ecY9o6PfR0Z6iy8mAtZEAEAgEAAAAAAAAAAAAA"
},
"digest": "75dAW4QrYV6Vt9ngQA4g14DDnmCCWF5BgE3dsgvtgzwy",
"version": 2,
"status": {
"success": true
},
"epoch": "951",
"gasUsed": {
"computationCost": "0",
"storageCost": "0",
"storageRebate": "0",
"nonRefundableStorageFee": "0"
},
"transactionDigest": "hSwNywhBjUhHvSsZT5PhVFz5iZgMR24onKQKFSyubVu",
"dependencies": [
"FRS9rMUZ2ycrVYFdtS2wiWE12JMwuVWKSZy3wpFd5ifD"
],
"lamportVersion": "631418222",
"changedObjects": [
{
"objectId": "0x0000000000000000000000000000000000000000000000000000000000000006",
"inputState": "INPUT_OBJECT_STATE_EXISTS",
"inputVersion": "631418221",
"inputDigest": "EmpuZ8vHkphwFnaH6NuC3cPsK58aWtdmJWCUpFZosNK",
"inputOwner": {
"kind": "SHARED",
"version": "1"
},
"outputState": "OUTPUT_OBJECT_STATE_OBJECT_WRITE",
"outputVersion": "631418222",
"outputDigest": "7L2E1st8zEP7QTaEyKYurMYmMBR1NV5WmYcS3QEsC63d",
"outputOwner": {
"kind": "SHARED",
"version": "1"
},
"idOperation": "NONE",
"objectType": "0x0000000000000000000000000000000000000000000000000000000000000002::clock::Clock"
}
]
}
}
}

Move Package Service:

Exposes Move package metadata, allowing you to query on-chain modules and published Move code.