ethereum_getTokenBalance

Instructions

Implementation Reference

• src/index.ts:168-214 (handler)

  The core handler function that implements the ethereum_getTokenBalance tool logic. It extracts parameters, creates an ERC20 contract instance using ethers.js, fetches balance, decimals, and symbol in parallel, formats the balance, and returns the result in MCP format. Handles errors gracefully.

  private async handleGetTokenBalance(request: any) {
    try {
      const address = request.params.arguments?.address;
      const tokenAddress = request.params.arguments?.token;
  
      if (!address || !tokenAddress) {
        throw new Error("Address and token address are required");
      }
  
      // Create contract instance
      const tokenContract = new ethers.Contract(
        tokenAddress,
        ERC20_ABI,
        this.provider
      );
  
      // Get decimals and balance
      const [decimals, balance, symbol] = await Promise.all([
        tokenContract.decimals(),
        tokenContract.balanceOf(address),
        tokenContract.symbol(),
      ]);
  
      const formattedBalance = ethers.formatUnits(balance, decimals);
  
      return {
        content: [
          {
            type: "text",
            text: `Token Balance for ${address}: ${formattedBalance} ${symbol}`,
          },
        ],
      };
    } catch (error: unknown) {
      console.error("Error getting token balance:", error);
      const errorMessage =
        error instanceof Error ? error.message : "Unknown error occurred";
      return {
        content: [
          {
            type: "text",
            text: `Error getting token balance: ${errorMessage}`,
          },
        ],
      };
    }
  }

• src/index.ts:82-95 (schema)

  Input schema validation for the ethereum_getTokenBalance tool, defining required 'address' and 'token' string parameters.

  inputSchema: {
    type: "object",
    properties: {
      address: {
        type: "string",
        description: "Ethereum address or ENS name",
      },
      token: {
        type: "string",
        description: "Token contract address or ENS name",
      },
    },
    required: ["address", "token"],
  },

• src/index.ts:79-96 (registration)

  Tool registration in the ListToolsRequestSchema handler, defining name, description, and input schema for ethereum_getTokenBalance.

  {
    name: "ethereum_getTokenBalance",
    description: "Get ERC20 token balance for an address",
    inputSchema: {
      type: "object",
      properties: {
        address: {
          type: "string",
          description: "Ethereum address or ENS name",
        },
        token: {
          type: "string",
          description: "Token contract address or ENS name",
        },
      },
      required: ["address", "token"],
    },
  },

• src/index.ts:154-155 (registration)

  Dispatch registration in the CallToolRequestSchema switch statement, routing ethereum_getTokenBalance calls to the handler method.

  case "ethereum_getTokenBalance":
    return await this.handleGetTokenBalance(request);

• src/index.ts:16-22 (helper)

  ERC20 ABI fragment used by the ethereum_getTokenBalance handler for contract interactions (balanceOf, decimals, symbol).

  const ERC20_ABI = [
    "function name() view returns (string)",
    "function symbol() view returns (string)",
    "function decimals() view returns (uint8)",
    "function totalSupply() view returns (uint256)",
    "function balanceOf(address) view returns (uint256)",
  ];