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

> Learn how to get the balance of an Ethereum account using the Arbitrum MCP Server with clear examples and code snippets from the dewanshparashar/arbitrum-mcp repository.

- Repository: [Dewansh/arbitrum-mcp](https://github.com/dewanshparashar/arbitrum-mcp)
- Tags: how-to-guide
- Published: 2026-02-28

---

**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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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`.

```typescript
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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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

```typescript
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.

```typescript
// 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:

```bash
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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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..."]`).