Sui JSON-RPC Skill

Use this skill to run Sui JSON-RPC operations through uxc + JSON-RPC.

Reuse the uxc skill for shared execution and error-handling guidance.

Prerequisites

uxc is installed and available in PATH.
Network access to https://fullnode.mainnet.sui.io.
No API key is required for the public mainnet fullnode in this skill's default flow.

Scope

This skill covers a safe read-first Sui JSON-RPC surface:

chain identity and latest checkpoint reads
checkpoint lookup
object lookup
reference gas price reads
latest system state reads
pubsub subscriptions for events and transaction effects

This skill does not cover:

unsafe_* transaction-building methods
sui_executeTransactionBlock
wallet signing flows
custom/private Sui RPC providers with different auth or rate limits

Endpoint And Discovery

This skill targets the public Sui fullnode endpoint:

https://fullnode.mainnet.sui.io

For pubsub, use a Sui provider WebSocket endpoint that you have verified actually accepts JSON-RPC subscriptions. Do not assume the public HTTPS fullnode host automatically supports the same wss:// hostname for pubsub.

uxc JSON-RPC discovery depends on OpenRPC or rpc.discover. Sui exposes a discoverable method surface, so help-first flow works directly against the endpoint.

Authentication

The default public endpoint used by this skill does not require authentication.

If a user later points the same workflow at a private Sui RPC provider, verify its auth model first before reusing this skill unchanged.

Core Workflow

Use the fixed link command by default:
- command -v sui-jsonrpc-cli
- If missing, create it: uxc link sui-jsonrpc-cli https://fullnode.mainnet.sui.io
- sui-jsonrpc-cli -h
Inspect operation schema first:
- sui-jsonrpc-cli sui_getLatestCheckpointSequenceNumber -h
- sui-jsonrpc-cli sui_getCheckpoint -h
- sui-jsonrpc-cli sui_getObject -h
Prefer read/setup validation before any deeper query:
- sui-jsonrpc-cli sui_getChainIdentifier
- sui-jsonrpc-cli sui_getLatestCheckpointSequenceNumber
- sui-jsonrpc-cli suix_getReferenceGasPrice
Execute with key/value or positional JSON:
- key/value: sui-jsonrpc-cli sui_getCheckpoint id=254502592
- positional JSON: sui-jsonrpc-cli sui_getObject '{"object_id":"0x6"}'
Use uxc subscribe start directly for pubsub streams:
- uxc subscribe start wss://<verified-sui-rpc-host> suix_subscribeEvent '{"params":[{"Package":"0x2"}]}' --sink file:$HOME/.uxc/subscriptions/sui-events.ndjson
- uxc subscribe start wss://<verified-sui-rpc-host> suix_subscribeTransaction '{"params":[{"FromAddress":"0x..."}]}' --sink file:$HOME/.uxc/subscriptions/sui-transactions.ndjson
- uxc subscribe status <job_id>
- uxc subscribe stop <job_id>

Recommended Subscription Operations

suix_subscribeEvent
suix_subscribeTransaction

Guardrails

Keep automation on the JSON output envelope; do not use --text.
Parse stable fields first: ok, kind, protocol, data, error.
Stay on the public read-only method surface by default.
Do not call any unsafe_* methods through this skill without explicit follow-up design and review.
Do not use this skill for write/sign/submit flows; those need separate wallet/auth guidance.
Use uxc subscribe start for pubsub methods; the fixed sui-jsonrpc-cli link is for normal request/response methods.
Subscription jobs should always write to a sink file so events can be inspected and replayed safely.
Before documenting or automating a Sui pubsub host, confirm the specific provider actually exposes JSON-RPC WebSocket subscriptions; public HTTPS endpoints do not guarantee a matching wss:// endpoint.
Public RPC availability and rate limits can change over time; if discovery or execution starts failing, re-check the endpoint before assuming a uxc bug.
sui-jsonrpc-cli <operation> ... is equivalent to uxc https://fullnode.mainnet.sui.io <operation> ....

References

Usage patterns: references/usage-patterns.md
Sui documentation: https://docs.sui.io/