erc20_balanceOf
Check the balance of a specific ERC20 token for any Ethereum address. Provide the token contract address and owner address, with optional network details, to retrieve accurate token holdings data.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| chainId | No | Optional. The chain ID to use. If provided with a named network and they don't match, the RPC's chain ID will be used. | |
| ownerAddress | Yes | The Ethereum address whose balance to check | |
| provider | No | Optional. Either a network name or custom RPC URL. Use getAllNetworks to see available networks and their details, or getNetwork to get info about a specific network. You can use any network name returned by these tools as a provider value. | |
| tokenAddress | Yes | The address of the ERC20 token contract |
Implementation Reference
- src/tools/erc20.ts:223-261 (handler)The handler function executing the tool logic for erc20_balanceOf. Maps parameters, fetches balance and token info via EthersService, formats response with symbol or error.async (params) => { // Map deprecated parameters const mapped = mapParameters(params); try { const contractAddr = mapped.contractAddress || params.tokenAddress; if (!contractAddr) { throw new Error('Either contractAddress or tokenAddress must be provided'); } const balance = await ethersService.getERC20Balance( mapped.ownerAddress, contractAddr, mapped.provider, mapped.chainId ); // Get token info to format the response const tokenInfo = await ethersService.getERC20TokenInfo( contractAddr, mapped.provider, mapped.chainId ); return { content: [{ type: "text", text: `${mapped.ownerAddress} has a balance of ${balance} ${tokenInfo.symbol}` }] }; } catch (error) { return { isError: true, content: [{ type: "text", text: `Error getting token balance: ${error instanceof Error ? error.message : String(error)}` }] }; } }
- src/tools/erc20.ts:214-222 (schema)Input schema using Zod for validating parameters like contractAddress, ownerAddress, provider for the erc20_balanceOf tool.{ contractAddress: contractAddressSchema, tokenAddress: tokenAddressSchema.optional(), // Deprecated ownerAddress: z.string().describe( "The Ethereum address whose balance to check" ), provider: providerSchema, chainId: chainIdSchema },
- src/tools/erc20.ts:211-262 (registration)Registration of the erc20_balanceOf tool using server.tool() within registerERC20Tools function, including name, description, schema, and handler.server.tool( "erc20_balanceOf", "Get the ERC20 token balance for a specific address. Alternative naming for compatibility with MCP client tests.", { contractAddress: contractAddressSchema, tokenAddress: tokenAddressSchema.optional(), // Deprecated ownerAddress: z.string().describe( "The Ethereum address whose balance to check" ), provider: providerSchema, chainId: chainIdSchema }, async (params) => { // Map deprecated parameters const mapped = mapParameters(params); try { const contractAddr = mapped.contractAddress || params.tokenAddress; if (!contractAddr) { throw new Error('Either contractAddress or tokenAddress must be provided'); } const balance = await ethersService.getERC20Balance( mapped.ownerAddress, contractAddr, mapped.provider, mapped.chainId ); // Get token info to format the response const tokenInfo = await ethersService.getERC20TokenInfo( contractAddr, mapped.provider, mapped.chainId ); return { content: [{ type: "text", text: `${mapped.ownerAddress} has a balance of ${balance} ${tokenInfo.symbol}` }] }; } catch (error) { return { isError: true, content: [{ type: "text", text: `Error getting token balance: ${error instanceof Error ? error.message : String(error)}` }] }; } } );
- src/tools/index.ts:24-24 (registration)Top-level registration invocation in registerAllTools that calls registerERC20Tools, thereby registering erc20_balanceOf.registerERC20Tools(server, ethersService);