Sui TypeScript SDK

The Sui TypeScript SDK is a modular library of tools for interacting with the Sui blockchain. Use it to send queries to RPC nodes, build and sign transactions, and interact with a Sui or local network.

Installation

npm i @mysten/sui

The SDK is published as an ESM only package. Make sure your package.json includes "type": "module":

{
	"type": "module"
}

If you are using TypeScript, your tsconfig.json should use a compatible moduleResolution setting such as "NodeNext", "Node16", or "Bundler".

Module packages

The SDK contains a set of modular packages that you can use independently or together. Import just what you need to keep your code light and compact.

• @mysten/sui/client: A client for interacting with Sui RPC nodes.
• @mysten/sui/bcs: A BCS builder with pre-defined types for Sui.
• @mysten/sui/transactions: Utilities for building and interacting with transactions.
• @mysten/sui/keypairs/*: Modular exports for specific KeyPair implementations.
• @mysten/sui/verify: Methods for verifying transactions and messages.
• @mysten/sui/cryptography: Shared types and classes for cryptography.
• @mysten/sui/multisig: Utilities for working with multisig signatures.
• @mysten/sui/utils: Utilities for formatting and parsing various Sui types.
• @mysten/sui/faucet: Methods for requesting SUI from a faucet.
• @mysten/sui/zklogin: Utilities for working with zkLogin.

Network locations

The following table lists the locations for Sui networks.

Quick start

Get started in a few minutes. This guide walks you through creating a keypair, funding it from a faucet, and checking your balance.

Create a project

mkdir hello-sui
cd hello-sui
npm init -y
npm pkg set type=module
npm i @mysten/sui

Step 1: Create a keypair and get SUI

Create a setup.ts file that generates a new keypair, requests SUI from the faucet, and prints your secret key for later use:

import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519';
import { getFaucetHost, requestSuiFromFaucetV3 } from '@mysten/sui/faucet';

// Generate a new keypair
const keypair = new Ed25519Keypair();

console.log('Address:', keypair.toSuiAddress());
console.log('Secret key:', keypair.getSecretKey());

// Request SUI from the devnet faucet
await requestSuiFromFaucetV3({
	host: getFaucetHost('devnet'),
	recipient: keypair.toSuiAddress(),
});

console.log('Faucet request sent! Save the secret key above for the next step.');

Run it:

node setup.ts

Save the secret key that gets printed; you'll use it in the next step.

Step 2: Check your balance

Create a balance.ts file that imports your keypair from the secret key and checks the balance:

import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519';
import { SuiGrpcClient } from '@mysten/sui/grpc';
import { MIST_PER_SUI } from '@mysten/sui/utils';

// Import the keypair using the secret key from step 1
const keypair = Ed25519Keypair.fromSecretKey('suiprivkey1...'); // paste your secret key here

const grpcClient = new SuiGrpcClient({
	network: 'devnet',
	baseUrl: 'https://fullnode.devnet.sui.io:443',
});

const { balance } = await grpcClient.getBalance({
	owner: keypair.toSuiAddress(),
});

const sui = Number(balance.balance) / Number(MIST_PER_SUI);
console.log(`Address: ${keypair.toSuiAddress()}`);
console.log(`Balance: ${sui} SUI`);

Run it:

node balance.ts

Step 3: Transfer SUI

Create a transfer.ts file that sends SUI to another address and logs the transaction effects:

import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519';
import { SuiGrpcClient } from '@mysten/sui/grpc';
import { coinWithBalance, Transaction } from '@mysten/sui/transactions';
import { MIST_PER_SUI } from '@mysten/sui/utils';

const keypair = Ed25519Keypair.fromSecretKey('suiprivkey1...'); // paste your secret key here
const grpcClient = new SuiGrpcClient({
	network: 'devnet',
	baseUrl: 'https://fullnode.devnet.sui.io:443',
});

const tx = new Transaction();

tx.transferObjects(
	[coinWithBalance({ balance: BigInt(0.1 * Number(MIST_PER_SUI)) })],
	'0xRecipientAddress', // replace with the recipient's address
);

const result = await keypair.signAndExecuteTransaction({
	transaction: tx,
	client: grpcClient,
	include: { effects: true, balanceChanges: true },
});

if (result.$kind === 'FailedTransaction') {
	console.error('Transaction failed:', result.FailedTransaction.status.error?.message);
} else {
	console.log('Transaction digest:', result.Transaction.digest);
	console.log('Effects:', JSON.stringify(result.Transaction.effects, null, 2));
	console.log('Balance changes:', JSON.stringify(result.Transaction.balanceChanges, null, 2));
}

Run it:

node transfer.ts

Faucet

Use requestSuiFromFaucetV3 on Devnet and Testnet. It fetches a challenge from /v3/challenge, computes Argon2d proof-of-work, and submits the proof to /v3/gas:

import { getFaucetHost, requestSuiFromFaucetV3 } from '@mysten/sui/faucet';

const result = await requestSuiFromFaucetV3({
	host: getFaucetHost('testnet'),
	recipient: '0xYourAddress', // Replace with your Sui address.
	timeout: 180_000,
});

console.log(result.digest, result.amountMist);

V3 credits the recipient's address balance, not a coin object. Its response contains digest, recipient, amountMist, and difficulty; it does not contain V2's coins_sent. Amounts are returned as decimal strings to preserve precision. The faucet sets the payout amount.

Set host to the faucet's origin (scheme, hostname, and optional port), such as https://faucet.testnet.sui.io. The API must serve /v3/challenge and /v3/gas at the origin root. Path prefixes such as /faucet are not supported; any path in host is discarded.

Optional headers apply to both requests. The timeout covers fetching, solving, and submission, and defaults to 180,000 milliseconds. Pass an AbortSignal as signal to cancel earlier.

The helper uses Node's asynchronous native Argon2d when available (Node 24.7 or newer), with Noble as the fallback for Node 22 and browsers. Native hashing does not require an addon. Browser apps can run the helper in a Web Worker to keep proof-of-work off the UI thread.

For a local no-PoW faucet, keep using V2:

import { getFaucetHost, requestSuiFromFaucetV2 } from '@mysten/sui/faucet';

await requestSuiFromFaucetV2({
	host: getFaucetHost('localnet'),
	recipient: '0xYourAddress', // Replace with your Sui address.
});

For a local PoW faucet, use requestSuiFromFaucetV3 and set host to its origin, with /v3/challenge and /v3/gas served at the origin root. If it listens on the default local faucet port, use getFaucetHost('localnet'). The helper does not infer the protocol from the host or fall back to V2.

V3 refreshes expired challenges before submission but never automatically retries a payout. HTTP 429 throws FaucetRateLimitError. Other HTTP errors throw FaucetError, which exposes status and, when provided by the server, code and a transaction digest. Non-JSON error responses use a fallback message and preserve the parse error as cause. If a digest is present, resolve that transaction before requesting another payout. A timeout or connection loss during submission does not prove the payout failed; do not blindly retry it.

Next steps

• Building Transactions: create and compose transactions
• Signing and Execution: sign and submit transactions
• Coins and Balances: work with tokens
• Client Setup: configure clients for different networks