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'.
How do I install this agent skill?
npx skills add https://github.com/aptos-labs/aptos-agent-skills --skill ts-sdk-clientIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides architectural guidance and best practices for configuring the Aptos TypeScript SDK client. It promotes secure configuration through environment variables and utilizes official Aptos Labs infrastructure, following industry standards for SDK integration.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerpass
1 file scanned · No issues
- ZeroLeakspass
Score: 93/100 · 2 sections analyzed
What does this agent skill do?
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– useNetwork.TESTNETorNetwork.MAINNET(or custom endpoints). - Use environment variables for network/URLs in production – e.g.
process.env.APTOS_NETWORKorimport.meta.env.VITE_APP_NETWORK. - Use
Network.TESTNETas 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
Networkenum. - Do not omit
networkwhen using custom endpoints – in v5.2+ useNetwork.CUSTOMwith 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
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/aptos-labs/aptos-agent-skills/ts-sdk-client">View ts-sdk-client on skillZs</a>