use-ts-sdk
Original:🇺🇸 English
Translated
Orchestrates TypeScript SDK integration for Aptos dApps. Routes to granular skills for specific tasks (client setup, accounts, transactions, view functions, types, wallet adapter). Use this skill for fullstack dApp integration or when multiple SDK concerns are involved. Triggers on: 'typescript sdk', 'ts-sdk', 'aptos sdk', 'SDK setup', 'interact with contract', 'call aptos', 'aptos javascript', 'frontend integration', 'fullstack'.
2installs
Added on
NPX Install
npx skill4agent add iskysun96/aptos-agent-skills use-ts-sdkTags
Translated version includes tags in frontmatterSKILL.md Content
View Translation Comparison →Use TypeScript SDK (Orchestrator)
Purpose
Orchestrates integration for Aptos dApps. For specific tasks, route to the appropriate granular skill. For composite tasks (e.g., "build me a fullstack dApp"), follow the workflow below.
@aptos-labs/ts-sdkCore Rules
- ALWAYS use (the current official SDK, NOT the deprecated
@aptos-labs/ts-sdkpackage)aptos - NEVER hardcode private keys in source code or frontend bundles
- NEVER expose private keys in client-side code or logs
- NEVER store private keys in environment variables accessible to the browser (use prefix only for public config)
VITE_ - ALWAYS load private keys from environment variables in server-side scripts only, using
process.env
Important: Boilerplate Template
If the project was scaffolded with (boilerplate template), wallet adapter and SDK setup are already done. Before writing new code, check what already exists:
create-aptos-dapp- — wallet adapter setup with auto-connect
frontend/components/WalletProvider.tsx - —
frontend/constants.ts,NETWORK,MODULE_ADDRESSfrom env varsAPTOS_API_KEY - — existing entry function patterns (follow these for new ones)
frontend/entry-functions/ - — existing view function patterns (follow these for new ones)
frontend/view-functions/
Do NOT recreate wallet provider, client setup, or constants if they already exist. Instead, follow the existing patterns to add new entry/view functions for your Move contracts.
Skill Routing
Route to the appropriate granular skill based on the task:
| Task | Skill |
|---|---|
| Set up Aptos client / configure network | ts-sdk-client |
| Create accounts/signers (server-side) | ts-sdk-account |
| Parse, format, or derive addresses | ts-sdk-address |
| Build, sign, submit, simulate transactions | ts-sdk-transactions |
| Read on-chain data (view, balances, resources) | ts-sdk-view-and-query |
| Map Move types to TypeScript types | ts-sdk-types |
| Connect wallet in React frontend | ts-sdk-wallet-adapter |
Fullstack dApp Workflow
When building a complete frontend integration:
- Set up client → read ts-sdk-client
- Create view function wrappers → read ts-sdk-view-and-query
- Create entry function payloads → read ts-sdk-transactions
- Wire up wallet connection → read ts-sdk-wallet-adapter
- Handle types correctly → read ts-sdk-types (as needed)
File Organization Pattern
src/
lib/
aptos.ts # Singleton Aptos client + MODULE_ADDRESS
view-functions/
getCount.ts # One file per view function
getListing.ts
entry-functions/
increment.ts # One file per entry function
createListing.ts
hooks/
useCounter.ts # React hooks wrapping view functions
useListing.ts
components/
WalletProvider.tsx # AptosWalletAdapterProvider wrapper
IncrementButton.tsx # Components calling entry functionsError Handling Pattern
typescript
async function submitTransaction(
aptos: Aptos,
signer: Account,
payload: InputGenerateTransactionPayloadData
): Promise<string> {
try {
const transaction = await aptos.transaction.build.simple({
sender: signer.accountAddress,
data: payload
});
const pendingTx = await aptos.signAndSubmitTransaction({
signer,
transaction
});
const committed = await aptos.waitForTransaction({
transactionHash: pendingTx.hash
});
if (!committed.success) {
throw new Error(`Transaction failed: ${committed.vm_status}`);
}
return pendingTx.hash;
} catch (error) {
if (error instanceof Error) {
if (error.message.includes("RESOURCE_NOT_FOUND")) {
throw new Error("Resource does not exist at the specified address");
}
if (error.message.includes("MODULE_NOT_FOUND")) {
throw new Error("Contract is not deployed at the specified address");
}
if (error.message.includes("ABORTED")) {
const match = error.message.match(/code: (\d+)/);
const code = match ? match[1] : "unknown";
throw new Error(`Contract error (code ${code})`);
}
}
throw error;
}
}Edge Cases
| Scenario | Check | Action |
|---|---|---|
| Resource not found | | Return default value or null |
| Module not deployed | | Show "contract not deployed" message |
| Function not found | | Check function name and module address |
| Move abort | | Parse abort code, map to user-friendly error |
| Out of gas | | Increase |
| Sequence number error | | Retry after fetching fresh sequence number |
| Network timeout | | Retry with exponential backoff |
| Account does not exist | | Fund account or prompt user to create one |
| Insufficient balance | | Show balance and required amount |
| User rejected in wallet | Wallet-specific rejection error | Show "transaction cancelled" message |
Anti-patterns
- NEVER use the deprecated npm package — use
aptos@aptos-labs/ts-sdk - NEVER skip after submitting — transaction may not be committed yet
waitForTransaction - NEVER hardcode module addresses — use environment variables ()
VITE_MODULE_ADDRESS - NEVER create multiple client instances — create one singleton and share it
Aptos - NEVER use in frontend code for real users — use wallet adapter
Account.generate() - NEVER use — removed in v6.0; use separate transactions instead
scriptComposer - NEVER use or
getAccountCoinAmount— deprecated; usegetAccountAPTAmountgetBalance()
SDK Version Notes
AIP-80 Private Key Format (v2.0+)
Ed25519 and Secp256k1 private keys now use an AIP-80 prefixed format when serialized with :
toString()typescript
const key = new Ed25519PrivateKey("0x...");
key.toString(); // Returns AIP-80 prefixed format, NOT raw hexFungible Asset Transfers (v1.39+)
typescript
await aptos.transferFungibleAssetBetweenStores({
sender: account,
fungibleAssetMetadataAddress: metadataAddr,
senderStoreAddress: fromStore,
recipientStoreAddress: toStore,
amount: 1000n
});Account Abstraction (v1.34+, AIP-104)
typescript
// Check if AA is enabled for an account
const isEnabled = await aptos.abstraction.isAccountAbstractionEnabled({
accountAddress: "0x...",
authenticationFunction: `${MODULE_ADDRESS}::auth::authenticate`
});
// Enable AA on an account
const enableTxn = await aptos.abstraction.enableAccountAbstractionTransaction({
accountAddress: account.accountAddress,
authenticationFunction: `${MODULE_ADDRESS}::auth::authenticate`
});
// Use AbstractedAccount for signing with custom auth logic
import { AbstractedAccount } from "@aptos-labs/ts-sdk";References
Pattern Documentation:
- TYPESCRIPT_SDK.md — Complete SDK API reference
Official Documentation:
- TypeScript SDK: https://aptos.dev/build/sdks/ts-sdk
- API Reference: https://aptos-labs.github.io/aptos-ts-sdk/
- Wallet Adapter: https://aptos.dev/build/sdks/wallet-adapter/dapp
- GitHub: https://github.com/aptos-labs/aptos-ts-sdk
Granular Skills:
- ts-sdk-client — Client setup and configuration
- ts-sdk-account — Account/signer creation
- ts-sdk-address — Address parsing and derivation
- ts-sdk-transactions — Build, sign, submit transactions
- ts-sdk-view-and-query — View functions and queries
- ts-sdk-types — Move-to-TypeScript type mapping
- ts-sdk-wallet-adapter — React wallet integration
Related Skills:
- — Write the Move contracts that this SDK interacts with
write-contracts - — Deploy contracts before calling them from TypeScript
deploy-contracts