eth_getBalance

Instructions

Implementation Reference

• src/index.ts:194-239 (handler)

  Full server.tool registration which defines and registers the handler function for eth_getBalance. The handler performs an RPC call to eth_getBalance, formats the balance from wei to ETH, handles errors, and returns a formatted text response.

  server.tool(
    "eth_getBalance",
    "Returns the balance of the account of given address",
    {
      address: z.string().describe("Address to check balance for"),
      blockNumber: z
        .string()
        .optional()
        .default("latest")
        .describe("Block number or 'latest', 'earliest', 'pending'"),
    },
    async ({ address, blockNumber }) => {
      try {
        const result = await makeRPCCall("eth_getBalance", [
          address,
          blockNumber,
        ]);
        const balance = ethers.formatEther(result);
        return {
          content: [
            {
              type: "text",
              text: formatResponse(
                {
                  address,
                  balance_wei: result,
                  balance_eth: balance,
                  block: blockNumber,
                },
                "Account Balance",
              ),
            },
          ],
        };
      } catch (error: any) {
        return {
          content: [
            {
              type: "text",
              text: `Error: ${error.message}`,
            },
          ],
        };
      }
    },
  );

• src/index.ts:197-204 (schema)

  Input schema using Zod for validating address (required string) and blockNumber (optional string, defaults to 'latest').

  {
    address: z.string().describe("Address to check balance for"),
    blockNumber: z
      .string()
      .optional()
      .default("latest")
      .describe("Block number or 'latest', 'earliest', 'pending'"),
  },

• src/index.ts:89-96 (helper)

  Generic helper function used by the handler to send the 'eth_getBalance' RPC method to the Ethers JsonRpcProvider.

  async function makeRPCCall(method: string, params: any[] = []): Promise<any> {
    try {
      const result = await provider.send(method, params);
      return result;
    } catch (error: any) {
      throw new Error(`RPC call failed: ${error.message}`);
    }
  }

• src/index.ts:32-57 (helper)

  Helper function used to format the tool's response as structured markdown text.

  function formatResponse(data: any, title: string): string {
    let result = `**${title}**\n\n`;
  
    if (typeof data === "object" && data !== null) {
      if (Array.isArray(data)) {
        // Handle arrays
        result += `**Count:** ${data.length}\n\n`;
        data.forEach((item, index) => {
          result += `**${index + 1}.**\n`;
          if (typeof item === "object" && item !== null) {
            result += formatObject(item, "  ");
          } else {
            result += `  ${item}\n`;
          }
          result += "\n";
        });
      } else {
        // Handle objects
        result += formatObject(data, "");
      }
    } else {
      result += `${data}\n`;
    }
  
    return result;
  }

• src/index.ts:194-239 (registration)

  Explicit registration of the tool with the MCP server instance.

  server.tool(
    "eth_getBalance",
    "Returns the balance of the account of given address",
    {
      address: z.string().describe("Address to check balance for"),
      blockNumber: z
        .string()
        .optional()
        .default("latest")
        .describe("Block number or 'latest', 'earliest', 'pending'"),
    },
    async ({ address, blockNumber }) => {
      try {
        const result = await makeRPCCall("eth_getBalance", [
          address,
          blockNumber,
        ]);
        const balance = ethers.formatEther(result);
        return {
          content: [
            {
              type: "text",
              text: formatResponse(
                {
                  address,
                  balance_wei: result,
                  balance_eth: balance,
                  block: blockNumber,
                },
                "Account Balance",
              ),
            },
          ],
        };
      } catch (error: any) {
        return {
          content: [
            {
              type: "text",
              text: `Error: ${error.message}`,
            },
          ],
        };
      }
    },
  );