get_token_balance_erc20
Retrieve the ERC20 token balance for a specific address on Ethereum or compatible networks using the token contract 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 or chain ID. Defaults to Ethereum mainnet. | |
| tokenAddress | Yes | The ERC20 token contract address |
Implementation Reference
- src/core/tools.ts:381-422 (registration)Registers the MCP tool 'get_token_balance' for retrieving ERC20 token balances of an address on EVM networks."get_token_balance", { description: "Get the ERC20 token balance for an address", inputSchema: { address: z.string().describe("The wallet address or ENS name"), tokenAddress: z.string().describe("The ERC20 token contract address"), network: z.string().optional().describe("Network name or chain ID. Defaults to Ethereum mainnet.") }, annotations: { title: "Get ERC20 Token Balance", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true } }, async ({ address, tokenAddress, network = "ethereum" }) => { try { const balance = await services.getERC20Balance(tokenAddress as Address, address as Address, network); return { content: [{ type: "text", text: JSON.stringify({ network, tokenAddress, address, balance: { raw: balance.raw.toString(), formatted: balance.formatted, symbol: balance.token.symbol, decimals: balance.token.decimals } }, null, 2) }] }; } catch (error) { return { content: [{ type: "text", text: `Error fetching token balance: ${error instanceof Error ? error.message : String(error)}` }], isError: true }; } }
- src/core/tools.ts:397-422 (handler)The handler function executes the tool logic by calling services.getERC20Balance and formatting the response.async ({ address, tokenAddress, network = "ethereum" }) => { try { const balance = await services.getERC20Balance(tokenAddress as Address, address as Address, network); return { content: [{ type: "text", text: JSON.stringify({ network, tokenAddress, address, balance: { raw: balance.raw.toString(), formatted: balance.formatted, symbol: balance.token.symbol, decimals: balance.token.decimals } }, null, 2) }] }; } catch (error) { return { content: [{ type: "text", text: `Error fetching token balance: ${error instanceof Error ? error.message : String(error)}` }], isError: true }; } }
- src/core/tools.ts:382-395 (schema)Zod-based input schema and annotations defining parameters: address, tokenAddress, network (optional).{ description: "Get the ERC20 token balance for an address", inputSchema: { address: z.string().describe("The wallet address or ENS name"), tokenAddress: z.string().describe("The ERC20 token contract address"), network: z.string().optional().describe("Network name or chain ID. Defaults to Ethereum mainnet.") }, annotations: { title: "Get ERC20 Token Balance", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
- src/core/services/balance.ts:98-136 (helper)Core helper function that fetches ERC20 token balance using viem contract reads, including symbol and decimals.export async function getERC20Balance( tokenAddressOrEns: string, ownerAddressOrEns: string, network = 'ethereum' ): Promise<{ raw: bigint; formatted: string; token: { symbol: string; decimals: number; } }> { // 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: erc20Abi, client: publicClient, }); const [balance, symbol, decimals] = await Promise.all([ contract.read.balanceOf([ownerAddress]), contract.read.symbol(), contract.read.decimals() ]); return { raw: balance, formatted: formatUnits(balance, decimals), token: { symbol, decimals } }; }
- src/core/services/balance.ts:12-35 (helper)Minimal ERC20 ABI used for reading balanceOf, symbol, and decimals in getERC20Balance.// Standard ERC20 ABI (minimal for reading) const erc20Abi = [ { inputs: [], name: 'symbol', outputs: [{ type: 'string' }], stateMutability: 'view', type: 'function' }, { inputs: [], name: 'decimals', outputs: [{ type: 'uint8' }], stateMutability: 'view', type: 'function' }, { inputs: [{ type: 'address', name: 'account' }], name: 'balanceOf', outputs: [{ type: 'uint256' }], stateMutability: 'view', type: 'function' } ] as const;