How to Get the Balance of an Ethereum Account Using the Arbitrum MCP Server

Use the EthereumAccountClient class from the dewanshparashar/arbitrum-mcp repository to call getBalance(address) for raw wei values or getBalanceInEther(address) for decimal ether amounts.

The Arbitrum MCP (Multi-Chain Provider) server provides a lightweight JSON-RPC wrapper around Ethereum-compatible nodes. When you need to check how much ETH an address holds on Arbitrum, the EthereumAccountClient handles the underlying eth_getBalance RPC calls, returning values in wei by default with optional conversion to ether.

Understanding the EthereumAccountClient Architecture

The balance retrieval logic lives in src/clients/ethereum-account-client.ts. This class encapsulates the communication layer between your application and the Arbitrum MCP server endpoint.

When you instantiate the client, you provide the RPC URL of the running MCP server (typically http://localhost:8547 for local development). The client exposes two primary methods for balance queries: getBalance() for raw blockchain data and getBalanceInEther() for human-readable formatting.

Retrieving Account Balances with getBalance()

Getting Raw Wei Balance

The getBalance(address) method constructs a standard JSON-RPC payload with method: "eth_getBalance" and params: [address, "latest"]. It returns the balance as a hex-encoded string representing wei (the smallest denomination of ether).

According to the source code in src/clients/ethereum-account-client.ts (lines 36-39), the implementation forwards the request to an internal makeRpcCall helper that posts the payload to the MCP endpoint using fetch.

const client = new EthereumAccountClient("http://localhost:8547");
const weiBalance = await client.getBalance("0xAbC123...");
// Returns: "0xde0b6b3a7640000" (hex string)

Converting to Ether with getBalanceInEther()

For applications requiring decimal representation, getBalanceInEther(address) converts the hex result to a readable string. As implemented in lines 41-53 of ethereum-account-client.ts, this method:

1. Calls getBalance() to retrieve the raw hex value
2. Parses the hex string into a BigInt
3. Divides by 10^18 to convert wei to ether
4. Returns the formatted decimal string

const etherBalance = await client.getBalanceInEther("0xAbC123...");
// Returns: "1.0"

Complete Implementation Example

Below is a runnable TypeScript example demonstrating the full workflow from client instantiation to balance retrieval. This assumes you have the dewanshparashar/arbitrum-mcp package installed and an MCP server running locally.

// file: balance-demo.ts
import { EthereumAccountClient } from "./src/clients/ethereum-account-client.js";

// 1. Configure the MCP server RPC endpoint
const rpcUrl = "http://localhost:8547";
const client = new EthereumAccountClient(rpcUrl);

// 2. Specify the target Ethereum address
const address = "0xAbC123..."; // Replace with actual address

async function showBalances() {
  try {
    // Raw wei balance (hex string)
    const weiBalance = await client.getBalance(address);
    console.log(`Balance (wei, hex): ${weiBalance}`);

    // Human-readable ether balance
    const etherBalance = await client.getBalanceInEther(address);
    console.log(`Balance (ether): ${etherBalance}`);
  } catch (err) {
    console.error("Failed to fetch balance:", err);
  }
}

showBalances();

Execute the script after installing dependencies:

npm install
npx ts-node balance-demo.ts

Expected output:

Balance (wei, hex): 0xde0b6b3a7640000
Balance (ether): 1

Error Handling and Edge Cases

The makeRpcCall method in src/clients/ethereum-account-client.ts (lines 11-22) handles HTTP-level failures and JSON-RPC error responses. If the MCP server is unreachable or returns a non-200 status, the client throws an error with the HTTP status text.

For invalid Ethereum addresses, the underlying Arbitrum Nitro node (which the MCP server queries) will return a JSON-RPC error that propagates through the client. Always wrap balance calls in try-catch blocks when integrating into production applications.

Summary

• Instantiate EthereumAccountClient with the MCP server RPC URL (typically http://localhost:8547).
• Call getBalance(address) to retrieve the raw balance as a hex wei string via the eth_getBalance JSON-RPC method.
• Call getBalanceInEther(address) to receive a decimal string converted from wei to ether (dividing by 10^18).
• Reference src/clients/ethereum-account-client.ts for the implementation details of the RPC wrapper and conversion logic.

Frequently Asked Questions

What is the difference between getBalance and getBalanceInEther?

getBalance() returns the raw blockchain response: a hexadecimal string representing wei (the smallest ether denomination). getBalanceInEther() parses that hex value, converts it to a BigInt, divides by 10^18, and returns a human-readable decimal string. Use getBalance() for precise arithmetic or further processing; use getBalanceInEther() for display purposes.

Why does the Arbitrum MCP Server return balances in wei?

The Arbitrum MCP Server follows the Ethereum JSON-RPC specification, which defines eth_getBalance to return values in wei. This avoids floating-point precision issues common in financial calculations. The EthereumAccountClient maintains this standard for compatibility but provides the getBalanceInEther() convenience method for applications requiring decimal formatting.

How do I handle connection errors to the MCP server?

The makeRpcCall method in src/clients/ethereum-account-client.ts throws errors for HTTP failures (non-200 status codes) or JSON-RPC error responses. Wrap your getBalance() or getBalanceInEther() calls in try-catch blocks to handle network timeouts, unreachable endpoints, or invalid address errors returned by the underlying Arbitrum Nitro node.

Can I query historical balances with this client?

The current implementation in src/clients/ethereum-account-client.ts uses the "latest" block tag for all eth_getBalance calls. To query historical balances, you would need to modify the getBalance() method to accept an optional block number or block hash parameter and pass it as the second element in the RPC params array (e.g., params: [address, "0x1234..."]).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}