TypeScript SDK: Aptos Client

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.

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.

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.

Basic setup

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

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

Network options

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

Singleton pattern (recommended)

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

Optional endpoints (override per service)

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

Client config (HTTP, timeouts, Bun)

// Disable HTTP/2 when using Bun (recommended) 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.* .

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

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