use-typescript-sdk（USE TypeScript SDK 命令行）

Use TypeScript SDK Skill

Important: Boilerplate Template

If the project was scaffolded with create-aptos-dapp (boilerplate template), wallet adapter and SDK setup are already done. Before writing new code, check what already exists:

• frontend/components/WalletProvider.tsx — wallet adapter setup with auto-connect
• frontend/constants.ts — NETWORK, MODULE_ADDRESS, APTOS_API_KEY from env vars
• frontend/entry-functions/ — existing entry function patterns (follow these for new ones)
• frontend/view-functions/ — existing view function patterns (follow these for new ones)
• frontend/components/ — working components (TransferAPT, MessageBoard, WalletSelector, etc.)

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.

Core Rules

SDK Setup

1. ALWAYS use @aptos-labs/ts-sdk (the current official SDK, NOT the deprecated aptos package)
2. ALWAYS create a singleton Aptos client and export it from a shared module (e.g., lib/aptos.ts)
3. ALWAYS configure the network via AptosConfig with environment variables
4. ALWAYS use Network.TESTNET as the default for development (NOT devnet, which resets frequently)

Balance & Queries

1. ALWAYS use aptos.getBalance() for APT balance queries (NOT the deprecated getAccountCoinAmount or getAccountAPTAmount)

Transactions

1. ALWAYS call waitForTransaction after submitting any transaction
2. ALWAYS simulate transactions before submitting for critical or high-value operations
3. ALWAYS wrap blockchain calls in try/catch with specific error handling
4. ALWAYS use the build-sign-submit pattern: transaction.build.simple() then signAndSubmitTransaction()

Security

1. NEVER hardcode private keys in source code or frontend bundles
2. NEVER expose private keys in client-side code or logs
3. NEVER store private keys in environment variables accessible to the browser (use VITE_ prefix only for public config)
4. ALWAYS load private keys from environment variables in server-side scripts only, using process.env

Type Safety

1. ALWAYS use bigint for u128 and u256 values (JavaScript number loses precision)
2. ALWAYS pass Object<T> references as address strings in functionArguments
3. ALWAYS use typed entry/view function wrappers instead of raw string-based calls in production code

Wallet Adapter

1. ALWAYS use @aptos-labs/wallet-adapter-react for frontend wallet integration
2. ALWAYS wrap your app with AptosWalletAdapterProvider
3. ALWAYS use useWallet() hook to access wallet functions in React components

Quick Workflow

1. Install SDK -> npm install @aptos-labs/ts-sdk
2. Create client -> Singleton Aptos instance in lib/aptos.ts
3. Read data -> Use aptos.view() for on-chain reads
4. Write data -> Use aptos.transaction.build.simple() + aptos.signAndSubmitTransaction()
5. Connect wallet -> Use @aptos-labs/wallet-adapter-react for frontend dApps
6. Handle errors -> Wrap all calls in try/catch with error-type checks

Key Example: Client Setup

// lib/aptos.ts - Singleton client (create once, import everywhere)
import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";

function getNetwork(): Network {
  const network = import.meta.env.VITE_APP_NETWORK;
  switch (network) {
    case "mainnet":
      return Network.MAINNET;
    case "testnet":
      return Network.TESTNET;
    case "devnet":
      return Network.DEVNET;
    default:
      return Network.TESTNET;
  }
}

const config = new AptosConfig({ network: getNetwork() });
export const aptos = new Aptos(config);

export const MODULE_ADDRESS = import.meta.env.VITE_MODULE_ADDRESS;

Key Example: View Functions (Read)

// view-functions/getCount.ts
import { aptos, MODULE_ADDRESS } from "../lib/aptos";

export async function getCount(accountAddress: string): Promise<number> {
  const result = await aptos.view({
    payload: {
      function: `${MODULE_ADDRESS}::counter::get_count`,
      functionArguments: [accountAddress]
    }
  });
  return Number(result[0]);
}

// With type arguments
export async function getCoinBalance(accountAddress: string, coinType: string): Promise<bigint> {
  const result = await aptos.view({
    payload: {
      function: "0x1::coin::balance",
      typeArguments: [coinType],
      functionArguments: [accountAddress]
    }
  });
  return BigInt(result[0] as string);
}

// Multiple return values
// Move: public fun get_listing(addr): (address, u64, bool)
export async function getListing(nftAddress: string): Promise<{ seller: string; price: number; isActive: boolean }> {
  const [seller, price, isActive] = await aptos.view({
    payload: {
      function: `${MODULE_ADDRESS}::marketplace::get_listing`,
      functionArguments: [nftAddress]
    }
  });
  return {
    seller: seller as string,
    price: Number(price),
    isActive: isActive as boolean
  };
}

Key Example: Entry Functions (Write) - Server/Script

import { Account, Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";

const config = new AptosConfig({ network: Network.TESTNET });
const aptos = new Aptos(config);

// Build transaction
const transaction = await aptos.transaction.build.simple({
  sender: account.accountAddress,
  data: {
    function: `${MODULE_ADDRESS}::counter::increment`,
    functionArguments: []
  }
});

// Sign and submit
const pendingTx = await aptos.signAndSubmitTransaction({
  signer: account,
  transaction
});

// ALWAYS wait for confirmation
const committedTx = await aptos.waitForTransaction({
  transactionHash: pendingTx.hash
});

console.log("Success:", committedTx.success);

Key Example: Entry Functions (Write) - Frontend with Wallet

// entry-functions/increment.ts
import { InputTransactionData } from "@aptos-labs/wallet-adapter-react";
import { MODULE_ADDRESS } from "../lib/aptos";

export function buildIncrementPayload(): InputTransactionData {
  return {
    data: {
      function: `${MODULE_ADDRESS}::counter::increment`,
      functionArguments: [],
    },
  };
}

// Component usage
import { useWallet } from "@aptos-labs/wallet-adapter-react";
import { aptos } from "../lib/aptos";
import { buildIncrementPayload } from "../entry-functions/increment";

function IncrementButton() {
  const { signAndSubmitTransaction } = useWallet();

  const handleClick = async () => {
    try {
      const response = await signAndSubmitTransaction(
        buildIncrementPayload(),
      );
      await aptos.waitForTransaction({
        transactionHash: response.hash,
      });
    } catch (error) {
      console.error("Transaction failed:", error);
    }
  };

  return <button onClick={handleClick}>Increment</button>;
}

Key Example: Wallet Adapter Setup

// main.tsx or App.tsx
import { AptosWalletAdapterProvider } from "@aptos-labs/wallet-adapter-react";
import { Network } from "@aptos-labs/ts-sdk";

function App() {
  return (
    <AptosWalletAdapterProvider
      autoConnect={true}
      dappConfig={{
        network: Network.TESTNET,
      }}
      onError={(error) => console.error("Wallet error:", error)}
    >
      <YourApp />
    </AptosWalletAdapterProvider>
  );
}

// In any child component
import { useWallet } from "@aptos-labs/wallet-adapter-react";

function WalletInfo() {
  const { account, connected, connect, disconnect, wallet, wallets } =
    useWallet();

  if (!connected) {
    return (
      <div>
        {wallets.map((w) => (
          <button key={w.name} onClick={() => connect(w.name)}>
            Connect {w.name}
          </button>
        ))}
      </div>
    );
  }

  return (
    <div>
      <p>Connected: {account?.address}</p>
      <p>Wallet: {wallet?.name}</p>
      <button onClick={disconnect}>Disconnect</button>
    </div>
  );
}

Key Example: Sponsored Transactions (Fee Payer)

import { Account, Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";

const aptos = new Aptos(new AptosConfig({ network: Network.TESTNET }));

// 1. Build with fee payer flag
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 signatures
const pendingTx = await aptos.transaction.submit.simple({
  transaction,
  senderAuthenticator: senderAuth,
  feePayerAuthenticator: feePayerAuth
});

await aptos.waitForTransaction({ transactionHash: pendingTx.hash });

Key Example: Multi-Agent Transactions

// 1. Build multi-agent transaction
const transaction = await aptos.transaction.build.multiAgent({
  sender: alice.accountAddress,
  secondarySignerAddresses: [bob.accountAddress],
  data: {
    function: `${MODULE_ADDRESS}::escrow::exchange`,
    functionArguments: [itemAddress, paymentAmount]
  }
});

// 2. Each agent signs
const aliceAuth = aptos.transaction.sign({
  signer: alice,
  transaction
});
const bobAuth = aptos.transaction.sign({
  signer: bob,
  transaction
});

// 3. Submit with all signatures
const pendingTx = await aptos.transaction.submit.multiAgent({
  transaction,
  senderAuthenticator: aliceAuth,
  additionalSignersAuthenticators: [bobAuth]
});

await aptos.waitForTransaction({ transactionHash: pendingTx.hash });

Type Mappings: Move to TypeScript

Transaction Simulation

// Build transaction
const transaction = await aptos.transaction.build.simple({
  sender: account.accountAddress,
  data: {
    function: `${MODULE_ADDRESS}::counter::increment`,
    functionArguments: []
  }
});

// Simulate to check for errors and estimate gas
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 estimate:", simResult.gas_used);

Gas Profiling

// Profile gas usage of a transaction (useful for optimization)
const gasProfile = await aptos.gasProfile({
  sender: account.accountAddress,
  data: {
    function: `${MODULE_ADDRESS}::module::function_name`,
    functionArguments: []
  }
});

console.log("Gas profile:", gasProfile);

Anti-patterns

1. NEVER use the deprecated aptos npm package - use @aptos-labs/ts-sdk instead
2. NEVER skip waitForTransaction after submitting - transaction may not be committed yet
3. NEVER hardcode module addresses - use environment variables (VITE_MODULE_ADDRESS)
4. NEVER use number for u128/u256 values - JavaScript loses precision above 2^53; use bigint
5. NEVER create multiple Aptos client instances - create one singleton and share it
6. NEVER ignore transaction simulation results for high-value operations
7. NEVER hardcode network selection - use environment-based configuration
8. NEVER store private keys in browser-accessible env vars (e.g., VITE_PRIVATE_KEY)
9. NEVER use Account.generate() in frontend code for real users - use wallet adapter instead
10. NEVER use raw aptos.signAndSubmitTransaction in React - use the wallet adapter's signAndSubmitTransaction
11. NEVER use scriptComposer - it was removed in v6.0; use batch transactions or separate calls instead
12. NEVER use getAccountCoinAmount or getAccountAPTAmount - deprecated; use getBalance() instead

Edge Cases to Handle

Error Handling Pattern

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;
  }
}

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 functions

SDK Version Notes (v5.2+ / v6.0)

Balance Queries (v5.1+)

// CORRECT (v5.1+)
const balance = await aptos.getBalance({
  accountAddress: account.accountAddress
});
// Returns bigint in octas (1 APT = 100_000_000 octas)

// DEPRECATED - do NOT use
// await aptos.getAccountCoinAmount(...)
// await aptos.getAccountAPTAmount(...)

AIP-80 Private Key Format (v2.0+)

Ed25519 and Secp256k1 private keys now use an AIP-80 prefixed format when serialized with toString():

const key = new Ed25519PrivateKey("0x...");
key.toString(); // Returns AIP-80 prefixed format, NOT raw hex

AccountAddress Parsing (v1.32+)

AccountAddress.fromString() now only accepts SHORT format (60-64 hex chars) by default. Use AccountAddress.from() for flexible parsing:

// CORRECT
const addr = AccountAddress.from("0x1"); // Accepts any format
const addr2 = AccountAddress.fromString("0x000000000000000000000000000000000000000000000000000000000000001"); // SHORT format only

// MAY FAIL in v1.32+
// AccountAddress.fromString("0x1") -- too short for SHORT format

Fungible Asset Transfers (v1.39+)

// Transfer between FA stores directly
await aptos.transferFungibleAssetBetweenStores({
  sender: account,
  fungibleAssetMetadataAddress: metadataAddr,
  senderStoreAddress: fromStore,
  recipientStoreAddress: toStore,
  amount: 1000n
});

Bun Runtime Compatibility

When using Bun instead of Node.js, disable HTTP/2 in the client config:

const config = new AptosConfig({
  network: Network.TESTNET,
  clientConfig: { http2: false }
});

Account Abstraction (v1.34+, AIP-104)

The aptos.abstraction namespace provides APIs for custom authentication:

// 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`
});

// Disable AA
const disableTxn = await aptos.abstraction.disableAccountAbstractionTransaction({
  accountAddress: account.accountAddress,
  authenticationFunction: `${MODULE_ADDRESS}::auth::authenticate`
});

// Use AbstractedAccount for signing with custom auth logic
import { AbstractedAccount } from "@aptos-labs/ts-sdk";

References

Detailed Patterns (references/ folder):

• references/wallet-adapter.md - Wallet adapter setup and patterns
• references/transaction-patterns.md - Advanced transaction patterns (sponsored, multi-agent, simulation)
• references/type-mappings.md - Complete Move-to-TypeScript type reference

Pattern Documentation (patterns/ folder):

• ../../../patterns/fullstack/TYPESCRIPT_SDK.md - Complete SDK API reference

Official Documentation:

• TypeScript SDK: https://aptos.dev/build/sdks/ts-sdk
• SDK Quickstart: https://aptos.dev/build/sdks/ts-sdk/quickstart
• API Reference: https://aptos-labs.github.io/aptos-ts-sdk/
• Wallet Adapter: https://aptos.dev/build/sdks/wallet-adapter/dapp
• Sponsored Transactions: https://aptos.dev/build/sdks/ts-sdk/building-transactions/sponsoring-transactions
• Multi-Agent Transactions: https://aptos.dev/build/sdks/ts-sdk/building-transactions/multi-agent-transactions
• GitHub: https://github.com/aptos-labs/aptos-ts-sdk

Related Skills:

• write-contracts - Write the Move contracts that this SDK interacts with
• deploy-contracts - Deploy contracts before calling them from TypeScript