WDK logoWDK documentation
StartWalletsDeFi & FiatAI & CLITools

Wallet Aptos Configuration

Configuration options for @tetherto/wdk-wallet-aptos.

Configure the Aptos wallet module with an Aptos fullnode REST endpoint. A provider is required for balance reads, fee quotes, transaction submission, normalized transaction lookup and waiting, and legacy receipt polling.

import WalletManagerAptos from '@tetherto/wdk-wallet-aptos'

const wallet = new WalletManagerAptos(seedPhrase, {
  provider: [
    'https://fullnode.mainnet.aptoslabs.com/v1',
    process.env.APTOS_FAILOVER_FULLNODE_URL
  ].filter(Boolean),
  retries: 3,
  txnExpirationSecs: 60,
  transactionMaxFee: 100000n,
  transferMaxFee: 100000n
})

Wallet Configuration

OptionTypeDescription
providerstring | AptosRpc | string[]Aptos fullnode REST API URL, an existing package AptosRpc instance, or an ordered URL list for failover. Required for chain operations.
chainIdnumberOptional chain ID. If omitted, the module fetches it from ledger info on first use.
retriesnumberFailover attempts when provider is an array. Defaults to 3.
txnExpirationSecsnumberTransaction expiration window measured from the current time. Defaults to 60.
transferMaxFeenumber | bigintOptional gas fee limit in octas for fungible asset transfer() calls.
transactionMaxFeenumber | bigintOptional gas fee limit in octas for native APT sendTransaction() and signTransaction().

An empty provider array behaves like no provider. Balance reads, quotes, transaction lookup and waiting, transaction signing, and transaction submission then fail because no fullnode is available.

The manager creates one REST client and reuses it across derived accounts and their read-only conversions. An existing AptosRpc is reused as-is; retries does not reconfigure that instance. AptosRpc is an internal package class, not an export you can import from the package root. Use the public URL or URL-array configuration shown above; the option does not accept a generic Aptos SDK client or a mixed array of URLs and clients.

Account Configuration

You can construct accounts directly when you need a specific derivation path.

import { WalletAccountAptos } from '@tetherto/wdk-wallet-aptos'

const account = new WalletAccountAptos(seedPhrase, "0'/0'/0'", {
  provider: 'https://fullnode.mainnet.aptoslabs.com/v1',
  transactionMaxFee: 100000n,
  transferMaxFee: 100000n
})

An address and provider are enough for balance reads and transaction tracking:

import { WalletAccountReadOnlyAptos } from '@tetherto/wdk-wallet-aptos'

const readOnlyAccount = new WalletAccountReadOnlyAptos('0x...', {
  provider: 'https://fullnode.mainnet.aptoslabs.com/v1'
})

Validate externally supplied addresses before construction. The read-only constructor stores the address verbatim and does not reject or normalize an invalid value.

Fee quotes simulate a transaction and message verification uses Ed25519, so those operations also require the matching 32-byte public key:

const readOnlyWithPublicKey = new WalletAccountReadOnlyAptos(
  '0x...',
  { provider: 'https://fullnode.mainnet.aptoslabs.com/v1' },
  publicKey
)

The constructor rejects a public key that does not derive the supplied address. Prefer account.toReadOnlyAccount() when you already have a writable account; it carries the matching public key and reuses the account's REST client.

Network Selection

Network selection is controlled by the fullnode URL and the transaction chain ID. If you provide chainId, it must match the configured fullnode. The module does not compare a supplied chain ID with ledger info before signing.

NetworkProvider URL
Mainnethttps://fullnode.mainnet.aptoslabs.com/v1
Testnethttps://fullnode.testnet.aptoslabs.com/v1

Derivation Paths

The module uses SLIP-0010 Ed25519 derivation. getAccount(index) derives:

m/44'/637'/index'/0'/0'

Use getAccountByPath(path) to provide a relative path after m/44'/637'/.

const account = await wallet.getAccountByPath("5'/0'/0'")

Every Aptos path segment must be hardened. A path segment without an apostrophe is invalid for this module's Ed25519 derivation.

The relative path must contain exactly three hardened indexes, such as "5'/0'/0'". The module normalizes leading zeros. For example, "05'/0'/0'" and "5'/0'/0'" resolve to the same cached account through the manager.

Fee Limit

Set transactionMaxFee for native APT sends and signing, and transferMaxFee for fungible asset transfers. Both limits use octas. A fresh simulation that exceeds the applicable limit throws MaximumFeeExceededError before signing. An estimate equal to the limit passes the fee check.

const wallet = new WalletManagerAptos(seedPhrase, {
  provider: 'https://fullnode.mainnet.aptoslabs.com/v1',
  transactionMaxFee: 100000n,
  transferMaxFee: 100000n
})

For a positive simulated gas unit price, the wallet also reduces the signed transaction’s maximum gas budget when necessary, so max_gas_amount * gas_unit_price stays within the limit. If the transaction needs more gas than that budget allows, execution can fail. Quotes estimate fees for review. The wallet runs a new simulation when you sign or send.

Security Notes

  • Keep seed phrases and seed bytes outside logs and client-visible error reporting.
  • Use trusted fullnode endpoints for production wallets.
  • Keep a supplied chainId consistent with every configured fullnode.
  • Set fee limits for native and fungible asset operations. Review quotes separately from the fee checks performed when signing.
  • Call dispose() on accounts and managers when they are no longer needed, but do not treat manager disposal as seed zeroization. The manager clears cached accounts and signers while retaining the manager's original seed buffer; release every manager and seed reference, and use a stronger isolation boundary when memory reclamation is required.

On this page