JSON-RPC Overview

The Sui JSON-RPC API provides a comprehensive interface for interacting with the Sui blockchain. It follows the JSON-RPC 2.0 specification and is available over HTTP and WebSocket connections.

API Endpoints

Mainnet:

https://fullnode.mainnet.sui.io:443

Testnet:

https://fullnode.testnet.sui.io:443

Devnet:

https://fullnode.devnet.sui.io:443

Local Network:

http://127.0.0.1:9000

API Categories

The Sui JSON-RPC API is organized into several namespaces:

Core APIs (`sui` namespace)

ReadApi - Query objects, transactions, checkpoints, and protocol state
WriteApi - Execute and inspect transactions

Extended APIs (`suix` namespace)

CoinReadApi - Query coin balances and metadata
EventApi - Query and subscribe to on-chain events
GovernanceApi - Access staking and validator information

Transaction Builder (`unsafe` namespace)

TransactionBuilder - Build unsigned transactions (use SDKs for production)

Making Requests

HTTP Example

curl -X POST https://fullnode.mainnet.sui.io:443 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "sui_getObject",
    "params": [
      "0x5",
      {
        "showType": true,
        "showOwner": true,
        "showContent": true
      }
    ]
  }'

WebSocket Subscriptions

WebSocket connections enable real-time event subscriptions:

const ws = new WebSocket('wss://fullnode.mainnet.sui.io:443');

ws.onopen = () => {
  ws.send(JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'suix_subscribeEvent',
    params: [{ All: [] }]
  }));
};

ws.onmessage = (event) => {
  console.log('Event:', JSON.parse(event.data));
};

Request Format

All JSON-RPC requests must include:

jsonrpc: Version string, always "2.0"
id: Request identifier (number or string)
method: API method name (e.g., "sui_getObject")
params: Array of parameters (order matters)

Response Format

Successful responses:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": { ... }
}

Error responses:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params"
  }
}

Rate Limits

Public RPC endpoints have rate limits. For production applications:

Run your own full node
Use a managed RPC provider
Implement exponential backoff for retries

API Discovery

Query available methods using the rpc.discover method:

curl -X POST https://fullnode.mainnet.sui.io:443 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"rpc.discover","params":[]}'

Next Steps

Explore specific APIs in the sidebar
Use the Rust SDK for type-safe interactions
Try the GraphQL API for flexible queries

​API Endpoints

​API Categories

​Core APIs (sui namespace)

​Extended APIs (suix namespace)

​Transaction Builder (unsafe namespace)

​Making Requests

​HTTP Example

​WebSocket Subscriptions

​Request Format

​Response Format

​Rate Limits

​API Discovery

​Next Steps