SUI gRPC Docs | NOWNodes

SUI gRPC API

NOWNodes provides access to the SUI gRPC API, allowing developers to query blockchain data, read objects, inspect transactions, execute or simulate transactions, resolve SuiNS names, verify signatures, and subscribe to checkpoint streams using Protocol Buffers and gRPC.

Endpoint

Copied!

sui-grpc.nownodes.io

Authentication

All requests must include your NOWNodes API key as gRPC metadata.

Copied!

api-key: YOUR_API_KEY

Proto files

SUI gRPC methods are described in .proto files.

Download the SUI proto files from:

Copied!

https://github.com/NOWNodes/sui-apis-grpc

Clone the repository:

Copied!

git clone https://github.com/NOWNodes/sui-apis-grpc

The SUI gRPC proto files are located here:

Copied!

sui-apis-grpc/proto/sui/rpc/v2

The proto root directory should be:

Copied!

sui-apis-grpc/proto

Use this directory as the import path in tools such as grpcurl or Postman.

Available services

Service	Proto file	Description
sui.rpc.v2.LedgerService	ledger_service.proto	Reads ledger data such as objects, transactions, checkpoints, epochs, and service status.
sui.rpc.v2.StateService	state_service.proto	Reads live state data such as owned objects, dynamic fields, balances, and coin metadata.
sui.rpc.v2.TransactionExecutionService	transaction_execution_service.proto	Executes or simulates SUI transactions.
sui.rpc.v2.MovePackageService	move_package_service.proto	Reads Move package metadata, datatypes, functions, and package versions.
sui.rpc.v2.SignatureVerificationService	signature_verification_service.proto	Verifies user signatures against supported SUI message types.
sui.rpc.v2.SubscriptionService	subscription_service.proto	Provides server-streaming subscriptions, such as checkpoint streaming.
sui.rpc.v2.NameService	name_service.proto	Resolves SuiNS names and reverse-resolves addresses to names.

LedgerService

The LedgerService provides access to core ledger data: service information, objects, transactions, checkpoints, and epochs.

Proto file:

Copied!

sui-apis-grpc/proto/sui/rpc/v2/ledger_service.proto

LedgerService methods

Method	Type	Description
GetServiceInfo	Unary	Returns general information about the node and chain state.
GetObject	Unary	Returns a single object by object ID and optional version.
BatchGetObjects	Unary	Returns multiple objects in a single request.
GetTransaction	Unary	Returns a single executed transaction by digest.
BatchGetTransactions	Unary	Returns multiple executed transactions by digest.
GetCheckpoint	Unary	Returns a checkpoint by sequence number, digest, or the latest checkpoint if no identifier is provided.
GetEpoch	Unary	Returns epoch information by epoch number, or the current epoch if no epoch is provided.

GetServiceInfo

Returns general information about the current state of the service.

Full method:

Copied!

sui.rpc.v2.LedgerService.GetServiceInfo

Request:

Copied!

{}

Example grpcurl request:

Copied!

ggrpcurl \
  -insecure \
  -H 'api-key: YOUR_API_KEY' \
  -emit-defaults \
  -proto './sui-apis-grpc/proto/sui/rpc/v2/ledger_service.proto' \
  -import-path './sui-apis-grpc/proto' \
  -d '{}' \
  'sui-grpc.nownodes.io' \
  sui.rpc.v2.LedgerService.GetServiceInfo

Response includes fields such as:

Field	Description
chainId	Chain identifier.
chain	Human-readable chain name, such as mainnet or testnet.
epoch	Current epoch based on the highest executed checkpoint.
checkpointHeight	Height of the most recently executed checkpoint.
timestamp	Timestamp of the most recently executed checkpoint.
lowestAvailableCheckpoint	Lowest checkpoint for which checkpoint and transaction data is available.
lowestAvailableCheckpointObjects	Lowest checkpoint for which object data is available.
server	Software version or server identifier.

GetObject

Returns an object by object ID.

Full method:

Copied!

sui.rpc.v2.LedgerService.GetObject

Request by latest object version:

Copied!

{
  "objectId": "0xOBJECT_ID"
}

Request by specific object version:

Copied!

{
  "objectId": "0xOBJECT_ID",
  "version": "123"
}

Request with read mask:

Copied!

{
"objectId": "0xOBJECT_ID",
  "readMask": {
    "paths": [
      "object_id",
      "version",
      "digest",
      "object_type"
    ]
  }
}

Request fields:

Field	Type	Required	Description
objectId	string	Yes	Object ID of the requested object.
version	string / uint64	No	Specific object version. If omitted and the object is live, the latest version is returned.
readMask	object	No	Field mask that limits which object fields are returned.

BatchGetObjects

Returns multiple objects in one request.

Full method:

Copied!

sui.rpc.v2.LedgerService.BatchGetObjects

Request:

Copied!

{
  "requests": [
    {
      "objectId": "0xOBJECT_ID_1"
    },
    {
      "objectId": "0xOBJECT_ID_2"
    }
  ]
}

Request with read mask:

Copied!

{
  "requests": [
    {
      "objectId": "0xOBJECT_ID_1"
    },
    {
      "objectId": "0xOBJECT_ID_2"
    }
  ],
  "readMask": {
    "paths": [
      "object_id",
      "version",
      "digest"
    ]
  }
}

Request fields:

Field	Type	Required	Description
requests	array	Yes	List of object lookup requests.
readMask	object	No	Field mask applied to returned objects.

GetTransaction

Returns an executed transaction by digest.

Full method:

Copied!

sui.rpc.v2.LedgerService.GetTransaction

Request:

Copied!

{
  "digest": "TRANSACTION_DIGEST"
}

Request with read mask:

Copied!

{
  "digest": "TRANSACTION_DIGEST",
  "readMask": {
    "paths": [
      "digest",
      "effects",
      "events",
      "checkpoint"
    ]
  }
}

Request fields:

Field	Type	Required	Description
digest	string	Yes	Digest of the requested transaction.
readMask	object	No	Field mask that limits which transaction fields are returned.

BatchGetTransactions

Returns multiple executed transactions by digest.

Full method:

Copied!

sui.rpc.v2.LedgerService.BatchGetTransactions

Request:

Copied!

{
  "digests": [
    "TRANSACTION_DIGEST_1",
    "TRANSACTION_DIGEST_2"
  ]
}

Request fields:

Field	Type	Required	Description
digests	array	Yes	List of transaction digests.
readMask	object	No	Field mask applied to returned transactions.

GetCheckpoint

Returns a checkpoint.

If neither sequenceNumber nor digest is provided, the latest checkpoint is returned.

Full method:

Copied!

sui.rpc.v2.LedgerService.GetCheckpoint

Latest checkpoint request:

Copied!

{}

Checkpoint by sequence number:

Copied!

{
  "sequenceNumber": "1000"
}

Checkpoint by digest:

Copied!

{
  "digest": "CHECKPOINT_DIGEST"
}

Request with read mask:

Copied!

{
  "sequenceNumber": "1000",
  "readMask": {
    "paths": [
      "sequence_number",
      "digest",
      "timestamp"
    ]
  }
}

Request fields:

Field	Type	Required	Description
sequenceNumber	string / uint64	No	Checkpoint sequence number.
digest	string	No	Checkpoint digest.
readMask	object	No	Field mask that limits which checkpoint fields are returned.

Example grpcurl request:

Copied!

grpcurl \
  -insecure \
  -H 'api-key: YOUR_API_KEY' \
  -emit-defaults \
  -proto './sui-apis-grpc/proto/sui/rpc/v2/ledger_service.proto' \
  -import-path './sui-apis-grpc/proto' \
  -d '{}' \
  'sui-grpc.nownodes.io' \
  sui.rpc.v2.LedgerService.GetCheckpoint

GetEpoch

Returns epoch information.

If no epoch is provided, the current epoch is returned.

Full method:

Copied!

sui.rpc.v2.LedgerService.GetEpoch

Current epoch request:

Copied!

{}

Specific epoch request:

Copied!

{
  "epoch": "10"
}

Request fields:

Field	Type	Required	Description
epoch	string / uint64	No	Requested epoch number. If omitted, the current epoch is returned.
readMask	object	No	Field mask that limits which epoch fields are returned.

StateService

The StateService provides access to live state data such as dynamic fields, owned objects, coin metadata, and balances.

Proto file:

Copied!

sui-apis-grpc/proto/sui/rpc/v2/state_service.proto

StateService methods

Method	Type	Description
ListDynamicFields	Unary	Lists dynamic fields owned by a parent object.
ListOwnedObjects	Unary	Lists objects owned by an address.
GetCoinInfo	Unary	Returns metadata and treasury information for a coin type.
GetBalance	Unary	Returns the total balance for a specific coin type owned by an address.
ListBalances	Unary	Lists all coin balances owned by an address.

ListDynamicFields

Lists dynamic fields owned by a parent object.

Full method:

Copied!

sui.rpc.v2.StateService.ListDynamicFields

Request:

Copied!

{
  "parent": "0xPARENT_OBJECT_ID",
  "pageSize": 50
}

Request fields:

Field	Type	Required	Description
parent	string	Yes	UID of the parent object that owns the dynamic fields.
pageSize	integer	No	Maximum number of dynamic fields to return.
pageToken	bytes / base64 string	No	Token received from a previous paginated response.
readMask	object	No	Field mask that limits returned dynamic field data.

ListOwnedObjects

Lists objects owned by an address.

Full method:

Copied!

sui.rpc.v2.StateService.ListOwnedObjects

Request:

Copied!

{
  "owner": "0xOWNER_ADDRESS",
  "pageSize": 50
}

Request with object type filter:

Copied!

{
  "owner": "0xOWNER_ADDRESS",
  "objectType": "0x2::coin::Coin<0x2::sui::SUI>"
}

Request fields:

Field	Type	Required	Description
owner	string	Yes	Address that owns the objects.
pageSize	integer	No	Maximum number of objects to return.
pageToken	bytes / base64 string	No	Token received from a previous paginated response.
readMask	object	No	Field mask that limits returned object data.
objectType	string	No	Optional type filter.

GetCoinInfo

Returns metadata and treasury information for a coin type.

Full method:

Copied!

sui.rpc.v2.StateService.GetCoinInfo

Request:

Copied!

{
  "coinType": "0x2::sui::SUI"
}

Request fields:

Field	Type	Required	Description
coinType	string	Yes	Coin type to request information about.

GetBalance

Returns the total balance for one coin type owned by an address.

Full method:

Copied!

sui.rpc.v2.StateService.GetBalance

Request:

Copied!

{
  "owner": "0xOWNER_ADDRESS",
  "coinType": "0x2::sui::SUI"
}

Request fields:

Field	Type	Required	Description
owner	string	Yes	Owner address.
coinType	string	Yes	Coin type, for example 0x2::sui::SUI.

ListBalances

Lists all coin balances owned by an address.

Full method:

Copied!

sui.rpc.v2.StateService.ListBalances

Request:

Copied!

{
  "owner": "0xOWNER_ADDRESS",
  "pageSize": 50
}

Request fields:

Field	Type	Required	Description
owner	string	Yes	Owner address.
pageSize	integer	No	Maximum number of balance entries to return.
pageToken	bytes / base64 string	No	Token received from a previous paginated response.

Example grpcurl request:

Copied!

grpcurl \
  -insecure \
  -H 'api-key: YOUR_API_KEY' \
  -emit-defaults \
  -proto './sui-apis-grpc/proto/sui/rpc/v2/state_service.proto' \
  -import-path './sui-apis-grpc/proto' \
  -d '{
    "owner": "0xOWNER_ADDRESS"
  }' \
  'sui-grpc.nownodes.io' \
  sui.rpc.v2.StateService.ListBalances

TransactionExecutionService

The TransactionExecutionService executes or simulates SUI transactions.

Proto file:

Copied!

sui-apis-grpc/proto/sui/rpc/v2/transaction_execution_service.proto

TransactionExecutionService methods

Method	Type	Description
ExecuteTransaction	Unary	Executes a signed transaction on the network.
SimulateTransaction	Unary	Simulates a transaction without committing it to the network.

ExecuteTransaction

Executes a signed transaction.

Full method:

Copied!

sui.rpc.v2.TransactionExecutionService.ExecuteTransaction

Request structure:

Copied!

{
  "transaction": {},
  "signatures": [],
  "readMask": {
    "paths": [
      "effects.status",
      "checkpoint"
    ]
  }
}

Request fields:

Field	Type	Required	Description
transaction	object	Yes	Transaction to execute.
signatures	array	Yes	User signatures authorizing execution of the transaction.
readMask	object	No	Field mask that controls which fields are returned.

SimulateTransaction

Simulates a transaction without committing it.

Full method:

Copied!

sui.rpc.v2.TransactionExecutionService.SimulateTransaction

Request structure:

Copied!

{
  "transaction": {},
  "checks": "ENABLED",
  "doGasSelection": true
}

Request fields:

Field	Type	Required	Description
transaction	object	Yes	Transaction to simulate.
readMask	object	No	Field mask that controls which fields are returned.
checks	enum	No	Controls whether transaction checks are enabled or disabled.
doGasSelection	boolean	No	Performs gas selection based on budget estimation and includes selected gas payment and budget in the response.

MovePackageService

The MovePackageService reads Move package metadata, datatypes, functions, and package versions.

Proto file:

Copied!

sui-apis-grpc/proto/sui/rpc/v2/move_package_service.proto

MovePackageService methods

Method	Type	Description
GetPackage	Unary	Returns a Move package by package ID.
GetDatatype	Unary	Returns a datatype descriptor from a package module.
GetFunction	Unary	Returns a function descriptor from a package module.
ListPackageVersions	Unary	Lists all versions of a package.

GetPackage

Returns a Move package.

Full method:

Copied!

sui.rpc.v2.MovePackageService.GetPackage

Request:

Copied!

{
  "packageId": "0xPACKAGE_ID"
}

Request fields:

Field	Type	Required	Description
packageId	string	Yes	Storage ID of the requested package.

GetDatatype

Returns a datatype descriptor from a Move package module.

Full method:

Copied!

sui.rpc.v2.MovePackageService.GetDatatype

Request:

Copied!

{
  "packageId": "0xPACKAGE_ID",
  "moduleName": "module_name",
  "name": "DatatypeName"
}

Request fields:

Field	Type	Required	Description
packageId	string	Yes	Storage ID of the requested package.
moduleName	string	Yes	Name of the requested module.
name	string	Yes	Name of the requested datatype.

GetFunction

Returns a function descriptor from a Move package module.

Full method:

Copied!

sui.rpc.v2.MovePackageService.GetFunction

Request:

Copied!

{
  "packageId": "0xPACKAGE_ID",
  "moduleName": "module_name",
  "name": "function_name"
}

Request fields:

Field	Type	Required	Description
packageId	string	Yes	Storage ID of the requested package.
moduleName	string	Yes	Name of the requested module.
name	string	Yes	Name of the requested function.

ListPackageVersions

Lists versions of a Move package.

Full method:

Copied!

sui.rpc.v2.MovePackageService.ListPackageVersions

Request:

Copied!

{
  "packageId": "0xPACKAGE_ID",
  "pageSize": 100
}

Request fields:

Field	Type	Required	Description
packageId	string	Yes	Storage ID of any version of the package.
pageSize	integer	No	Maximum number of versions to return.
pageToken	bytes / base64 string	No	Token received from a previous paginated response.

SignatureVerificationService

The SignatureVerificationService verifies user signatures against supported SUI message types.

Proto file:

Copied!

sui-apis-grpc/proto/sui/rpc/v2/signature_verification_service.proto

SignatureVerificationService methods

Method	Type	Description
VerifySignature	Unary	Verifies a user signature against a provided message and, optionally, an expected address.

VerifySignature

Verifies a user signature.

Full method:

Copied!

sui.rpc.v2.SignatureVerificationService.VerifySignature

Request structure:

Copied!

{
  "message": {},
  "signature": {},
  "address": "0xADDRESS"
}

Request fields:

Field	Type	Required	Description
message	object	Yes	Message to verify. Supported message types include PersonalMessage and TransactionData.
signature	object	Yes	User signature to verify.
address	string	No	Optional address to validate against the signature.
jwks	array	No	Optional JWK set used for verifying zkLogin signatures.
epoch	string / uint64	No	Epoch to use for verification.

Response fields:

Field	Description
isValid	Indicates whether the signature is valid.
reason	Reason why verification failed, if isValid is false.

SubscriptionService

The SubscriptionService provides server-streaming APIs.

Proto file:

Copied!

sui-apis-grpc/proto/sui/rpc/v2/subscription_service.proto

SubscriptionService methods

Method	Type	Description
SubscribeCheckpoints	Server streaming	Subscribes to the checkpoint stream. The server returns checkpoint messages in order and without gaps.

SubscribeCheckpoints

Subscribes to checkpoint updates.

Full method:

Copied!

sui.rpc.v2.SubscriptionService.SubscribeCheckpoints

Request:

Copied!

{}

Request with read mask:

Copied!

{
  "readMask": {
    "paths": [
      "cursor",
      "checkpoint.sequence_number",
      "checkpoint.digest"
    ]
  }
}

Request fields:

Field	Type	Required	Description
readMask	object	No	Field mask specifying which parts of the streaming response should be returned.

Response fields:

Field	Description
cursor	Checkpoint sequence number and current cursor in the stream.
checkpoint	Requested checkpoint data.

Example grpcurl request:

Copied!

grpcurl \
  -insecure \
  -H 'api-key: YOUR_API_KEY' \
  -emit-defaults \
  -proto './sui-apis-grpc/proto/sui/rpc/v2/subscription_service.proto' \
  -import-path './sui-apis-grpc/proto' \
  -d '{}' \
  'sui-grpc.nownodes.io' \
  sui.rpc.v2.SubscriptionService.SubscribeCheckpoints

This request stays open and returns new checkpoint messages until the connection is closed.

To stop the stream, press:

Ctrl + C

NameService

The NameService resolves SuiNS names and reverse-resolves addresses.

Proto file:

Copied!

sui-apis-grpc/proto/sui/rpc/v2/name_service.proto

NameService methods

Method	Type	Description
LookupName	Unary	Resolves a SuiNS name to its name record.
ReverseLookupName	Unary	Resolves an address to its linked SuiNS name record.

LookupName

Looks up a SuiNS name.

Full method:

Copied!

sui.rpc.v2.NameService.LookupName

Request:

Copied!

{
  "name": "example.sui"
}

Alternative request format:

Copied!

{
  "name": "@example"
}

Request fields:

Field	Type	Required	Description
name	string	Yes	SuiNS name. Supports both @name and name.sui formats.

ReverseLookupName

Looks up the SuiNS name linked to an address.

Full method:

Copied!

sui.rpc.v2.NameService.ReverseLookupName

Request:

Copied!

{
  "address": "0xADDRESS"
}

Request fields:

Field	Type	Required	Description
address	string	Yes	Address to reverse-resolve.

Postman setup

You can send SUI gRPC requests using Postman.

Step 1: Create a gRPC request

Open Postman and select:

Copied!

New → gRPC Request

Step 2: Enter the endpoint

Copied!

sui-grpc.nownodes.io

Step 3: Import a proto file

Choose:

Copied!

Import a .proto file

For example, to use LedgerService, import:

Copied!

sui-apis-grpc/proto/sui/rpc/v2/ledger_service.proto

Import path:

Copied!

sui-apis-grpc/proto

Step 4: Select service and method

Example:

Copied!

sui.rpc.v2.LedgerService / GetCheckpoint

Step 5: Add metadata

Add the following metadata:

Copied!

api-key: YOUR_API_KEY

Step 6: Add request body

Example:

Copied!

{}

Click Invoke to send the request.

grpcurl syntax

General syntax:

Copied!

grpcurl \
  -insecure \
  -H 'api-key: YOUR_API_KEY' \
  -emit-defaults \
  -proto './sui-apis-grpc/proto/sui/rpc/v2/SERVICE_FILE.proto' \
  -import-path './sui-apis-grpc/proto' \
  -d 'REQUEST_JSON' \
  'sui-grpc.nownodes.io' \
  sui.rpc.v2.ServiceName.MethodName

Common errors

UNAUTHENTICATED

The API key is missing or incorrect.

Make sure your request includes metadata:

Copied!

api-key: YOUR_API_KEY

Method not found

The selected method name is incorrect, or the wrong proto file was imported.

Examples of correct method formats:

Copied!

sui.rpc.v2.LedgerService.GetCheckpoint

Some tools may use slash notation:

Copied!

sui.rpc.v2.LedgerService/GetCheckpoint

google/rpc/status.proto: File not found

The import path is incomplete or missing Google RPC proto definitions.

Make sure your import path points to:

Copied!

sui-apis-grpc/proto

If your tool does not provide google/rpc definitions automatically, make sure these files are available:

Copied!

google/rpc/status.proto

Copied!

google/rpc/error_details.proto

Missing input file

The gRPC client cannot find the selected .proto file.

Check that the selected proto file exists, for example:

Copied!

sui-apis-grpc/proto/sui/rpc/v2/ledger_service.proto

And that the import path is:

Copied!

sui-apis-grpc/proto

Documentation

SUI gRPC API

Endpoint

Authentication

Proto files

Available services

LedgerService

LedgerService methods

GetServiceInfo

GetObject

BatchGetObjects

GetTransaction

BatchGetTransactions

GetCheckpoint

GetEpoch

StateService

StateService methods

ListDynamicFields

ListOwnedObjects

GetCoinInfo

GetBalance

ListBalances

TransactionExecutionService

TransactionExecutionService methods

ExecuteTransaction

SimulateTransaction

MovePackageService

MovePackageService methods

GetPackage

GetDatatype

GetFunction

ListPackageVersions

SignatureVerificationService

SignatureVerificationService methods

VerifySignature

SubscriptionService

SubscriptionService methods

SubscribeCheckpoints

NameService

NameService methods

LookupName

ReverseLookupName

Postman setup

Step 1: Create a gRPC request

Step 2: Enter the endpoint

Step 3: Import a proto file

Step 4: Select service and method

Step 5: Add metadata

Step 6: Add request body

grpcurl syntax

Common errors

UNAUTHENTICATED

Method not found

google/rpc/status.proto: File not found

Missing input file