Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

SDK

balances

Read a wallet's on-chain balances. This is a plain read: no signer, no userOp, no relay. It works for any address (a Wallet you created or a bare 0x… address), including counterfactual wallets that haven't been deployed yet.

// `client` and `wallet` from earlier
const { native } = await client.balances({ wallet });
console.log(native); // bigint — native token balance in wei

Pass a bare address if that's all you have:

const { native } = await client.balances({
  wallet: "0xabc…" as `0x${string}`,
});

Target a specific chain when the client is configured with more than one:

import { createClient, BNB_TESTNET, SEPOLIA } from "@functornetwork/agentic-wallet";
 
const client = createClient({ chains: [BNB_TESTNET, SEPOLIA] });
 
// BNB testnet (the default — first chain)
const bnb = await client.balances({ wallet });
// Ethereum Sepolia
const sepolia = await client.balances({ wallet, chainId: 11155111 });

Parameters

client.balances(opts: ClientBalancesOptions): Promise<BalancesResult>;
 
type ClientBalancesOptions = {
  wallet: Wallet | Address;       // a Wallet object or a bare 0x… address
  chainId?: number;               // defaults to the client's default chain
};
 
type BalancesResult = {
  native: bigint;                 // native token balance in wei (tBNB on BNB, ETH on Sepolia)
};

Notes

  • Native only, for now. balances returns the native token balance. ERC-20 balances land alongside the v1 DeFi recipes (the recipes know which tokens matter per protocol).
  • No funds required. It's a read against the chain's public RPC, so it doesn't cost gas and doesn't need the wallet to be funded or deployed.
  • Units are wei. Use viem's formatEther to display it: formatEther(native).