get_token_balance_erc20

Instructions

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;