ts-sdk-client

How to create and configure the Aptos client (Aptos, AptosConfig) in @aptos-labs/ts-sdk. Covers Network, fullnode/indexer/faucet URLs, singleton pattern, and Bun compatibility. Triggers on: 'Aptos client', 'AptosConfig', 'SDK client', 'client setup', 'new Aptos(', 'Network.TESTNET', 'Network.MAINNET'.

Quality

85%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

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

Repository: aave/aptos-aave-v3
Path: .claude/skills/ts-sdk-client/SKILL.md
Commit: 919362b

Last updated: 5 days ago
First committed: 6 months ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.