> For the complete documentation index, see [llms.txt](/llms.txt) # Commands and Inputs Reference Complete reference for transaction commands and input types A [programmable transaction block](https://docs.sui.io/guides/developer/transactions/prog-txn-blocks) has two parts: **inputs** (objects and pure values) and **commands** (operations that execute on those inputs). This page is a complete reference for all input types and commands available in the SDK. For task-oriented guides, see [Building Transactions](./basics). See also the [Sui documentation on PTB commands](https://docs.sui.io/references/ptb-commands) and [inputs and results](https://docs.sui.io/concepts/transactions/inputs-and-results). ## Passing inputs ### Object references Commands that accept objects (like `splitCoins`, `mergeCoins`, `transferObjects`, and `moveCall`) accept any of the following as an object reference: * **String object ID**:`'0xObjectId'`, SDK looks up version and digest at build time * **`tx.object('0xObjectId')`**: Equivalent to a string ID, but explicit * **`tx.objectRef({...})`**: Fully-resolved owned or immutable object (no lookup needed) * **`tx.sharedObjectRef({...})`**: Fully-resolved shared object (no lookup needed) * **`tx.receivingRef({...})`**: Fully-resolved receiving object (no lookup needed) * **Transaction result**: The return value of a previous command (for example, from `splitCoins`) * **`tx.coin({...})`** or **`coinWithBalance({...})`**: A coin intent resolved at build time * **`tx.gas`**: The gas coin (when gas is paid from coin objects) ### JavaScript value shortcuts For arguments where the expected type is known, you can pass plain JavaScript values. The SDK coerces them to the correct Move type automatically. ```typescript // amounts in splitCoins are coerced to u64 tx.splitCoins(tx.gas, [100, 200]); // addresses in transferObjects are coerced to address tx.transferObjects([coin], '0xRecipientAddress'); ``` ### Pure values For Move primitive types, use `tx.pure` to serialize values as BCS: ```typescript tx.pure.u8(255); tx.pure.u16(65535); tx.pure.u32(4294967295); tx.pure.u64(100); tx.pure.u128(100n); tx.pure.u256(100n); tx.pure.bool(true); tx.pure.string('hello'); tx.pure.address('0xSomeAddress'); tx.pure.id('0xSomeObjectId'); ``` ### Vectors and options ```typescript // Using type-specific methods tx.pure.vector('u8', [1, 2, 3]); tx.pure.option('u8', 1); tx.pure.option('u8', null); // None // Using type string syntax tx.pure('vector', [1, 2, 3]); tx.pure('option', 1); tx.pure('option', null); tx.pure('vector>', [1, null, 2]); ``` ### BCS serialization For complex types, use the BCS library directly: ```typescript import { bcs } from '@mysten/sui/bcs'; tx.pure(bcs.vector(bcs.U8).serialize([1, 2, 3])); tx.pure(bcs.option(bcs.U8).serialize(1)); tx.pure(bcs.option(bcs.U8).serialize(null)); ``` ### Address balance withdrawals Address balances are currently only available on Devnet and Testnet. They are not yet supported on Mainnet. Use `tx.withdrawal()` to create an input that withdraws from your address balance: ```typescript // Withdraw SUI const withdrawal = tx.withdrawal({ amount: 1_000_000_000 }); // Withdraw another coin type const withdrawal = tx.withdrawal({ amount: 1_000_000, type: '0xPackageId::module::CoinType' }); ``` See [Coins and Balances](./coins-and-balances#withdrawing-from-address-balance) for usage examples. ### The gas coin `tx.gas` references the coin used for gas payment. It can be used as an input to commands: ```typescript const [coin] = tx.splitCoins(tx.gas, [1_000_000_000]); ``` `tx.gas` is not available when gas is paid from address balances. Use `tx.coin()` instead for portable code. ## Object inputs Objects on Sui have different [ownership types](https://docs.sui.io/guides/developer/objects/object-ownership), including address-owned, shared, immutable, and object-owned (receiving). Each type requires different metadata when used as a transaction input, but the SDK handles most of this automatically. ### tx.object(id) The simplest way to reference an onchain object. The SDK automatically looks up the object's version, digest, and type when the transaction is built: ```typescript tx.moveCall({ target: '0xPackage::module::function', arguments: [tx.object('0xSomeObjectId')], }); ``` Object IDs can also be passed directly to commands that only accept objects: ```typescript tx.transferObjects(['0xObjectId1', '0xObjectId2'], '0xRecipient'); ``` When a Move function expects a `Receiving` argument, `tx.object()` automatically converts the reference to a receiving input: ```typescript tx.moveCall({ target: '0xPackage::module::receive', // The SDK detects the function signature expects Receiving and adjusts accordingly arguments: [tx.object('0xParentId'), tx.object('0xReceivingObjectId')], }); ``` ### Fully-resolved object references To avoid the SDK's automatic lookup (for [offline building](./offline) or performance), provide the full object metadata directly: ```typescript // Owned or immutable objects — need exact version and digest tx.objectRef({ objectId: '0xObjectId', version: '42', digest: 'abc123...', }); // Shared objects — need initial shared version (stable, doesn't change) tx.sharedObjectRef({ objectId: '0xObjectId', initialSharedVersion: '1', mutable: true, }); // Receiving objects — need exact version and digest tx.receivingRef({ objectId: '0xObjectId', version: '42', digest: 'abc123...', }); ``` ### Shared objects Shared objects are accessible by any transaction and are sequenced through consensus. When using `tx.object()` with a shared object ID, the SDK looks up the required metadata automatically. For offline building or performance, use `tx.sharedObjectRef()` with the `initialSharedVersion` (which is stable and never changes after the object is shared): ```typescript tx.sharedObjectRef({ objectId: '0xSharedObjectId', initialSharedVersion: '1', mutable: true, // false for read-only access }); ``` ### Party objects Party objects are address-owned but consensus-versioned, with per-address permissions (read, write, delete, or transfer). They are referenced the same way as shared objects: ```typescript tx.sharedObjectRef({ objectId: '0xPartyObjectId', initialSharedVersion: '1', mutable: true, }); ``` Key differences from regular owned objects: * **Enable pipelining**: Multiple in-flight transactions on the same object * **No version lookup needed**: `initialSharedVersion` is stable * **Cannot be used for gas payment**: Use address balance for gas instead ### Object helpers Common system objects have shorthand methods. Passing `mutable` skips the SDK's automatic mutability lookup: ```typescript tx.object.system(); // Sui system state (SDK looks up mutability) tx.object.system({ mutable: true }); // Mutable system state (no lookup needed) tx.object.system({ mutable: false }); // Immutable system state (no lookup needed) tx.object.clock(); // On-chain clock (always immutable) tx.object.random(); // Random number generator tx.object.denyList(); // Coin deny list (SDK looks up mutability) tx.object.denyList({ mutable: true }); // Mutable deny list (no lookup needed) ``` `tx.object.option` wraps an object as a Move `Option`. This adds a `moveCall` command to the transaction that constructs the option value: ```typescript // Some — wraps the object in Option::some() tx.object.option({ type: '0xPackage::module::Thing', value: '0xObjectId', }); // None — creates Option::none() tx.object.option({ type: '0xPackage::module::Thing', value: null, }); ``` ## Commands ### `splitCoins` Creates new coins by splitting amounts from an existing coin. Returns one result per amount. ```typescript const [coin1, coin2] = tx.splitCoins(coin, [amount1, amount2]); ``` | Parameter | Type | Description | | --------- | -------------------------------------------------- | ------------------------- | | `coin` | [object reference](#object-references) or `tx.gas` | The coin to split from | | `amounts` | `(number \| bigint \| string)[]` | Amounts for each new coin | ### `mergeCoins` Merges one or more source coins into a destination coin. The source coins are destroyed. ```typescript tx.mergeCoins(destinationCoin, [sourceCoin1, sourceCoin2]); ``` | Parameter | Type | Description | | ------------- | ----------------------------------------- | -------------------------------- | | `destination` | [object reference](#object-references) | The coin to merge into | | `sources` | [object reference](#object-references)\[] | Coins to merge (destroyed after) | ### `transferObjects` Transfers one or more objects to a recipient address. ```typescript tx.transferObjects([obj1, obj2], recipientAddress); ``` | Parameter | Type | Description | | --------- | ----------------------------------------- | ------------------- | | `objects` | [object reference](#object-references)\[] | Objects to transfer | | `address` | `string` | Recipient address | ### `moveCall` Calls a function in a published Move package. Returns whatever the Move function returns. ```typescript const [result] = tx.moveCall({ target: '0xPackage::module::function', arguments: [arg1, arg2], typeArguments: ['0x2::sui::SUI'], }); ``` | Parameter | Type | Description | | --------------- | ---------- | -------------------------------------------------- | | `target` | `string` | `packageId::moduleName::functionName` | | `arguments` | `any[]` | Function arguments (objects, pure values, results) | | `typeArguments` | `string[]` | Move type parameters | You can also pass `package`, `module`, and `function` separately instead of `target`: ```typescript tx.moveCall({ package: '0xPackageId', module: 'my_module', function: 'my_function', arguments: [], typeArguments: [], }); ``` ### `makeMoveVec` Constructs a vector of objects for use in `moveCall`. Required because there's no other way to pass a vector of objects as a transaction input. ```typescript const vec = tx.makeMoveVec({ elements: [obj1, obj2] }); // Pass the vector to a Move function tx.moveCall({ target: '0xPackage::module::process_items', arguments: [vec], }); ``` | Parameter | Type | Description | | ---------- | ----------------------------------------- | -------------------------------- | | `elements` | [object reference](#object-references)\[] | Objects to include in the vector | | `type` | `string` (optional) | Move type of the elements | ### `publish` Publishes a new Move package. Returns the upgrade capability object. ```typescript const [upgradeCap] = tx.publish({ modules, dependencies }); ``` | Parameter | Type | Description | | -------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `modules` | `number[][] \| string[]` | Compiled module bytecodes. Each module as a `number[]` (byte array) or base64-encoded `string`. To convert from `Uint8Array`, use `Array.from(bytes)`. | | `dependencies` | `string[]` | Package IDs of dependencies | ### `upgrade` Upgrades an existing Move package. ```typescript const [upgradeReceipt] = tx.upgrade({ modules, dependencies, package: packageId, ticket }); ``` | Parameter | Type | Description | | -------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `modules` | `number[][] \| string[]` | Compiled module bytecodes. Each module as a `number[]` (byte array) or base64-encoded `string`. To convert from `Uint8Array`, use `Array.from(bytes)`. | | `dependencies` | `string[]` | Package IDs of dependencies | | `package` | `string` | ID of the package being upgraded | | `ticket` | [object reference](#object-references) | The upgrade ticket | ## Transaction results Every command returns a `TransactionResult` that can be used as input to subsequent commands: ```typescript const [coin] = tx.splitCoins(tx.gas, [100]); tx.transferObjects([coin], address); ``` When a command returns multiple values, use destructuring or indexing: ```typescript const [a, b] = tx.moveCall({ target: '0xPkg::mod::returns_two' }); // or const result = tx.moveCall({ target: '0xPkg::mod::returns_two' }); tx.transferObjects([result[0], result[1]], address); ```