sui-ts-sdk

name	sui-ts-sdk
description	Use when writing TypeScript code interacting with SUI blockchain via @mysten/sui SDK. Covers PTB construction, client setup, transaction execution, and on-chain queries. Triggers on backend scripts, CLI tools, serverless functions, or any non-React TS SDK usage. For frontend-specific setup (dApp Kit, wallet adapters, React hooks), use sui-frontend skill alongside this one.

Sui TypeScript SDK Skill

SDK Versions

Targets: @mysten/sui 2.22.0 (^2.0). Tested: 2026-07-18.

Compatibility notes: Sui 2.x removed SuiClient from @mysten/sui/client, @mysten/sui/cryptography/hash, and event pub/sub (subscribeEvent has no v2 equivalent — use an indexer or the gRPC checkpoint stream). If your install is on 1.x, stop and either upgrade or follow the 1.x patterns in your installed package's README — do not mix.

---

You are writing TypeScript code that interacts with the Sui blockchain using the @mysten/sui SDK (v2+). Follow these rules precisely. This skill covers PTB (Programmable Transaction Block) construction, client setup, transaction execution, and on-chain queries. These patterns apply equally in backend scripts and frontend apps. If you are building a frontend, use the sui-frontend skill first (or alongside this one) for dApp Kit setup, wallet connection, and React integration — then apply the PTB and client patterns from this skill.

---

1. Package & Imports

The SDK package is @mysten/sui. The old package name @mysten/sui.js was renamed at v1.0 and must not be used.

# correct
npm install @mysten/sui

# deprecated package name — will not receive updates
npm install @mysten/sui.js

All imports use subpath exports from @mysten/sui:

// @check:skip — contrasts correct vs deliberately-wrong imports
// correct subpath imports
import { Transaction } from '@mysten/sui/transactions';
import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519';
import { SuiGrpcClient } from '@mysten/sui/grpc';

import { TransactionBlock } from '@mysten/sui.js'; // wrong: old package name (deprecated, removed at v1.0)
import { Transaction } from '@mysten/sui'; // wrong: no root export — import from a subpath like @mysten/sui/transactions

ESM-only (v2+): Set "type": "module" in package.json and update tsconfig.json:

{ "compilerOptions": { "moduleResolution": "NodeNext", "module": "NodeNext" } }

---

2. Client Setup

The SDK provides three client types. Use SuiGrpcClient for new code — it is the recommended client with the best performance. The JSON-RPC API is deprecated (permanent deactivation: 2026-07-31; public endpoints shutting down July 2026). Since sui 2.20.4 every JSON-RPC client/transport API and JSON-RPC-specific type is marked @deprecated in the SDK — expect strikethrough in editors and deprecation lint warnings.

// Recommended — gRPC client (best performance, type-safe protobuf)
import { SuiGrpcClient } from '@mysten/sui/grpc';

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

For legacy JSON-RPC, GraphQL clients, and gRPC service clients, see references/advanced-patterns.md.

Network URLs

Network	gRPC base URL
Mainnet	https://fullnode.mainnet.sui.io:443
Testnet	https://fullnode.testnet.sui.io:443
Devnet	https://fullnode.devnet.sui.io:443

---

3. Transaction Construction

A Programmable Transaction Block (PTB) is built using the Transaction class. The class was renamed from TransactionBlock at v1.0:

// @check:skip — contrasts correct vs deliberately-wrong class name
// correct
import { Transaction } from '@mysten/sui/transactions';
const tx = new Transaction();

import { TransactionBlock } from '@mysten/sui.js/transactions'; // wrong: old class name, deprecated pre-1.0
const txb = new TransactionBlock();

Cloning a transaction

// @check:skip
// v1.0+
const newTx = Transaction.from(existingTx);

// wrong: old constructor-based cloning
const newTx = new TransactionBlock(existingTx);

Serialization

// @check:skip
// v1.0+ — async, runs serialization plugins
const json = await tx.toJSON();

// Deserialize
const restored = Transaction.from(json);

// deprecated
const bytes = tx.serialize();

---

4. Pure Value Inputs

Use tx.pure.<type>() helpers for non-object inputs. These handle BCS serialization automatically. Never manually BCS-encode values when a tx.pure helper exists.

// @check:skip
// Typed pure helpers
tx.pure.u8(255);
tx.pure.u16(65535);
tx.pure.u32(4294967295);
tx.pure.u64(1000000n);              // accepts bigint or number
tx.pure.u128(1000000n);
tx.pure.u256(1000000n);
tx.pure.bool(true);
tx.pure.string('hello');
tx.pure.address('0xSomeAddress');
tx.pure.id('0xSomeObjectId');       // equivalent to address, for object IDs as values

// Vectors
tx.pure.vector('u64', [100n, 200n, 300n]);
tx.pure.vector('address', [addr1, addr2]);
tx.pure.vector('bool', [true, false]);

// Option
tx.pure.option('u64', 42n);         // Some(42)
tx.pure.option('u64', null);        // None

// @check:skip
// don't manually construct BCS for types that have helpers
import { bcs } from '@mysten/sui/bcs';
tx.pure(bcs.U64.serialize(100));    // unnecessary — use tx.pure.u64(100)

For advanced types without a built-in helper, fall back to tx.pure(bcsBytes) where bcsBytes is a Uint8Array:

// @check:skip
import { bcs } from '@mysten/sui/bcs';

const MyStruct = bcs.struct('MyStruct', {
  id: bcs.Address,
  value: bcs.U64,
});
tx.pure(MyStruct.serialize({ id: '0x...', value: 100n }));

---

5. Object Inputs

Use tx.object(id) for object inputs. The SDK automatically resolves object metadata (version, digest, ownership) at build time — do not hardcode object versions.

// @check:skip
// Let the SDK resolve object details
tx.object('0xSomeObjectId');

// Well-known system object shortcuts
tx.object.system();    // 0x5 — Sui system state
tx.object.clock();     // 0x6 — Clock
tx.object.random();    // 0x8 — Random
tx.object.denyList();  // 0x403 — DenyList

// Construct an Option<Object> input
tx.object.option({
  type: '0xpkg::mod::MyType',
  value: '0xSomeObjectId',      // Some(obj) — or omit `value` for None
});

// @check:skip
// don't hardcode object versions
tx.object(Inputs.ObjectRef({
  objectId: '0x...',
  version: '42',     // will break when object is modified
  digest: 'abc...',
}));
// Exception: offline building (see references/advanced-patterns.md § Offline Building)

Receiving objects

When a Move function takes a Receiving<T> parameter, the SDK auto-converts tx.object() to a receiving reference. No special handling is needed — just pass the object ID normally.

---

6. Built-in Commands

splitCoins

Creates new coins by splitting from a source coin. Returns an array of coin references:

// @check:skip
// Split from gas coin — most common pattern for SUI
const [coin] = tx.splitCoins(tx.gas, [1000]);

// Split multiple amounts
const [coin1, coin2] = tx.splitCoins(tx.gas, [1000, 2000]);

// Split from a non-gas coin
const [portion] = tx.splitCoins(tx.object('0xMyCoin'), [500]);

mergeCoins

Merges coins into a destination coin:

// @check:skip
tx.mergeCoins(tx.object('0xDestCoin'), [
  tx.object('0xCoinA'),
  tx.object('0xCoinB'),
]);

transferObjects

Transfers one or more objects to a recipient address:

// @check:skip
// Transfer a split coin
const [coin] = tx.splitCoins(tx.gas, [1000]);
tx.transferObjects([coin], '0xRecipientAddress');

// Transfer existing objects
tx.transferObjects(
  [tx.object('0xObj1'), tx.object('0xObj2')],
  '0xRecipientAddress',
);

// Transfer the entire gas coin (send all SUI to someone)
tx.transferObjects([tx.gas], '0xRecipientAddress');

moveCall

Calls a Move function:

// @check:skip
tx.moveCall({
  target: '0xPackageId::module_name::function_name',
  arguments: [
    tx.object('0xSomeObject'),     // object argument
    tx.pure.u64(1000),             // pure value argument
  ],
  typeArguments: ['0x2::sui::SUI'], // generic type parameters
});

Return values from moveCall are usable in subsequent commands:

// @check:skip
const [result] = tx.moveCall({
  target: '0xpkg::amm::swap',
  arguments: [tx.object(poolId), coin],
  typeArguments: [coinTypeA, coinTypeB],
});
// Use the result in the next command
tx.transferObjects([result], myAddress);

makeMoveVec

Constructs a vector<T> of objects for passing into a Move function:

// @check:skip
const vec = tx.makeMoveVec({
  type: '0xpkg::mod::MyType',
  elements: [tx.object('0xA'), tx.object('0xB')],
});
tx.moveCall({
  target: '0xpkg::mod::process_all',
  arguments: [vec],
});

publish

Publishing a Move package from TS is occasional and overlaps the sui-deployer skill. For the tx.publish({ modules, dependencies }) pattern and the sui move build --dump-bytecode-as-base64 step, see references/advanced-patterns.md or the sui-deployer skill.

---

7. Command Result Chaining

Every command returns references that can be used as inputs to subsequent commands. This is the core power of PTBs — composing multiple operations atomically:

// @check:skip
const tx = new Transaction();

// Step 1: Split a coin
const [coin] = tx.splitCoins(tx.gas, [1_000_000]);

// Step 2: Pass the split coin into a Move call
const [receipt] = tx.moveCall({
  target: '0xpkg::shop::buy_item',
  arguments: [tx.object(shopId), coin, tx.pure.string('sword')],
});

// Step 3: Transfer the receipt to the sender
tx.transferObjects([receipt], myAddress);

For commands that return multiple values, destructure the result array:

// @check:skip
const [coinOut, receipt] = tx.moveCall({
  target: '0xpkg::amm::swap',
  arguments: [tx.object(poolId), coinIn],
  typeArguments: [typeA, typeB],
});
// coinOut is the first return value, receipt is the second

For advanced PTB composability (multi-step swap+stake, flash loan hot potato patterns), see references/advanced-patterns.md.

---

8. Gas Coin

tx.gas is a special reference to the gas payment coin:

// @check:skip
// Split from gas coin (by-reference)
const [coin] = tx.splitCoins(tx.gas, [100]);

// Merge into gas coin
tx.mergeCoins(tx.gas, [tx.object('0xOtherCoin')]);

// Transfer the entire gas coin (moves all SUI)
tx.transferObjects([tx.gas], recipient);

// Pass gas coin as a Move call argument (by-reference)
tx.moveCall({
  target: '0xpkg::mod::deposit',
  arguments: [tx.object(vaultId), tx.gas],
});

Gas configuration

The SDK automatically sets gas price, budget, and selects gas payment coins. Override only when needed:

// @check:skip
// Manual overrides (rarely needed)
tx.setGasPrice(1000);
tx.setGasBudget(10_000_000);
tx.setGasPayment([{
  objectId: '0x...',
  version: '1',
  digest: '...',
}]);
// Gas payment coins must not overlap with transaction input objects

// Set sender explicitly (required for some offline or sponsored flows)
tx.setSender('0xSenderAddress');

Address-balance gas + expiration (@mysten/sui ≥2.22.1): when a transaction uses address-balance gas (explicit empty gas payment) and a preset gas budget — i.e. backend gas selection is skipped — with no expiration set, gRPC/GraphQL resolution now auto-sets a ValidDuring expiration from the simulation's effects epoch. Explicitly set expirations — including { None: true } — are preserved, and kind-only resolution / backend gas selection paths (budget or payment unset) are unaffected. On 2.22.0 (this skill's tested pin) no expiration is synthesized.

---

9. Transaction Intents — coinWithBalance

For non-SUI coin types, manually splitting coins is complex because you must find, select, and merge coins of the correct type. The coinWithBalance intent automates this:

// @check:skip
import { coinWithBalance, Transaction } from '@mysten/sui/transactions';

const tx = new Transaction();

// REQUIRED: setSender when using coinWithBalance with non-SUI types
tx.setSender(keypair.toSuiAddress());

tx.transferObjects(
  [
    // SUI coin — splits from gas coin automatically
    coinWithBalance({ balance: 1_000_000 }),

    // Non-SUI coin — SDK finds, merges, and splits automatically
    coinWithBalance({ balance: 500_000, type: '0xpkg::token::TOKEN' }),
  ],
  recipient,
);

Why use coinWithBalance over manual splitCoins?

For SUI, tx.splitCoins(tx.gas, [...]) works fine. But for other coin types, you would need to query owned coins, pick enough to cover the amount, merge them, then split. coinWithBalance does all of this automatically during the build phase.

Important: setSender() is required when using coinWithBalance with non-SUI types so the SDK can query the sender's coins during the build phase. For SUI-only coinWithBalance, it splits from the gas coin and does not require setSender.

---

10. Execution & Status Checking

Sign and execute

// @check:skip
const result = await client.signAndExecuteTransaction({
  signer: keypair,
  transaction: tx,
});

// ALWAYS check for failure — a finalized tx can still fail (Move abort, gas)
if (result.$kind === 'FailedTransaction') {
  throw new Error(
    `Transaction failed: ${result.FailedTransaction.status.error?.message}`,
  );
}

Execution with include options

// @check:skip
const result = await client.core.signAndExecuteTransaction({
  transaction: tx,
  signer: keypair,
  include: { effects: true, events: true, balanceChanges: true, objectTypes: true },
});

On SuiGrpcClient (sui ≥2.22), transaction methods also accept include: { protoJson: true } — the result then carries a protoJson field with the raw protobuf-JSON gRPC response (works on getTransaction, waitForTransaction, executeTransaction, signAndExecuteTransaction, simulateTransaction).

Waiting for indexing

After execution, wait before follow-up queries:

// @check:skip
await client.waitForTransaction({ digest: result.digest });
// Now safe to query updated state

For separate sign + execute, multi-sig, keypairs, offline building, client extensions, v1→v2 migration, and common mistakes, see:

• references/advanced-patterns.md
• references/reference.md - Complete v1-to-v2 API mapping
• references/examples.md - Advanced PTB examples and patterns

For sponsored transactions specifically, see references/ptbs-advanced.md (concept) and references/examples.md §3 (complete code).

---

11. Common Query Patterns

Core API (recommended)

// @check:skip
// Get object
const obj = await client.core.getObject({
  objectId: '0xObjId',
  include: { content: true, owner: true },
});

// List owned objects
const objects = await client.core.listOwnedObjects({ owner: '0xAddress', include: { content: true } });

// List coins / balances
const coins = await client.core.listCoins({ owner: '0xAddress' });
const balances = await client.core.listBalances({ owner: '0xAddress' });

// Get transaction
const txn = await client.core.getTransaction({ digest: 'Digest', include: { effects: true, events: true } });

// Simulate (dry run)
const simResult = await client.core.simulateTransaction({ transaction: txBytes, include: { effects: true } });

// Dynamic fields
const fields = await client.core.listDynamicFields({ parentId: '0xParentObjId' });

All core methods accept an AbortSignal via options.signal. Note: before sui 2.20.4 SuiGrpcClient accepted signal but never forwarded it (requests could not be cancelled); 2.20.4 fixes this, including MVR resolveType/resolvePackage resolution.

gRPC service clients (lower-level)

For the lower-level service clients (ledgerService, transactionExecutionService, movePackageService, etc.), see references/advanced-patterns.md.

Verifying signatures (@mysten/sui/verify, boolean forms sui ≥2.19)

// @check:skip — txBytes/signature/senderAddress come from your app context
import { verifyTransactionSignature, isValidTransactionSignature } from '@mysten/sui/verify';

// Throwing form: returns the PublicKey, throws on invalid signature
const pubkey = await verifyTransactionSignature(txBytes, signature, { address: senderAddress });

// Boolean form (sui ≥2.19): false for malformed/invalid/mismatched-address signatures.
// Environmental failures (e.g. zkLogin JWK/epoch lookup) still throw — a network blip
// is never reported as "invalid signature".
const ok = await isValidTransactionSignature(txBytes, signature, { address: senderAddress });

Siblings: isValidSignature(bytes, sig, { address? }) (no client option) and isValidPersonalMessageSignature(message, sig, { client?, address? }). The verify* functions now delegate to these internally.

---

12. What the Sui TS SDK is NOT

Mistake	Correct approach
import ... from '@mysten/sui.js'	Use @mysten/sui — .js suffix removed at v1.0
new TransactionBlock()	Use new Transaction() — renamed at v1.0
client.signAndExecuteTransactionBlock()	Use client.signAndExecuteTransaction()
Hardcoding object versions in tx.object()	Let SDK resolve automatically (except offline builds)
Manual BCS for basic types	Use tx.pure.u64(), tx.pure.address(), etc.
Not checking result.$kind after execution	Always check for FailedTransaction
Querying state immediately after execution	Use client.waitForTransaction() first
Using SuiClient / getFullnodeUrl	Removed in v2 — use SuiGrpcClient
tx.serialize()	Use await tx.toJSON()

---

Integration

Called By

• sui-full-stack (Phase 2: Development)
• sui-frontend (PTB construction patterns)

Calls

• sui-docs-query - Query latest SDK documentation

References

• references/advanced-patterns.md - Execution, keypairs, offline building, sponsored tx, extensions, v1→v2 migration, common mistakes
• references/reference.md - Complete v1-to-v2 API mapping
• references/examples.md - Advanced PTB examples and patterns

Related @mysten packages (niche / pre-1.0, not yet covered in depth)

• @mysten/payment-kit (PaymentKitClient, paymentKit client $extend() plugin, payment URIs), experimental — structured on-chain payment flows. Reach for it instead of hand-rolling coin transfers when you need payment-request semantics.
• @mysten/pas (PASClient) — Permissioned Assets Standard; regulated/compliance-gated asset transfers. Niche.

See Also

• ptbs-advanced.md — Read when building a sponsored transaction, reading pruned/archival history, or mapping a use-case to the right client API