MCP Ethers Wallet

Instructions

Implementation Reference

• src/tools/erc20.ts:169-206 (handler)

  Primary MCP tool handler for getERC20Balance. Validates and maps parameters, retrieves balance via ethersService, fetches token symbol, formats and returns text response.

  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:157-207 (registration)

  MCP server tool registration for getERC20Balance, defining name, description, input schema, and handler reference. Called from tools index.

  server.tool(
    "getERC20Balance",
    "Get the ERC20 token balance for a specific address. Returns the balance amount along with the token symbol for easy reading.",
    {
      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/definitions/erc20.ts:31-55 (schema)

  Standalone JSON schema definition for getERC20Balance tool inputs, matching the registered schema (with tokenAddress instead of contractAddress).

  {
    name: "getERC20Balance",
    description: "Get the ERC20 token balance of a wallet",
    inputSchema: {
      type: "object",
      properties: {
        tokenAddress: {
          type: "string",
          description: "The address of the ERC20 token contract"
        },
        ownerAddress: {
          type: "string",
          description: "The Ethereum address whose balance to check"
        },
        provider: {
          type: "string",
          description: "Optional. Either a network name or custom RPC URL. Use getSupportedNetworks to get a list of supported networks."
        },
        chainId: {
          type: "number",
          description: "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."
        }
      },
      required: ["tokenAddress", "ownerAddress"]
    }

• src/tools/handlers/erc20.ts:80-119 (handler)

  Alternative handler implementation in dedicated handlers module, using Zod validation with friendly errors and common schemas.

  getERC20Balance: async (args: unknown) => {
    const schema = z.object({
      contractAddress: contractAddressSchema.optional(),
      tokenAddress: tokenAddressSchema,  // Deprecated
      ownerAddress: CommonSchemas.ethereumAddress.describe('Address to check balance for'),
      provider: providerSchema,
      chainId: chainIdSchema
    });
    
    try {
      // First validate with friendly errors
      const validatedParams = validateWithFriendlyErrors(
        schema,
        args,
        'Get ERC20 Balance'
      );
      
      // Then map deprecated parameters for backward compatibility
      const mapped = mapParameters(validatedParams);
      
      // Ensure we have a contract address (from either new or old parameter name)
      const contractAddr = mapped.contractAddress || validatedParams.tokenAddress;
      if (!contractAddr) {
        throw new Error('Contract address is required. Please provide either contractAddress or tokenAddress.');
      }
      
      const balance = await ethersService.getERC20Balance(validatedParams.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: `${validatedParams.ownerAddress} has a balance of ${balance} ${tokenInfo.symbol}`
        }]
      };
    } catch (error) {
      return createErrorResponse(error, 'getting token balance');
    }

• src/services/erc/erc20.ts:113-193 (helper)

  Core ERC20 balance retrieval helper function (getBalance) with comprehensive features: caching (30s TTL), rate limiting, ethers Contract balanceOf call, decimals-based formatting, detailed error handling and logging. Called internally by EthersService.getERC20Balance.

  export async function getBalance(
    ethersService: EthersService,
    tokenAddress: string,
    ownerAddress: string,
    provider?: string,
    chainId?: number
  ): Promise<string> {
    metrics.incrementCounter('erc20.getBalance');
    
    return timeAsync('erc20.getBalance', async () => {
      try {
        // Check rate limiting
        const identity = `${tokenAddress}:${ownerAddress}`;
        if (!rateLimiter.consume('token', identity)) {
          throw new ERC20Error('Rate limit exceeded for token operations');
        }
        
        // Create cache key
        const cacheKey = createTokenCacheKey(
          CACHE_KEYS.ERC20_BALANCE,
          tokenAddress,
          ownerAddress,
          chainId
        );
        
        // Check cache first
        const cachedBalance = balanceCache.get(cacheKey);
        if (cachedBalance) {
          return cachedBalance;
        }
        
        // Get provider from ethers service
        const ethersProvider = ethersService['getProvider'](provider, chainId);
        
        // Create contract instance
        const contract = new ethers.Contract(tokenAddress, ERC20_ABI, ethersProvider);
        
        // Get raw balance
        let balance;
        try {
          balance = await contract.balanceOf(ownerAddress);
        } catch (error: any) {
          // Check for empty response (0x) which often indicates a non-ERC20 contract
          if (error.code === 'BAD_DATA' && error.value === '0x') {
            logger.debug('Contract returned empty data for balanceOf call', { 
              tokenAddress,
              errorCode: error.code,
              errorValue: error.value,
              errorMessage: error.message
            });
            throw new ERC20Error(
              `Contract at ${tokenAddress} does not appear to be a valid ERC20 token. It returned empty data for the balanceOf call. Error code: ${error.code}`
            );
          }
          // Log other errors with full context
          logger.debug('Error calling balanceOf on contract', {
            tokenAddress,
            ownerAddress,
            errorCode: error.code,
            errorMessage: error.message,
            errorValue: error.value
          });
          // Re-throw the original error
          throw error;
        }
        
        // Get token decimals for formatting
        const tokenInfo = await getTokenInfo(ethersService, tokenAddress, provider, chainId);
        
        // Format the balance based on decimals
        const formattedBalance = ethers.formatUnits(balance, tokenInfo.decimals);
        
        // Cache result for future use (30 second TTL)
        balanceCache.set(cacheKey, formattedBalance, { ttl: 30000 });
        
        return formattedBalance;
      } catch (error) {
        logger.debug('Error getting ERC20 balance', { tokenAddress, ownerAddress, error });
        throw handleTokenError(error, 'Failed to get token balance');
      }
    });