ts-sdk-client

TypeScript SDK：Aptos 客户端

用途

介绍如何在 @aptos-labs/ts-sdk 中创建和配置 Aptos 客户端和 AptosConfig。所有读写以及账户／交易 API 都使用同一个客户端实例。

始终遵循

1. 每个应用创建一个 Aptos 实例（单例）并重复使用——避免为同一网络创建多个 new Aptos(config)。
2. 通过 AptosConfig 配置网络——使用 Network.TESTNET 或 Network.MAINNET（或自定义端点）。
3. 在生产环境中使用环境变量配置网络／URL——例如 process.env.APTOS_NETWORK 或 import.meta.env.VITE_APP_NETWORK。
4. 开发环境默认使用 Network.TESTNET——devnet 会频繁重置。

切勿

1. 不要为每个请求创建新的 Aptos 客户端——重复使用单例。
2. 使用公共网络时，不要在源代码中硬编码完整的 fullnode／indexer URL——请使用 Network 枚举。
3. 使用自定义端点时，不要省略 network——在 v5.2+ 中，使用 Network.CUSTOM 和自定义 URL。

---

基本设置

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

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

---

网络选项

// Predefined networks
const devnet = new AptosConfig({ network: Network.DEVNET });
const testnet = new AptosConfig({ network: Network.TESTNET });
const mainnet = new AptosConfig({ network: Network.MAINNET });

// Custom endpoints (network is REQUIRED in v5.2+)
const custom = new AptosConfig({
  network: Network.CUSTOM,
  fullnode: "https://your-fullnode.example.com/v1",
  indexer: "https://your-indexer.example.com/v1/graphql",
  faucet: "https://your-faucet.example.com"
});

---

单例模式（推荐）

// lib/aptos.ts or similar
import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";

function getNetwork(): Network {
  const raw = typeof process !== "undefined" ? process.env.APTOS_NETWORK : import.meta.env?.VITE_APP_NETWORK;
  switch (raw) {
    case "mainnet":
      return Network.MAINNET;
    case "devnet":
      return Network.DEVNET;
    default:
      return Network.TESTNET;
  }
}

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

---

可选端点（按服务覆盖）

const config = new AptosConfig({
  network: Network.TESTNET,
  fullnode: "https://fullnode.testnet.aptoslabs.com/v1", // override default
  indexer: "https://indexer.testnet.aptoslabs.com/v1/graphql",
  faucet: "https://faucet.testnet.aptoslabs.com",
  pepper: "https://...", // keyless pepper service
  prover: "https://..." // keyless prover
});
const aptos = new Aptos(config);

---

客户端配置（HTTP、超时、Bun）

// Disable HTTP/2 when using Bun (recommended)
const config = new AptosConfig({
  network: Network.TESTNET,
  clientConfig: { http2: false }
});
const aptos = new Aptos(config);

---

使用客户端

构造完成后，以下操作均使用同一个 aptos 实例：

• 账户／余额： aptos.getAccountInfo()、aptos.getBalance()、aptos.getAccountResources() 等。
• 交易： aptos.transaction.build.simple()、aptos.signAndSubmitTransaction()、 aptos.waitForTransaction()。
• View： aptos.view()。
• 水龙头： aptos.fundAccount()（devnet／testnet）。
• Coin／Token／对象／ANS／质押： aptos.coin.*、aptos.digitalAsset.*、aptos.fungibleAsset.*、 aptos.object.*、aptos.ans.*、aptos.staking.*。

---

常见错误

错误	正确做法
在每个函数中创建 Aptos	使用一个单例；传入 aptos，或从共享模块导入
使用 devnet 进行持久开发	优先使用 testnet；devnet 会重置
自定义 URL 未设置 Network.CUSTOM	提供 fullnode／indexer／faucet 时，设置 network: Network.CUSTOM
在 Bun 中忘记设置 http2: false	为 Bun 设置 clientConfig: { http2: false }

---

参考

• SDK：src/api/aptos.ts、src/api/aptosConfig.ts
• 模式：TYPESCRIPT_SDK.md
• 相关：ts-sdk-account、ts-sdk-transactions、 ts-sdk-wallet-adapter、use-ts-sdk