Skip to main content

Sui gRPC API Overview

Updated on
Oct 21, 2026

Overview​

Sui gRPC API provides high-performance access to network data through gRPC interfaces. It serves as a powerful tool for developers who need to:

  • Access blockchain data with low latency
  • Monitor on-chain activities and state changes
  • Query account and object states efficiently
  • Execute transactions with minimal overhead

Access​

You can access Sui gRPC directly through your existing Quicknode Sui endpoint—no additional add-ons are needed. The gRPC services are available on port 9000, a dedicated and secure channel for gRPC communication.

Endpoint and Token Configuration​

When connecting to Sui gRPC services, the port must be specified in the URL:

  • Endpoint: The name of your endpoint followed by .sui-mainnet.quiknode.pro and the port number 9000 (e.g., https://docs-demo.sui-mainnet.quiknode.pro:9000)
  • Token: The alphanumeric string that follows the endpoint name in the URL

For example, if your endpoint looks like this: https://docs-demo.sui-mainnet.quiknode.pro/123456789/, then your authentication credentials would be:

  • Endpoint: https://docs-demo.sui-mainnet.quiknode.pro:9000
  • Token: 123456789

Network Availability​

Sui gRPC API is available on both Mainnet and Testnet.

Archive Data Access​

Archive queries for historical Sui blockchain data are available on Mainnet only through gRPC. Archive access is integrated into your existing gRPC endpoint:

  • Same Endpoint: Archive queries use the same endpoint and port (9000) as regular gRPC requests—no separate endpoint needed
  • Automatic Routing: Full nodes retain the last 14 epochs. Queries for data older than 14 epochs are routed to archive nodes
  • No Configuration Required: Archive access works without any additional setup or configuration
  • Mainnet Only: Archive support is not available on Testnet

Note: This differs from the Sui Foundation's approach, which uses separate endpoints for archive data. With Quicknode, you can query both recent and historical data through a single endpoint.

Request metadata and version compatibility​

Simulation client protocol version​

SimulateTransaction belongs to sui.rpc.v2.TransactionExecutionService. It previews execution without submitting a transaction or requiring a signature.

Starting with v1.82.1, the server can add allowed-proposer restrictions to the returned transaction when:

  • The server enables enable-simulate-allowed-proposers.
  • The client sends x-sui-client-protocol-version: 136 or higher.
  • The node has the required proposer information.

Clients that omit the header or send a version below 136 keep the previous behavior.

Send the version as gRPC request metadata. Your client must support that version, including TransactionExpiration::Validity. For grpcurl, add -H "x-sui-client-protocol-version: 136". For the other examples, set SUI_CLIENT_PROTOCOL_VERSION.

See the upstream compatibility change.

Simulation example setup​

Set QN_SUI_GRPC_HOST to your hostname and port 9000, without https:// or the token path, and QN_SUI_TOKEN to your endpoint token.

Generate Python and Go bindings or load TypeScript definitions from sui/rpc/v2/transaction_execution_service.proto and its imports; see the language setup guides.

The examples simulate 0x2::tx_context::epoch with checks disabled and gas selection off, using mock gas. They require no funded account and do not submit a transaction. This mock-gas example does not exercise allowed-proposer selection. For a production preview, use your transaction, enable checks, and configure gas selection as needed.

Supported Services​

Sui gRPC API includes the following services:

Ledger Service​


  • BatchGetObjects: Retrieves multiple objects in a single request
  • BatchGetTransactions: Retrieves multiple transactions in a single request
  • GetCheckpoint: Retrieves checkpoint information
  • GetEpoch: Retrieves epoch information
  • GetObject: Retrieves a single object
  • GetServiceInfo: Retrieves service information
  • GetTransaction: Retrieves a single transaction

Transaction Execution Service​


  • ExecuteTransaction: Executes a transaction on the Sui network
  • SimulateTransaction: Previews transaction execution without submitting it

State Service​


  • ListDynamicFields: Lists dynamic fields for an object
  • ListOwnedObjects: Lists objects owned by an address
  • GetCoinInfo: Retrieves coin information
  • GetBalance: Retrieves balance for a specific coin type
  • ListBalances: Lists all balances for an address

Move Package Service​


  • GetPackage: Retrieves Move package information
  • GetDatatype: Retrieves datatype information from a package
  • GetFunction: Retrieves function information from a package
  • ListPackageVersions: Lists available versions of a package

Subscription Service​


  • SubscribeCheckpoints: Subscribes to checkpoint updates

Signature Verification Service​


  • VerifySignature: Verifies transaction signatures

Limits & Data Retention​

  • Pagination: List and batch operations return paginated results. Always check the next_page_token field in responses to retrieve additional pages. Do not assume all data is returned in a single request
  • Field Masks: Use the read_mask field when applicable to reduce response size and latency, especially for large resources like objects and transactions
  • Archive Data: Full nodes retain the last 14 epochs of data. On Mainnet, queries for data older than 14 epochs are automatically routed to archive nodes through your existing endpoint—no separate configuration needed
  • Streaming: Use SubscribeCheckpoints for real-time data instead of polling. If a stream is interrupted, resume from the last known checkpoint using other APIs to backfill missed data

Making Sui gRPC Requests​

To make requests to Sui gRPC using different languages, check out the method-specific documentation for each service. Each method includes examples in:

Last updated on