Compose multiple Aptos Move entry-function calls into one script transaction. The SDK builds on @aptos-labs/ts-sdk and @aptos-labs/script-composer-pack (WASM), and supports single-signer, multi-agent, and fee-payer transactions.
For the official Aptos guide, see Invoke chains of Move calls with Dynamic Script Composer.
A transaction normally invokes one entry function. Script Composer lets an application describe several compatible calls, including calls that consume values returned by earlier calls, and execute them atomically in one Aptos transaction.
pnpm add @aptos-labs/script-composer-sdk @aptos-labs/ts-sdk @aptos-labs/script-composer-packThe SDK supports @aptos-labs/ts-sdk major versions 3 through 7. Use Node.js 22 or a current LTS release for this repository and its examples.
Browser applications also need the buffer peer dependency and a global polyfill before initializing the SDK:
pnpm add bufferimport { Buffer } from 'buffer';
(window as typeof window & { Buffer: typeof Buffer }).Buffer = Buffer;The React and Next.js examples in this repository follow this pattern.
This example builds a transaction that transfers APT on Testnet. By default, the composer fetches the Move ABI and bytecode it needs from the configured network. Building a transaction does not sign or submit it.
import { Aptos, AptosConfig, Network } from '@aptos-labs/ts-sdk';
import { BuildScriptComposerTransaction, CallArgument } from '@aptos-labs/script-composer-sdk';
const config = new AptosConfig({ network: Network.TESTNET });
const sender = '0x...';
const recipient = '0x...';
const transaction = await BuildScriptComposerTransaction({
sender,
aptosConfig: config,
builder: async (composer) => {
await composer.addBatchedCalls({
function: '0x1::aptos_account::transfer',
functionArguments: [CallArgument.newSigner(0), recipient, 1_000],
});
return composer;
},
});
// Safe for a quick integration check; no transaction is submitted.
const result = await new Aptos(config).transaction.simulate.simple({ transaction });
console.log(result);To submit a transaction, sign the returned transaction with the appropriate accounts using @aptos-labs/ts-sdk, then submit the resulting authenticator. See the Aptos TypeScript SDK documentation for account management and signing APIs.
addBatchedCalls uses allowFetch: true by default. The composer fetches missing Move module ABI and bytecode from the configured full node, which is convenient for connected applications.
For offline or controlled environments, set options.allowFetch to false and provide both moduleAbi and moduleBytecodes. You can also preload modules with getModuleInner and composer.storeModule as shown in the Node example.
When a Move entry function is generic, pass concrete type tags through typeArguments. The composer also loads any modules required by those type tags:
await composer.addBatchedCalls({
function: '0x1::coin::transfer',
typeArguments: ['0x1::aptos_coin::AptosCoin'],
functionArguments: [CallArgument.newSigner(0), recipient, 1_000],
});addBatchedCalls returns CallArgument[]. Pass a returned item into a later call's functionArguments to compose dependent operations without leaving the transaction:
const [createdObject] = await composer.addBatchedCalls({ /* first call */ });
await composer.addBatchedCalls({
function: '0x...::module::consume',
functionArguments: [createdObject],
});Move ability rules still apply at composition time. Values without drop must be consumed by a later call, and values without copy can only be forwarded once. See the official Script Composer guide for examples.
CallArgument.newSigner(0)refers to the primary sender. Secondary signers are indexed starting at1.- Use
BuildScriptComposerTransactionfor a normal, single-signer transaction. - Use
BuildScriptComposerMultiAgentTransactionwhen calls require secondary signers and/or a fee payer. It returns a transaction that each required account must sign before submission. - For a sponsored transaction with only the primary sender and no secondary signers, you can also pass
withFeePayer: truetoBuildScriptComposerTransaction. - A fee payer pays gas; it is not an additional Move-function signer unless the Move call itself requires one.
- Single-signer transactions:
aptos.transaction.simulate.simple({ transaction }) - Multi-agent transactions:
aptos.transaction.simulate.multiAgent({ transaction, ... })with the public keys for each required signer
| Example | Demonstrates | Run from repository root |
|---|---|---|
| Node.js | Auto-fetch and preloaded-module composition, then simulation on Testnet | pnpm --filter example-nodejs start |
| Multi-agent Node.js | Secondary signers and fee-payer transaction construction | pnpm --filter example-multi-agent-nodejs start |
| React | Browser UI for composing and simulating transactions | pnpm --filter react-project dev |
| Next.js | Browser UI including multi-agent flows | pnpm --filter nextjs-project dev |
Examples construct or simulate transactions only unless their documentation explicitly says otherwise. Review function arguments, account addresses, and network configuration before adapting an example to submit real transactions.
git clone https://github.com/aptos-labs/script-composer-sdk.git
cd script-composer-sdk
pnpm install
pnpm build
pnpm testThe repository is a pnpm workspace. SDK source is in packages/sdk; runnable applications live under examples.
This project uses Changesets. Changes that affect the published SDK should include a changeset:
pnpm changesetMerging changesets to main creates or updates a version PR; merging that PR publishes the package through .github/workflows/release.yml.
Maintainers: configure the GitHub App (APTOS_LABS_BOT_APP_ID, APTOS_LABS_BOT_APP_PRIVATE_KEY) and npm Trusted Publisher for that workflow before the first automated release.
For defects and feature requests, open a GitHub issue. Do not report security vulnerabilities in a public issue; follow Aptos Labs' security reporting process instead.