ts-sdk-client

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TypeScript SDK: Aptos Client

TypeScript SDK：Aptos 客户端

Purpose

目的

Guide creation and configuration of the Aptos client and AptosConfig in

@aptos-labs/ts-sdk

. One client instance is used for all read/write and account/transaction APIs.

本文指导如何在

@aptos-labs/ts-sdk

中创建和配置Aptos客户端与AptosConfig。单个客户端实例可用于所有读写、账户及交易API。

ALWAYS

务必遵守

Create one Aptos instance per app (singleton) and reuse it – avoid multiple
```
new Aptos(config)
```
for the same network.
Configure network via
AptosConfig
– use
```
Network.TESTNET
```
or
```
Network.MAINNET
```
(or custom endpoints).
Use environment variables for network/URLs in production – e.g.
```
process.env.APTOS_NETWORK
```
or
```
import.meta.env.VITE_APP_NETWORK
```
.
Use
Network.TESTNET
as default for development – devnet resets frequently.

每个应用仅创建一个Aptos实例（单例模式）并复用——避免针对同一网络多次调用
```
new Aptos(config)
```
。
通过
AptosConfig
配置网络——使用
```
Network.TESTNET
```
或
```
Network.MAINNET
```
（或自定义端点）。
生产环境中使用环境变量存储网络/URL——例如
```
process.env.APTOS_NETWORK
```
或
```
import.meta.env.VITE_APP_NETWORK
```
。
开发环境默认使用
Network.TESTNET
——devnet会频繁重置。

NEVER

禁止操作

Do not create a new Aptos client per request – reuse the singleton.
Do not hardcode fullnode/indexer URLs in source when using public networks – use
```
Network
```
enum.
Do not omit
network
when using custom endpoints – in v5.2+ use
```
Network.CUSTOM
```
with custom URLs.

不要为每个请求创建新的Aptos客户端——复用单例实例。
使用公共网络时不要在源码中硬编码全节点/索引器URL——使用
```
Network
```
枚举。
使用自定义端点时不要省略
network
参数——在v5.2+版本中需搭配
```
Network.CUSTOM
```
及自定义URL使用。

Basic setup

基础配置

typescript

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

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

typescript

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

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

Network options

网络选项

typescript

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

typescript

// 预定义网络
const devnet  = new AptosConfig({ network: Network.DEVNET });
const testnet = new AptosConfig({ network: Network.TESTNET });
const mainnet = new AptosConfig({ network: Network.MAINNET });

// 自定义端点（v5.2+版本中network为必填项）
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",
});

Singleton pattern (recommended)

单例模式（推荐）

typescript

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

typescript

// lib/aptos.ts 或类似文件
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);

Optional endpoints (override per service)

可选端点（按服务覆盖配置）

typescript

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

typescript

const config = new AptosConfig({
  network: Network.TESTNET,
  fullnode: "https://fullnode.testnet.aptoslabs.com/v1",  // 覆盖默认值
  indexer: "https://indexer.testnet.aptoslabs.com/v1/graphql",
  faucet: "https://faucet.testnet.aptoslabs.com",
  pepper: "https://...",   // 无密钥pepper服务
  prover: "https://...",   // 无密钥prover
});
const aptos = new Aptos(config);

Client config (HTTP, timeouts, Bun)

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

typescript

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

typescript

// 使用Bun时禁用HTTP/2（推荐）
const config = new AptosConfig({
  network: Network.TESTNET,
  clientConfig: { http2: false },
});
const aptos = new Aptos(config);

Using the client

客户端使用

After construction, use the same

aptos

instance for:

Account / balance:

aptos.getAccountInfo()

aptos.getBalance()

aptos.getAccountResources()

, etc.

Transactions:

aptos.transaction.build.simple()

aptos.signAndSubmitTransaction()

aptos.waitForTransaction()

View:
```
aptos.view()
```
.
Faucet:
```
aptos.fundAccount()
```
(devnet/testnet).

Coin / token / object / ANS / staking:

aptos.coin.*

aptos.digitalAsset.*

aptos.fungibleAsset.*

aptos.object.*

aptos.ans.*

aptos.staking.*

创建实例后，可复用同一

aptos

实例完成以下操作：

账户/余额：

aptos.getAccountInfo()

、

aptos.getBalance()

、

aptos.getAccountResources()

等。

交易：

aptos.transaction.build.simple()

、

aptos.signAndSubmitTransaction()

、

aptos.waitForTransaction()

。

视图调用：
```
aptos.view()
```
。
水龙头：
```
aptos.fundAccount()
```
（仅devnet/testnet可用）。

代币/资产/对象/ANS/质押：

aptos.coin.*

、

aptos.digitalAsset.*

、

aptos.fungibleAsset.*

、

aptos.object.*

、

aptos.ans.*

、

aptos.staking.*

。

Common mistakes

常见错误

Mistake	Correct approach
Creating Aptos in every function	One singleton; pass `aptos` or import from shared module
Using devnet for persistent dev	Prefer testnet; devnet resets
Custom URLs without Network.CUSTOM	Set `network: Network.CUSTOM` when providing fullnode/indexer/faucet
Forgetting http2: false on Bun	Set `clientConfig: { http2: false }` for Bun

错误操作	正确做法
在每个函数中创建Aptos实例	仅创建一个单例实例；通过参数传递 `aptos` 或从共享模块导入
使用devnet进行持久化开发	优先使用testnet；devnet会定期重置
自定义URL未搭配Network.CUSTOM	提供全节点/索引器/水龙头URL时，需设置 `network: Network.CUSTOM`
使用Bun时未设置http2: false	配置 `clientConfig: { http2: false }` 以适配Bun

References

参考资料

SDK:
```
src/api/aptos.ts
```
,
```
src/api/aptosConfig.ts
```
Pattern: TYPESCRIPT_SDK.md
Related: ts-sdk-account, ts-sdk-transactions, ts-sdk-wallet-adapter, use-ts-sdk

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