SuiJsonRpcClient

This page exists for maintaining legacy JSON-RPC code. New code should use SuiGrpcClient and its top-level methods by default. See Migrating from JSON-RPC for replacement examples.

The SuiJsonRpcClient connects to a Sui network's JSON-RPC server. It also implements the Core API, so SDKs that accept ClientWithCoreApi can support it during a migration.

import { SuiJsonRpcClient, getJsonRpcFullnodeUrl } from '@mysten/sui/jsonRpc';

const client = new SuiJsonRpcClient({
	url: getJsonRpcFullnodeUrl('mainnet'),
	network: 'mainnet',
});

// Use the Core API
const { object } = await client.core.getObject({ objectId: '0x...' });

Connecting to a Sui network

To establish a legacy JSON-RPC connection, import SuiJsonRpcClient from @mysten/sui/jsonRpc and pass the relevant URL to the url parameter. The following example establishes a connection to Devnet and gets all Coin<coin_type> objects owned by an address.

import { getJsonRpcFullnodeUrl, SuiJsonRpcClient } from '@mysten/sui/jsonRpc';

// use getJsonRpcFullnodeUrl to define Devnet RPC location
const rpcUrl = getJsonRpcFullnodeUrl('devnet');

// create a client connected to devnet
const client = new SuiJsonRpcClient({ url: rpcUrl, network: 'devnet' });

// get coins owned by an address
// replace <OWNER_ADDRESS> with actual address in the form of 0x123...
await client.getCoins({
	owner: '<OWNER_ADDRESS>',
});

Network URLs:

• localnet: http://127.0.0.1:9000
• devnet: https://fullnode.devnet.sui.io:443
• testnet: https://fullnode.testnet.sui.io:443

For local development, you can run cargo run --bin sui -- start --with-faucet --force-regenesis to spin up a local network with a local validator, a Full node, and a faucet server. Refer to the Local Network guide for more information.

Manually calling unsupported RPC methods

You can use SuiJsonRpcClient to call any RPC method the node you're connecting to exposes. Most RPC methods are built into SuiJsonRpcClient, but you can use call to leverage any methods available in the RPC.

import { SuiJsonRpcClient } from '@mysten/sui/jsonRpc';

const client = new SuiJsonRpcClient({
	url: 'https://fullnode.devnet.sui.io:443',
	network: 'devnet',
});
// asynchronously call suix_getCommitteeInfo
const committeeInfo = await client.call('suix_getCommitteeInfo', []);

For a full list of available RPC methods, see the RPC documentation.

Customizing the transport

The SuiJsonRpcClient uses a transport to manage connections to the RPC node. By default it creates a JsonRpcHTTPTransport for HTTP JSON-RPC requests. You can construct a custom transport instance if you need to pass options such as headers or a custom fetch implementation.

import { SuiJsonRpcClient, JsonRpcHTTPTransport } from '@mysten/sui/jsonRpc';

const client = new SuiJsonRpcClient({
	network: 'devnet',
	transport: new JsonRpcHTTPTransport({
		url: 'https://fullnode.devnet.sui.io:443',
		rpc: {
			headers: {
				'x-custom-header': 'custom value',
			},
		},
	}),
});

Pagination

SuiJsonRpcClient exposes a number of RPC methods that return paginated results. These methods return a result object with 3 fields:

• data: The list of results for the current page
• nextCursor: A cursor pointing to the next page of results
• hasNextPage: A boolean indicating whether there are more pages of results

Some APIs also accept an order option that can be set to either ascending or descending to change the order in which the results are returned.

You can pass the nextCursor to the cursor option of the RPC method to retrieve the next page, along with a limit to specify the page size:

const page1 = await client.getCheckpoints({
	descendingOrder: false,
	limit: 10,
});

const page2 =
	page1.hasNextPage &&
	(await client.getCheckpoints({
		descendingOrder: false,
		cursor: page1.nextCursor,
		limit: 10,
	}));

Methods

In addition to the RPC methods mentioned above, SuiJsonRpcClient also exposes some methods for working with Transactions.

executeTransactionBlock

const tx = new Transaction();

// add transaction data to tx...

const { bytes, signature } = await tx.sign({ client, signer: keypair });

const result = await client.executeTransactionBlock({
	transactionBlock: bytes,
	signature,
	options: {
		showEffects: true,
	},
});

Arguments

• transactionBlock: BCS serialized transaction data bytes as a Uint8Array or base64-encoded string.
• signature: A signature, or list of signatures committed to the intent message of the transaction data, as a base-64 encoded string.
• options:
  • showBalanceChanges: Whether to show balance_changes. Default to be False
  • showEffects: Whether to show transaction effects. Default to be False
  • showEvents: Whether to show transaction events. Default to be False
  • showInput: Whether to show transaction input data. Default to be False
  • showObjectChanges: Whether to show object_changes. Default to be False
  • showRawInput: Whether to show bcs-encoded transaction input data

signAndExecuteTransaction

const tx = new Transaction();

// add transaction data to tx...

const result = await client.signAndExecuteTransaction({
	transaction: tx,
	signer: keypair,
	options: {
		showEffects: true,
	},
});

// IMPORTANT: Always check the transaction status
if (result.effects?.status.status === 'failure') {
	throw new Error(`Transaction failed: ${result.effects.status.error}`);
}

Arguments

• transaction: A Transaction or BCS serialized transaction data bytes as a Uint8Array.
• signer: A Keypair instance to sign the transaction
• options:
  • showBalanceChanges: Whether to show balance_changes. Default to be False
  • showEffects: Whether to show transaction effects. Default to be False
  • showEvents: Whether to show transaction events. Default to be False
  • showInput: Whether to show transaction input data. Default to be False
  • showObjectChanges: Whether to show object_changes. Default to be False
  • showRawInput: Whether to show bcs-encoded transaction input data

waitForTransaction

Wait for a transaction result to be available over the API. This can be used in conjunction with signAndExecuteTransaction to wait for the transaction to be available through the API. This currently polls the getTransactionBlock API to check for the transaction.

const tx = new Transaction();

const result = await client.signAndExecuteTransaction({
	transaction: tx,
	signer: keypair,
	options: {
		showEffects: true,
	},
});

// Check transaction status
if (result.effects?.status.status === 'failure') {
	throw new Error(`Transaction failed: ${result.effects.status.error}`);
}

const transaction = await client.waitForTransaction({
	digest: result.digest,
	options: {
		showEffects: true,
	},
});

Arguments

• digest: the digest of the queried transaction
• signal: An optional abort signal that can be used to cancel the request
• timeout: The amount of time to wait for a transaction. Defaults to one minute.
• pollInterval: The amount of time to wait between checks for the transaction. Defaults to 2 seconds.
• options:
  • showBalanceChanges: Whether to show balance_changes. Default to be False
  • showEffects: Whether to show transaction effects. Default to be False
  • showEvents: Whether to show transaction events. Default to be False
  • showInput: Whether to show transaction input data. Default to be False
  • showObjectChanges: Whether to show object_changes. Default to be False
  • showRawInput: Whether to show bcs-encoded transaction input data