ts-sdk-transactions
How to build, sign, submit, and simulate transactions in @aptos-labs/ts-sdk. Covers build.simple(), signAndSubmitTransaction(), waitForTransaction(), simulate, sponsored (fee payer), and multi-agent. Triggers on: 'build.simple', 'signAndSubmitTransaction', 'transaction.build', 'waitForTransaction', 'signAsFeePayer', 'SDK transaction', 'sponsored transaction', 'multi-agent transaction'.
How do I install this agent skill?
npx skills add https://github.com/aptos-labs/aptos-agent-skills --skill ts-sdk-transactionsIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides standard documentation and code examples for using the Aptos TypeScript SDK. It follows security best practices for blockchain interactions and contains no malicious patterns or vulnerabilities.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
- Runlayerpass
1 file scanned · No issues
- ZeroLeakspass
Score: 93/100 · 2 sections analyzed
What does this agent skill do?
TypeScript SDK: Transactions
Purpose
Guide building, signing, submitting, and simulating transactions with @aptos-labs/ts-sdk. Use the build → sign →
submit → wait pattern; optionally simulate before submit.
ALWAYS
- Call
aptos.waitForTransaction({ transactionHash })after submit – do not assume transaction is committed aftersignAndSubmitTransaction. - Use
aptos.transaction.build.simple()for entry function payloads – passsenderanddata: { function, functionArguments, typeArguments? }. - Simulate before submit for critical/high-value flows – use
aptos.transaction.simulate.simple()and checksuccessandvm_status. - Use the same Account instance for signer that you use for
senderaddress when building (e.g.account.accountAddressas sender,accountas signer).
NEVER
- Do not skip
waitForTransaction– submission returns when the tx is accepted, not when it is committed. - Do not use deprecated
scriptComposer(removed in v6) – use separate transactions or batch patterns. - Do not use
numberfor u64/u128/u256 infunctionArguments– usebigintwhere required to avoid precision loss.
Standard flow (simple transaction)
import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
const aptos = new Aptos(new AptosConfig({ network: Network.TESTNET }));
const MODULE_ADDRESS = "0x...";
// 1. Build
const transaction = await aptos.transaction.build.simple({
sender: account.accountAddress,
data: {
function: `${MODULE_ADDRESS}::counter::increment`,
functionArguments: []
}
});
// 2. Sign and submit
const pendingTx = await aptos.signAndSubmitTransaction({
signer: account,
transaction
});
// 3. Wait for commitment
const committedTx = await aptos.waitForTransaction({
transactionHash: pendingTx.hash
});
if (!committedTx.success) {
throw new Error(`Tx failed: ${committedTx.vm_status}`);
}
Build options
// With type arguments (e.g. coin type)
const transaction = await aptos.transaction.build.simple({
sender: account.accountAddress,
data: {
function: "0x1::coin::transfer",
typeArguments: ["0x1::aptos_coin::AptosCoin"],
functionArguments: [recipientAddress, amount]
}
});
// Optional: max gas, expiry, etc. (see SDK types for full options)
const transactionWithOptions = await aptos.transaction.build.simple({
sender: account.accountAddress,
data: { function: "...", functionArguments: [] },
options: {
maxGasAmount: 2000n,
gasUnitPrice: 100n,
expireTimestamp: BigInt(Math.floor(Date.now() / 1000) + 600)
}
});
Simulation (before submit)
const transaction = await aptos.transaction.build.simple({
sender: account.accountAddress,
data: {
function: `${MODULE_ADDRESS}::counter::increment`,
functionArguments: []
}
});
const [simResult] = await aptos.transaction.simulate.simple({
signerPublicKey: account.publicKey,
transaction
});
if (!simResult.success) {
throw new Error(`Simulation failed: ${simResult.vm_status}`);
}
console.log("Gas used:", simResult.gas_used);
Sponsored transactions (fee payer)
// 1. Build with fee payer
const transaction = await aptos.transaction.build.simple({
sender: sender.accountAddress,
withFeePayer: true,
data: {
function: `${MODULE_ADDRESS}::counter::increment`,
functionArguments: []
}
});
// 2. Sender signs
const senderAuth = aptos.transaction.sign({
signer: sender,
transaction
});
// 3. Fee payer signs (different method)
const feePayerAuth = aptos.transaction.signAsFeePayer({
signer: feePayer,
transaction
});
// 4. Submit with both authenticators
const pendingTx = await aptos.transaction.submit.simple({
transaction,
senderAuthenticator: senderAuth,
feePayerAuthenticator: feePayerAuth
});
await aptos.waitForTransaction({ transactionHash: pendingTx.hash });
Multi-agent transactions
const transaction = await aptos.transaction.build.multiAgent({
sender: alice.accountAddress,
secondarySignerAddresses: [bob.accountAddress],
data: {
function: `${MODULE_ADDRESS}::escrow::exchange`,
functionArguments: [itemAddress, amount]
}
});
const aliceAuth = aptos.transaction.sign({ signer: alice, transaction });
const bobAuth = aptos.transaction.sign({ signer: bob, transaction });
const pendingTx = await aptos.transaction.submit.multiAgent({
transaction,
senderAuthenticator: aliceAuth,
additionalSignersAuthenticators: [bobAuth]
});
await aptos.waitForTransaction({ transactionHash: pendingTx.hash });
waitForTransaction options
const committed = await aptos.waitForTransaction({
transactionHash: pendingTx.hash,
options: {
timeoutSecs: 60,
checkSuccess: true // throw if tx failed
}
});
Gas profiling
const gasProfile = await aptos.gasProfile({
sender: account.accountAddress,
data: {
function: `${MODULE_ADDRESS}::module::function_name`,
functionArguments: []
}
});
console.log("Gas profile:", gasProfile);
Common mistakes
| Mistake | Correct approach |
|---|---|
| Not calling waitForTransaction | Always wait and check committedTx.success |
| Using number for large amounts | Use bigint for u64/u128/u256 in functionArguments |
| Wrong signer for submit | Use the Account whose address is the sender (or fee payer / additional signer as appropriate) |
| Assuming scriptComposer exists | Use separate transactions or batch; scriptComposer removed in v6 |
References
- SDK:
src/api/transaction.ts,src/internal/transactionSubmission.ts,src/internal/transaction.ts - Pattern: TYPESCRIPT_SDK.md
- Related: ts-sdk-account, ts-sdk-client, ts-sdk-wallet-adapter, use-ts-sdk
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/aptos-labs/aptos-agent-skills/ts-sdk-transactions">View ts-sdk-transactions on skillZs</a>