Using grpcurl with Sui gRPC
Inspect Dwellir Sui gRPC services with reflection, run current v2 requests, and select retained checkpoints without generating clients.
Sui RPC endpoint: endpoint URLs, plans and pricing.
grpcurl uses server reflection to discover Dwellir's deployed Sui API. You do not need local proto files for these commands.
Install grpcurl
Install a binary from the grpcurl releases, or build it with Go:
go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest
export PATH="$(go env GOPATH)/bin:$PATH"For Homebrew, Windows, Docker and the full flag reference, see the grpcurl guide.
Configure authentication
Set DWELLIR_API_KEY in your environment. The commands below expand that variable inside grpcurl, so the key is absent from the process arguments.
export SUI_GRPC_ENDPOINT=api-sui-mainnet-full.n.dwellir.com:443Use TLS on port 443. Pass authentication as x-api-key metadata, rather than appending the key to the URL.
Discover services and messages
grpcurl -expand-headers -H 'x-api-key: ${DWELLIR_API_KEY}' \
"$SUI_GRPC_ENDPOINT" list
grpcurl -expand-headers -H 'x-api-key: ${DWELLIR_API_KEY}' \
"$SUI_GRPC_ENDPOINT" list sui.rpc.v2.TransactionExecutionService
grpcurl -expand-headers -H 'x-api-key: ${DWELLIR_API_KEY}' \
"$SUI_GRPC_ENDPOINT" describe sui.rpc.v2.ExecuteTransactionRequestThe execution service is TransactionExecutionService. Inspect request messages before constructing a payload; reflection lists schemas, rather than testing method behavior.
Query service information
grpcurl -max-time 10 -expand-headers -H 'x-api-key: ${DWELLIR_API_KEY}' \
-d '{}' "$SUI_GRPC_ENDPOINT" sui.rpc.v2.LedgerService/GetServiceInfoThe response includes checkpointHeight, lowestAvailableCheckpoint, and lowestAvailableCheckpointObjects. Those values change as the node advances and prunes data.
Read the latest checkpoint
grpcurl -max-time 10 -expand-headers -H 'x-api-key: ${DWELLIR_API_KEY}' \
-d '{"read_mask":{"paths":["sequence_number","summary.timestamp"]}}' \
"$SUI_GRPC_ENDPOINT" sui.rpc.v2.LedgerService/GetCheckpointThe selected fields appear inside checkpoint. The timestamp is checkpoint.summary.timestamp, rather than timestamp_ms.
Read balances and package functions
grpcurl -max-time 10 -expand-headers -H 'x-api-key: ${DWELLIR_API_KEY}' \
-d '{"owner":"0x0","coin_type":"0x2::sui::SUI"}' \
"$SUI_GRPC_ENDPOINT" sui.rpc.v2.StateService/GetBalance
grpcurl -max-time 10 -expand-headers -H 'x-api-key: ${DWELLIR_API_KEY}' \
-d '{"package_id":"0x2","module_name":"transfer","name":"transfer"}' \
"$SUI_GRPC_ENDPOINT" sui.rpc.v2.MovePackageService/GetFunctionBalance data appears inside balance. A package member request uses name, not function_name or datatype_name.
Choose a recent historical range
This example also requires jq:
checkpoint=$(grpcurl -max-time 10 -expand-headers \
-H 'x-api-key: ${DWELLIR_API_KEY}' -d '{}' "$SUI_GRPC_ENDPOINT" \
sui.rpc.v2.LedgerService/GetServiceInfo | jq -r '.checkpointHeight | tonumber - 10')
request=$(jq -n --arg checkpoint "$checkpoint" \
'{start_checkpoint:$checkpoint,options:{limit:2},read_mask:{paths:["sequence_number"]}}')
grpcurl -max-time 10 -expand-headers -H 'x-api-key: ${DWELLIR_API_KEY}' \
-d "$request" "$SUI_GRPC_ENDPOINT" sui.rpc.v2.LedgerService/ListCheckpointsThe start bound is inclusive. An end bound, when supplied, is exclusive. The final frame includes end.
A range below retained history returns OUT_OF_RANGE. Individual checkpoint and proof reads can return NOT_FOUND for pruned or unindexed data.
Test live streams
grpcurl -max-time 5 -expand-headers -H 'x-api-key: ${DWELLIR_API_KEY}' \
-d '{"read_mask":{"paths":["sequence_number"]}}' \
"$SUI_GRPC_ENDPOINT" sui.rpc.v2.SubscriptionService/SubscribeCheckpointsThe client deadline terminates this unbounded stream. DEADLINE_EXCEEDED after receiving frames is expected for this command.
Filtered subscriptions can emit progress-only frames. See filter syntax and recovery guidance.
Execute or simulate transactions
Follow the execution and simulation references for encoded transaction bodies and mask roots.
Put serialized transaction bytes in transaction.bcs.value. Successful execution submits a signed transaction; simulation does not.