get_erc20_balance
Retrieve ERC20 token balances for a specific address on supported networks, including BSC, Ethereum, and others, by providing the token contract address and network details.
Instructions
Get ERC20 token balance for an address
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | The address to check balance for | |
| network | No | Network name (e.g. 'bsc', 'opbnb', 'ethereum', 'base', etc.) or chain ID. Supports others main popular networks. Defaults to BSC mainnet. | bsc |
| tokenAddress | Yes | The ERC20 token contract address |
Implementation Reference
- src/evm/services/balance.ts:46-86 (handler)The core handler function that resolves addresses, fetches ERC20 balance, symbol, and decimals from the blockchain, and formats the result.
export async function getERC20Balance( tokenAddressOrEns: string, ownerAddressOrEns: string, network = "ethereum" ): Promise<{ raw: bigint formatted: string symbol: string decimals: number network: string tokenAddress: Address ownerAddress: Address }> { // Resolve ENS names to addresses if needed const tokenAddress = await resolveAddress(tokenAddressOrEns, network) const ownerAddress = await resolveAddress(ownerAddressOrEns, network) const publicClient = getPublicClient(network) const contract = getContract({ address: tokenAddress, abi: ERC20_ABI, client: publicClient }) const [balance, symbol, decimals] = await Promise.all([ contract.read.balanceOf([ownerAddress]) as Promise<bigint>, contract.read.symbol() as Promise<string>, contract.read.decimals() as Promise<number> ]) return { raw: balance, formatted: formatUnits(balance, decimals), symbol, decimals, network, tokenAddress, ownerAddress } } - src/evm/modules/tokens/tools.ts:60-82 (registration)Registers the 'get_erc20_balance' MCP tool, including input schema validation with Zod and a wrapper handler that calls the core getERC20Balance service.
server.tool( "get_erc20_balance", "Get ERC20 token balance for an address", { tokenAddress: z.string().describe("The ERC20 token contract address"), address: z.string().describe("The address to check balance for"), network: defaultNetworkParam, privateKey: privateKeyParam }, async ({ network, tokenAddress, address, privateKey }) => { try { const res = await services.getERC20Balance( tokenAddress as Address, address || privateKeyToAccount(privateKey as Hex).address, network ) return mcpToolRes.success(res) } catch (error) { return mcpToolRes.error(error, "fetching ERC20 token balance") } } )