# eth_getBalance - Arc RPC Method

Returns the balance of a given address on Arc.

> **Why Arc?** Build on Circle's stablecoin-native Layer 1 where USDC is the gas token and BFT consensus gives sub-second deterministic finality with USDC as the native gas token, sub-second irreversible finality, an EWMA-smoothed fee market with a 20 Gwei floor, and EIP-7708 Transfer logs for native value movement.

## When to Use This Method

`eth_getBalance` is fundamental for payment platforms, stablecoin issuers, exchange and treasury teams, and Solidity developers building on Arc:

- **Wallet applications**: Display user balances and enable balance-dependent operations on Arc
- **Transaction validation**: Verify accounts have sufficient funds before submitting transactions to Arc
- **DeFi monitoring**: Track collateral positions, liquidity pools, and TVL across crossborder settlement, merchant payments, institutional clearing, and USDC-denominated financial applications
- **Accounting and reconciliation**: Cross-reference on-chain balances against off-chain ledger entries for financial reporting

## Request Parameters

- `address` (`DATA, required`): 20-byte address to check balance for
- `blockParameter` (`QUANTITY|TAG, required`): Block number in hex, or "latest", "earliest", "pending", "safe", "finalized"

## Request Example

```json
{
  "jsonrpc": "2.0",
  "method": "eth_getBalance",
  "params": [
    "0x3600000000000000000000000000000000000000",
    "latest"
  ],
  "id": 1
}
```

## Response Fields

- `result` (`QUANTITY, required`): Integer of the current balance in wei (hexadecimal)

## Successful Response

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x1a055690d9db80000"
}
```

## Common Use Cases

### 1. Display Formatted Wallet Balance with Ether Conversion

Retrieve and display a human-readable balance for any address on Arc. Convert the wei result to ether client-side using your web3 library.

```javascript
import { JsonRpcProvider, formatEther } from 'ethers';

const provider = new JsonRpcProvider('https://api-arc-mainnet.n.dwellir.com/YOUR_API_KEY');

async function displayBalance(address) {
  const balanceWei = await provider.getBalance(address);
  const balance = formatEther(balanceWei);
  console.log(`Balance: ${balance} Arc`);
  return balance;
}

displayBalance('0x3600000000000000000000000000000000000000');
```

### 2. Monitor Whale Wallet Activity with Polling and Threshold Alerts

Poll a high-value wallet on Arc at regular intervals. Trigger an alert when the balance crosses a defined threshold, useful for tracking DeFi movements or exchange hot wallet activity.

```python
from web3 import Web3
import time

w3 = Web3(Web3.HTTPProvider('https://api-arc-mainnet.n.dwellir.com/YOUR_API_KEY'))
address = '0x3600000000000000000000000000000000000000'
threshold_wei = w3.to_wei(100, 'ether')

def monitor_balance():
    previous_balance = w3.eth.get_balance(address)
    while True:
        time.sleep(15)
        current_balance = w3.eth.get_balance(address)
        if abs(current_balance - previous_balance) > threshold_wei:
            print(f'Balance changed by more than 100 Arc')
        if current_balance > w3.to_wei(1000, 'ether'):
            print(f'Whale alert: wallet exceeds 1000 Arc')
        previous_balance = current_balance

monitor_balance()
```

### 3. Historical Balance Tracking Using Block Tags

Query an account's balance at a specific block height to build a historical balance timeline. This is essential for audit trails, tax reporting, and analyzing wallet behavior over time on Arc.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "math/big"

    "github.com/ethereum/go-ethereum/common"
    "github.com/ethereum/go-ethereum/ethclient"
)

func main() {
    client, _ := ethclient.Dial("https://api-arc-mainnet.n.dwellir.com/YOUR_API_KEY")

    address := common.HexToAddress("0x3600000000000000000000000000000000000000")

    // Query balance at a specific block number
    blockNumber := big.NewInt(1000000)
    historicalBalance, _ := client.BalanceAt(context.Background(), address, blockNumber)
    fmt.Printf("Historical balance at block 1,000,000: %s wei\n", historicalBalance.String())

    // Query latest balance for comparison
    currentBalance, _ := client.BalanceAt(context.Background(), address, nil)
    change := new(big.Int).Sub(currentBalance, historicalBalance)
    fmt.Printf("Balance change: %s wei\n", change.String())
}
```

## Best Practices

- **Cache balances with short TTL**: Set a 2-5 second cache duration for balance queries to reduce RPC calls while keeping data fresh enough for most UI use cases
- **Convert wei to ether client-side**: Use `formatEther` (ethers.js) or `fromWei` (web3.py) rather than relying on node-side conversion, which the JSON-RPC does not provide
- **Use `pending` tag cautiously**: Balances returned with the `pending` block tag may reflect unconfirmed state changes and differ from finalized on-chain values
- **For batch balance queries, use `eth_call` with multicall**: When querying balances for many addresses, bundle them through a multicall contract to reduce individual RPC round-trips

## USDC balances on Arc

Arc's native token is USDC, not ETH, and the same balance is exposed through two interfaces with different precision:

| Interface | Where you read it                                           | Decimals |
| --------- | ----------------------------------------------------------- | -------- |
| Native    | `eth_getBalance`, `msg.value`, `address.balance`            | 18       |
| ERC-20    | `balanceOf` on `0x3600000000000000000000000000000000000000` | 6        |

Divide the native value by 1012 to display it as USDC. These are not two assets and there is no WETH-style wrapper, so never add the two values together or pair them against each other in pool math.

Credit and record balances from the 18-decimal native value. The ERC-20 view truncates sub-USDC fractions, so crediting from `balanceOf` records less than was actually transferred. A `balanceOf` of `0` does not mean the account is empty: a residual native balance below 1012 wei truncates to zero in the 6-decimal view.

See Arc's [stablecoin native model](https://docs.arc.io/arc/concepts/stablecoin-native-model) for the full two-interface table.

## Code Examples

cURL
JavaScript
Python
Go

```bash
curl -X POST https://api-arc-mainnet.n.dwellir.com/YOUR_API_KEY \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getBalance",
    "params": [
      "0x3600000000000000000000000000000000000000",
      "latest"
    ],
    "id": 1
  }'
```

```javascript
import { JsonRpcProvider, formatEther } from 'ethers';

const provider = new JsonRpcProvider('https://api-arc-mainnet.n.dwellir.com/YOUR_API_KEY');

const address = '0x3600000000000000000000000000000000000000';
const balanceWei = await provider.getBalance(address);
const balance = formatEther(balanceWei);

console.log(`Balance: ${balance}`);

// Get balance at specific block
const historicalBalance = await provider.getBalance(address, 1000000);
console.log(`Historical balance: ${formatEther(historicalBalance)}`);
```

```python
from web3 import Web3

w3 = Web3(Web3.HTTPProvider('https://api-arc-mainnet.n.dwellir.com/YOUR_API_KEY'))

address = '0x3600000000000000000000000000000000000000'
balance_wei = w3.eth.get_balance(address)
balance = w3.from_wei(balance_wei, 'ether')

print(f'Balance: {balance}')

# Get balance at specific block
historical_balance = w3.eth.get_balance(address, block_identifier=1000000)
print(f'Historical balance: {w3.from_wei(historical_balance, "ether")}')
```

```go
package main

import (
    "context"
    "fmt"
    "log"
    "math/big"

    "github.com/ethereum/go-ethereum/common"
    "github.com/ethereum/go-ethereum/ethclient"
)

func main() {
    client, err := ethclient.Dial("https://api-arc-mainnet.n.dwellir.com/YOUR_API_KEY")
    if err != nil {
        log.Fatal(err)
    }

    address := common.HexToAddress("0x3600000000000000000000000000000000000000")
    balance, err := client.BalanceAt(context.Background(), address, nil)
    if err != nil {
        log.Fatal(err)
    }

    // Convert to ether
    fbalance := new(big.Float).SetInt(balance)
    ethValue := new(big.Float).Quo(fbalance, big.NewFloat(1e18))

    fmt.Printf("Balance: %f\n", ethValue)
}
```

## Related Methods

- [`eth_getCode`](https://www.dwellir.com/docs/arc/eth_getCode) - Get contract bytecode
- [`eth_getTransactionCount`](https://www.dwellir.com/docs/arc/eth_getTransactionCount) - Get account nonce
