Pular para o conteúdo principal

Sui TypeScript SDK

This is the Sui TypeScript SDK built on the Sui JSON RPC API. It provides utility classes and functions for applications to sign transactions and interact with the Sui network.

WARNING: Note that we are still iterating on the RPC and SDK API before TestNet, therefore please expect frequent breaking changes in the short-term. We expect the API to stabilize after the upcoming TestNet launch.

Current version: 1.37.6

Working with DevNet​

The SDK will be published to npm registry with the same bi-weekly release cycle as the DevNet validators and RPC Server. To use the SDK in your project, you can do:

npm install @mysten/sui

You can also use your preferred npm client, such as yarn or pnpm.

Working with local network​

Note that the latest tag for the published SDK might go out of sync with the RPC server on the main branch until the next release. If you're developing against a local network, we recommend using the experimental-tagged packages, which contain the latest changes from main.

npm install @mysten/sui@experimental

Refer to the JSON RPC topic for instructions about how to start a local network and local RPC server.

Connecting to Sui Network​

The JsonRpcProvider class provides a connection to the JSON-RPC Server and should be used for all read-only operations. The default URLs to connect with the RPC server are:

Don't have an access key? Create one at https://BlockEden.xyz/dash/.

import { SuiClient, getFullnodeUrl } from '@mysten/sui/client';
// connect to Testnet
const suiClient = new SuiClient({ url: getFullnodeUrl('testnet') });
// get tokens from the Testnet faucet server
import { getFaucetHost, requestSuiFromFaucetV0 } from '@mysten/sui/faucet';
await requestSuiFromFaucetV0({
	host: getFaucetHost('testnet'),
	recipient: '0xcc2bd176a478baea9a0de7a24cd927661cc6e860d5bacecb9a138ef20dbab231',
});

For local development, you can run cargo run --bin sui-test-validator to spin up a local network with a local validator, a fullnode, and a faucet server. Refer to this guide for more information.

import { SuiClient, getFullnodeUrl } from '@mysten/sui/client';
import { getFaucetHost, requestSuiFromFaucetV0 } from '@mysten/sui/faucet';
// connect to local RPC server
const suiClient = new SuiClient({ url: getFullnodeUrl('localnet') });
// get tokens from the local faucet server
await requestSuiFromFaucetV0({
	host: getFaucetHost('localnet'),
	recipient: '0xcc2bd176a478baea9a0de7a24cd927661cc6e860d5bacecb9a138ef20dbab231',
});

You can also construct your own in custom connections, with your own URLs to your fullnode and faucet server

import { SuiClient } from '@mysten/sui/client';
import { requestSuiFromFaucetV0 } from '@mysten/sui/faucet';
// connect to a custom RPC server
const suiClient = new SuiClient({ url: 'https://fullnode.testnet.sui.io' });
// get tokens from a custom faucet server
await requestSuiFromFaucetV0({
	host: 'https://faucet.testnet.sui.io/gas',
	recipient: '0xcc2bd176a478baea9a0de7a24cd927661cc6e860d5bacecb9a138ef20dbab231',
});

Writing APIs​

For a primer for building transactions, refer to this guide.

Transfer Object​

import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519';
import { SuiClient, getFullnodeUrl } from '@mysten/sui/client';
import { Transaction } from '@mysten/sui/transactions';
// Generate a new Ed25519 Keypair
const keypair = new Ed25519Keypair();
const client = new SuiClient({ url: getFullnodeUrl('mainnet') });
const tx = new Transaction();
tx.transferObjects(
	[tx.object('0xe19739da1a701eadc21683c5b127e62b553e833e8a15a4f292f4f48b4afea3f2')],
	tx.pure.address('0x1d20dcdb2bca4f508ea9613994683eb4e76e9c4ed371169677c1be02aaf0b12a'),
);
const result = await client.signAndExecuteTransaction({
	transaction: tx,
	signer: keypair,
});
console.log({ result });

Transfer Sui​

To transfer 1000 MIST to another address:

import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519';
import { SuiClient, getFullnodeUrl } from '@mysten/sui/client';
import { Transaction } from '@mysten/sui/transactions';
// Generate a new Keypair
const keypair = new Ed25519Keypair();
const client = new SuiClient({ url: getFullnodeUrl('mainnet') });
const tx = new Transaction();
const [coin] = tx.splitCoins(tx.gas, [1000]);
tx.transferObjects([coin], keypair.toSuiAddress());
const result = await client.signAndExecuteTransaction({
	transaction: tx,
	signer: keypair,
});
console.log({ result });

Merge coins​

import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519';
import { SuiClient, getFullnodeUrl } from '@mysten/sui/client';
import { Transaction } from '@mysten/sui/transactions';
// Generate a new Keypair
const keypair = new Ed25519Keypair();
const client = new SuiClient({ url: getFullnodeUrl('mainnet') });
const tx = new Transaction();
tx.mergeCoins(tx.object('0xe19739da1a701eadc21683c5b127e62b553e833e8a15a4f292f4f48b4afea3f2'), [
	tx.object('0x127a8975134a4824d9288722c4ee4fc824cd22502ab4ad9f6617f3ba19229c1b'),
]);
const result = await client.signAndExecuteTransaction({
	transaction: tx,
	signer: keypair,
});
console.log({ result });

Move Call​

import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519';
import { SuiClient, getFullnodeUrl } from '@mysten/sui/client';
import { Transaction } from '@mysten/sui/transactions';
// Generate a new Keypair
const keypair = new Ed25519Keypair();
const client = new SuiClient({ url: getFullnodeUrl('mainnet') });
const packageObjectId = '0x...';
const tx = new Transaction();
tx.moveCall({
	target: `${packageObjectId}::nft::mint`,
	arguments: [tx.pure.string('Example NFT')],
});
const result = await client.signAndExecuteTransaction({
	transaction: tx,
	signer: keypair,
});
console.log({ result });

Publish Modules​

To publish a package:

import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519';
import { SuiClient, getFullnodeUrl } from '@mysten/sui/client';
import { Transaction } from '@mysten/sui/transactions';
const { execSync } = require('child_process');
// Generate a new Keypair
const keypair = new Ed25519Keypair();
const client = new SuiClient({ url: getFullnodeUrl('mainnet') });
const { modules, dependencies } = JSON.parse(
	execSync(`${cliPath} move build --dump-bytecode-as-base64 --path ${packagePath}`, {
		encoding: 'utf-8',
	}),
);
const tx = new Transaction();
const [upgradeCap] = tx.publish({
	modules,
	dependencies,
});
tx.transferObjects([upgradeCap], keypair.toSuiAddress());
const result = await client.signAndExecuteTransaction({
	transaction: tx,
	signer: keypair,
});
console.log({ result });

Reading APIs​

Get Owned Objects​

Fetch objects owned by the address 0xcc2bd176a478baea9a0de7a24cd927661cc6e860d5bacecb9a138ef20dbab231

import { SuiClient, getFullnodeUrl } from '@mysten/sui/client';
const client = new SuiClient({ url: getFullnodeUrl('mainnet') });
const objects = await client.getOwnedObjects({
	owner: '0xcc2bd176a478baea9a0de7a24cd927661cc6e860d5bacecb9a138ef20dbab231',
});

Get Object​

Fetch object details for the object with id 0xe19739da1a701eadc21683c5b127e62b553e833e8a15a4f292f4f48b4afea3f2

import { SuiClient, getFullnodeUrl } from '@mysten/sui/client';
const client = new SuiClient({ url: getFullnodeUrl('mainnet') });
const txn = await client.getObject({
	id: '0xcc2bd176a478baea9a0de7a24cd927661cc6e860d5bacecb9a138ef20dbab231',
	// fetch the object content field
	options: { showContent: true },
});
// You can also fetch multiple objects in one batch request
const txns = await client.multiGetObjects({
	ids: [
		'0xcc2bd176a478baea9a0de7a24cd927661cc6e860d5bacecb9a138ef20dbab231',
		'0x9ad3de788483877fe348aef7f6ba3e52b9cfee5f52de0694d36b16a6b50c1429',
	],
	// only fetch the object type
	options: { showType: true },
});

Get Transaction​

Fetch transaction details from transaction digests:

import { SuiClient, getFullnodeUrl } from '@mysten/sui/client';
const client = new SuiClient({ url: getFullnodeUrl('mainnet') });
const txn = await client.getTransactionBlock({
	digest: '9XFneskU8tW7UxQf7tE5qFRfcN4FadtC2Z3HAZkgeETd=',
	// only fetch the effects field
	options: {
		showEffects: true,
		showInput: false,
		showEvents: false,
		showObjectChanges: false,
		showBalanceChanges: false,
	},
});

// You can also fetch multiple transactions in one batch request
const txns = await client.multiGetTransactionBlocks({
	digests: [
		'9XFneskU8tW7UxQf7tE5qFRfcN4FadtC2Z3HAZkgeETd=',
		'17mn5W1CczLwitHCO9OIUbqirNrQ0cuKdyxaNe16SAME=',
	],
	// fetch both the input transaction data as well as effects
	options: { showInput: true, showEffects: true },
});

Get Checkpoints​

Get latest 100 Checkpoints in descending order and print Transaction Digests for each one of them.

client.getCheckpoints({ descendingOrder: true }).then(function (checkpointPage: CheckpointPage) {
	console.log(checkpointPage);

	checkpointPage.data.forEach((checkpoint) => {
		console.log('---------------------------------------------------------------');
		console.log(
			' -----------   Transactions for Checkpoint:  ',
			checkpoint.sequenceNumber,
			' -------- ',
		);
		console.log('---------------------------------------------------------------');
		checkpoint.transactions.forEach((tx) => {
			console.log(tx);
		});
		console.log('***************************************************************');
	});
});

Get Checkpoint 1994010 and print details.

client.getCheckpoint({ id: '1994010' }).then(function (checkpoint: Checkpoint) {
	console.log('Checkpoint Sequence Num ', checkpoint.sequenceNumber);
	console.log('Checkpoint timestampMs ', checkpoint.timestampMs);
	console.log('Checkpoint # of Transactions ', checkpoint.transactions.length);
});

Get Coins​

Fetch coins of type 0x65b0553a591d7b13376e03a408e112c706dc0909a79080c810b93b06f922c458::usdc::USDC owned by an address:

import { SuiClient, getFullnodeUrl } from '@mysten/sui/client';
const client = new SuiClient({ url: getFullnodeUrl('mainnet') });
// If coin type is not specified, it defaults to 0x2::sui::SUI
const coins = await client.getCoins({
	owner: '0xcc2bd176a478baea9a0de7a24cd927661cc6e860d5bacecb9a138ef20dbab231',
	coinType: '0x65b0553a591d7b13376e03a408e112c706dc0909a79080c810b93b06f922c458::usdc::USDC',
});

Fetch all coin objects owned by an address:

import { SuiClient, getFullnodeUrl } from '@mysten/sui/client';
const client = new SuiClient({ url: getFullnodeUrl('mainnet') });
const allCoins = await client.getAllCoins({
	owner: '0xcc2bd176a478baea9a0de7a24cd927661cc6e860d5bacecb9a138ef20dbab231',
});

Fetch the total coin balance for one coin type, owned by an address:

import { SuiClient, getFullnodeUrl } from '@mysten/sui/client';
const client = new SuiClient({ url: getFullnodeUrl('mainnet') });
// If coin type is not specified, it defaults to 0x2::sui::SUI
const coinBalance = await client.getBalance({
	owner: '0xcc2bd176a478baea9a0de7a24cd927661cc6e860d5bacecb9a138ef20dbab231',
	coinType: '0x65b0553a591d7b13376e03a408e112c706dc0909a79080c810b93b06f922c458::usdc::USDC',
});

Events API​

Querying events created by transactions sent by account 0xcc2bd176a478baea9a0de7a24cd927661cc6e860d5bacecb9a138ef20dbab231

import { SuiClient, getFullnodeUrl } from '@mysten/sui/client';
const client = new SuiClient({ url: getFullnodeUrl('mainnet') });
const events = client.queryEvents({
	query: { Sender: toolbox.address() },
	limit: 2,
});

Subscribe to all events created by transactions sent by account 0xcc2bd176a478baea9a0de7a24cd927661cc6e860d5bacecb9a138ef20dbab231

import { SuiClient, getFullnodeUrl } from '@mysten/sui/client';
const client = new SuiClient({ url: getFullnodeUrl('mainnet') });

// Note: Event subscriptions are deprecated in the current SDK
// Use queryEvents with polling for real-time event monitoring
const events = await client.queryEvents({
	query: {
		Sender: '0xcc2bd176a478baea9a0de7a24cd927661cc6e860d5bacecb9a138ef20dbab231',
	},
	limit: 50,
	order: 'descending',
});

Subscribe to all events created by a package's nft module

import { SuiClient, getFullnodeUrl } from '@mysten/sui/client';
const client = new SuiClient({ url: getFullnodeUrl('mainnet') });

const somePackage = '0x...';
// Note: Event subscriptions are deprecated, use queryEvents instead
const nftEvents = await client.queryEvents({
	query: {
		MoveModule: { package: somePackage, module: 'nft' },
	},
	limit: 50,
	order: 'descending',
});
Share on Twitter