get_balance
Retrieve the native token balance (ETH, MATIC, etc.) for a wallet address or ENS name across 30+ EVM-compatible networks using the EVM MCP Server.
Instructions
Get the native token balance (ETH, MATIC, etc.) for an address
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | The wallet address or ENS name (e.g., '0x1234...' or 'vitalik.eth') to check the balance for | |
| network | No | Network name (e.g., 'ethereum', 'optimism', 'arbitrum', 'base', etc.) or chain ID. Supports all EVM-compatible networks. Defaults to Ethereum mainnet. |
Implementation Reference
- src/core/tools.ts:342-378 (registration)Registration of the 'get_balance' tool, including input schema, annotations, and the handler function that fetches and formats the balance using services.getETHBalance
server.registerTool( "get_balance", { description: "Get the native token balance (ETH, MATIC, etc.) for an address", inputSchema: { address: z.string().describe("The wallet address or ENS name"), network: z.string().optional().describe("Network name or chain ID. Defaults to Ethereum mainnet.") }, annotations: { title: "Get Native Token Balance", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true } }, async ({ address, network = "ethereum" }) => { try { const balance = await services.getETHBalance(address as Address, network); return { content: [{ type: "text", text: JSON.stringify({ network, address, balance: { wei: balance.wei.toString(), ether: balance.ether } }, null, 2) }] }; } catch (error) { return { content: [{ type: "text", text: `Error fetching balance: ${error instanceof Error ? error.message : String(error)}` }], isError: true }; } } ); - src/core/tools.ts:358-377 (handler)Handler function for 'get_balance' tool that calls the service, formats the response as JSON, and handles errors
async ({ address, network = "ethereum" }) => { try { const balance = await services.getETHBalance(address as Address, network); return { content: [{ type: "text", text: JSON.stringify({ network, address, balance: { wei: balance.wei.toString(), ether: balance.ether } }, null, 2) }] }; } catch (error) { return { content: [{ type: "text", text: `Error fetching balance: ${error instanceof Error ? error.message : String(error)}` }], isError: true }; } } - src/core/tools.ts:347-349 (schema)Input schema for 'get_balance' tool using Zod validation for address and optional network
address: z.string().describe("The wallet address or ENS name"), network: z.string().optional().describe("Network name or chain ID. Defaults to Ethereum mainnet.") }, - src/core/services/balance.ts:75-89 (helper)Core helper function getETHBalance that resolves ENS if needed, fetches balance using viem client.getBalance, and formats it to wei and ether units
export async function getETHBalance( addressOrEns: string, network = 'ethereum' ): Promise<{ wei: bigint; ether: string }> { // Resolve ENS name to address if needed const address = await resolveAddress(addressOrEns, network); const client = getPublicClient(network); const balance = await client.getBalance({ address }); return { wei: balance, ether: formatEther(balance) }; }