getWalletBalance

Retrieve the current Ether balance for any Ethereum wallet address across supported networks. Specify an address and optionally a network or chain ID to query blockchain data.

Input Schema

TableJSON Schema

Name	Required	Description
`address`	Yes	The Ethereum address to query
`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.
`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.

Implementation Reference

src/tools/core.ts:256-275 (handler)

Handler function that fetches the ETH balance for the given address using the selected provider's getBalance method, formats it to ETH and wei, and returns a text response. Uses ethersService for provider selection and handles errors.

async ({ address, provider, chainId }) => {
  try {
    // Get the balance in wei directly from the provider
    const selectedProvider = provider ? 
      ethersService.getProvider(provider, chainId) : 
      ethersService.provider;
      
    const balanceWei = await selectedProvider.getBalance(address);
    const balanceEth = ethers.formatEther(balanceWei);
    
    return {
      content: [{ 
        type: "text", 
        text: `Balance of ${address}: ${balanceEth} ETH (${balanceWei.toString()} wei)`
      }]
    };
  } catch (error) {
    return createErrorResponse(error, 'getting wallet balance');
  }
}

src/tools/core.ts:247-255 (schema)

Zod input schema for the getWalletBalance tool. Requires an Ethereum address; optional provider (network name or RPC URL) and chainId.

{
  address: addressSchema.describe(
    "The Ethereum address to query"
  ),
  provider: z.string().optional().describe(PROVIDER_DESCRIPTION),
  chainId: z.number().optional().describe(
    "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."
  )
},

src/tools/core.ts:245-276 (registration)

Registration of the getWalletBalance tool using server.tool() within the registerCoreTools function, including inline schema and handler.

server.tool(
  "getWalletBalance",
  {
    address: addressSchema.describe(
      "The Ethereum address to query"
    ),
    provider: z.string().optional().describe(PROVIDER_DESCRIPTION),
    chainId: z.number().optional().describe(
      "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."
    )
  },
  async ({ address, provider, chainId }) => {
    try {
      // Get the balance in wei directly from the provider
      const selectedProvider = provider ? 
        ethersService.getProvider(provider, chainId) : 
        ethersService.provider;
        
      const balanceWei = await selectedProvider.getBalance(address);
      const balanceEth = ethers.formatEther(balanceWei);
      
      return {
        content: [{ 
          type: "text", 
          text: `Balance of ${address}: ${balanceEth} ETH (${balanceWei.toString()} wei)`
        }]
      };
    } catch (error) {
      return createErrorResponse(error, 'getting wallet balance');
    }
  }
);

MCP Ethers Wallet