eth_getBalance

Returns the ZETA token balance of an account at a given block.

When to Use This Method

Use eth_getBalance to:

• Check ZETA Balance - Query native token balance
• Monitor Accounts - Track balance changes over time
• Verify Transactions - Confirm funds before sending
• Cross-Chain Operations - Check gas funds for omnichain calls
• Wallet Integration - Display user balances

Parameters

1. Address (required): 20 bytes - Address to check balance
2. Block Parameter (optional):
   • latest - Latest block (default)
   • earliest - Genesis block
   • pending - Pending state
   • Block number as hexadecimal

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

Returns

QUANTITY - ZETA balance in wei as hexadecimal.

• Type: Hexadecimal string
• Unit: Wei (1 ZETA = 10^18 wei)
• Format: 0x prefixed

Implementation Examples

cURL

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

JavaScript

// Using fetch
const response = await fetch('https://api-xdc-mainnet.n.dwellir.com/YOUR_API_KEY', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'eth_getBalance',
    params: [
      '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8',
      'latest'
    ],
    id: 1,
  }),
});

const data = await response.json();
const balanceWei = BigInt(data.result);
const balanceZeta = Number(balanceWei) / 1e18;
console.log('Balance:', balanceZeta, 'ZETA');

// Using ethers.js
import { ethers } from 'ethers';

const provider = new ethers.JsonRpcProvider('https://api-xdc-mainnet.n.dwellir.com/YOUR_API_KEY');
const balance = await provider.getBalance('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8');
console.log('ZETA Balance:', ethers.formatEther(balance));

// Using web3.js
import Web3 from 'web3';

const web3 = new Web3('https://api-xdc-mainnet.n.dwellir.com/YOUR_API_KEY');
const balanceWei = await web3.eth.getBalance('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8');
const balanceZeta = web3.utils.fromWei(balanceWei, 'ether');
console.log('Account balance:', balanceZeta, 'ZETA');

// Balance at specific block
const historicalBalance = await provider.getBalance(
  '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8',
  1000000 // Block number
);
console.log('Balance at block 1000000:', ethers.formatEther(historicalBalance));

Python

import requests
import json
from web3 import Web3

# Using requests
url = 'https://api-xdc-mainnet.n.dwellir.com/YOUR_API_KEY'
headers = {'Content-Type': 'application/json'}
payload = {
    'jsonrpc': '2.0',
    'method': 'eth_getBalance',
    'params': [
        '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8',
        'latest'
    ],
    'id': 1
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
result = response.json()
balance_wei = int(result['result'], 16)
balance_zeta = balance_wei / 10**18
print(f'Balance: {balance_zeta} ZETA')

# Using web3.py
w3 = Web3(Web3.HTTPProvider('https://api-xdc-mainnet.n.dwellir.com/YOUR_API_KEY'))
address = '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8'
balance_wei = w3.eth.get_balance(address)
balance_zeta = w3.from_wei(balance_wei, 'ether')
print(f'Account balance: {balance_zeta} ZETA')

# Check multiple addresses
addresses = [
    '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8',
    '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
]

for addr in addresses:
    balance = w3.from_wei(w3.eth.get_balance(addr), 'ether')
    print(f'{addr}: {balance} ZETA')

Example Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x56bc75e2d63100000"
}

Decoding: 0x56bc75e2d63100000 = 100,000,000,000,000,000,000 wei = 100 ZETA

Omnichain Balance Management

xdc enables unique cross-chain balance features:

Multi-Chain Asset Tracking

// Track balances across multiple chains from xdc
class OmnichainBalanceTracker {
  constructor(provider) {
    this.provider = provider;
    this.zrc20Contracts = new Map();
  }
  
  async getTotalBalance(address) {
    // Get native ZETA balance
    const zetaBalance = await this.provider.getBalance(address);
    
    // Get ZRC-20 balances (wrapped assets from other chains)
    const balances = {
      ZETA: ethers.formatEther(zetaBalance),
      'ETH.ETH': await this.getZRC20Balance(address, ZRC20_ETH),
      'BSC.BNB': await this.getZRC20Balance(address, ZRC20_BNB),
      'BTC.BTC': await this.getZRC20Balance(address, ZRC20_BTC)
    };
    
    return balances;
  }
  
  async getZRC20Balance(address, zrc20Address) {
    const abi = ['function balanceOf(address) view returns (uint256)'];
    const contract = new ethers.Contract(zrc20Address, abi, this.provider);
    const balance = await contract.balanceOf(address);
    return ethers.formatEther(balance);
  }
}

Common Use Cases

1. Wallet Balance Display

class WalletBalanceManager {
  constructor(provider) {
    this.provider = provider;
    this.balanceCache = new Map();
  }
  
  async getBalance(address, useCache = true) {
    const cacheKey = `balance-${address}`;
    
    // Check cache (valid for 10 seconds)
    if (useCache && this.balanceCache.has(cacheKey)) {
      const cached = this.balanceCache.get(cacheKey);
      if (Date.now() - cached.timestamp < 10000) {
        return cached.balance;
      }
    }
    
    // Fetch fresh balance
    const balanceWei = await this.provider.getBalance(address);
    const balanceZeta = ethers.formatEther(balanceWei);
    
    // Update cache
    this.balanceCache.set(cacheKey, {
      balance: balanceZeta,
      timestamp: Date.now()
    });
    
    return balanceZeta;
  }
  
  async formatBalance(address) {
    const balance = await this.getBalance(address);
    
    if (parseFloat(balance) === 0) {
      return '0 ZETA';
    } else if (parseFloat(balance) < 0.0001) {
      return '< 0.0001 ZETA';
    } else if (parseFloat(balance) > 1000000) {
      return `${(parseFloat(balance) / 1000000).toFixed(2)}M ZETA`;
    } else {
      return `${parseFloat(balance).toFixed(4)} ZETA`;
    }
  }
}

2. Insufficient Balance Detection

async function checkSufficientBalance(address, requiredAmount, gasBuffer = 0.1) {
  const balance = await provider.getBalance(address);
  const required = ethers.parseEther(requiredAmount.toString());
  const buffer = ethers.parseEther(gasBuffer.toString());
  const total = required + buffer;
  
  if (balance < total) {
    const shortage = ethers.formatEther(total - balance);
    throw new Error(
      `Insufficient balance. Need ${ethers.formatEther(total)} ZETA, ` +
      `have ${ethers.formatEther(balance)} ZETA. ` +
      `Short by ${shortage} ZETA`
    );
  }
  
  return {
    sufficient: true,
    balance: ethers.formatEther(balance),
    required: ethers.formatEther(total),
    surplus: ethers.formatEther(balance - total)
  };
}

3. Balance Change Monitor

class BalanceMonitor {
  constructor(provider) {
    this.provider = provider;
    this.subscriptions = new Map();
  }
  
  async watchBalance(address, callback, interval = 5000) {
    let lastBalance = await this.provider.getBalance(address);
    
    const checkBalance = setInterval(async () => {
      const currentBalance = await this.provider.getBalance(address);
      
      if (!currentBalance.eq(lastBalance)) {
        const change = currentBalance.sub(lastBalance);
        const changeZeta = ethers.formatEther(change);
        
        callback({
          address,
          previousBalance: ethers.formatEther(lastBalance),
          currentBalance: ethers.formatEther(currentBalance),
          change: changeZeta,
          direction: change.gt(0) ? 'increase' : 'decrease',
          timestamp: Date.now()
        });
        
        lastBalance = currentBalance;
      }
    }, interval);
    
    this.subscriptions.set(address, checkBalance);
    return () => this.stopWatching(address);
  }
  
  stopWatching(address) {
    const subscription = this.subscriptions.get(address);
    if (subscription) {
      clearInterval(subscription);
      this.subscriptions.delete(address);
    }
  }
}

4. Cross-Chain Gas Calculator

async function calculateCrossChainGas(destinationChainId, operation) {
  const address = await signer.getAddress();
  const balance = await provider.getBalance(address);
  
  // Calculate required ZETA for cross-chain operation
  const gasPrice = await provider.getGasPrice();
  const estimatedGas = BigInt(200000); // Base cross-chain gas
  const protocolFee = ethers.parseEther('0.01'); // xdc protocol fee
  
  // Destination chain gas (paid in ZETA)
  const destGasPrice = await getDestinationGasPrice(destinationChainId);
  const destGas = BigInt(100000);
  const destGasInZeta = convertToZeta(destGasPrice * destGas, destinationChainId);
  
  const totalRequired = (gasPrice * estimatedGas) + protocolFee + destGasInZeta;
  
  if (balance < totalRequired) {
    throw new Error(
      `Insufficient ZETA for cross-chain operation. ` +
      `Need ${ethers.formatEther(totalRequired)} ZETA`
    );
  }
  
  return {
    sufficient: true,
    balance: ethers.formatEther(balance),
    required: ethers.formatEther(totalRequired),
    breakdown: {
      xdcGas: ethers.formatEther(gasPrice * estimatedGas),
      protocolFee: ethers.formatEther(protocolFee),
      destinationGas: ethers.formatEther(destGasInZeta)
    }
  };
}

5. Historical Balance Analysis

async function analyzeBalanceHistory(address, blocks = 100) {
  const currentBlock = await provider.getBlockNumber();
  const history = [];
  
  for (let i = 0; i <= blocks; i += 10) {
    const blockNumber = currentBlock - (blocks - i);
    const balance = await provider.getBalance(address, blockNumber);
    const block = await provider.getBlock(blockNumber);
    
    history.push({
      block: blockNumber,
      timestamp: block.timestamp,
      balance: ethers.formatEther(balance)
    });
  }
  
  // Calculate statistics
  const balances = history.map(h => parseFloat(h.balance));
  const stats = {
    current: balances[balances.length - 1],
    highest: Math.max(...balances),
    lowest: Math.min(...balances),
    average: balances.reduce((a, b) => a + b, 0) / balances.length,
    volatility: calculateVolatility(balances)
  };
  
  return { history, stats };
}

Balance Precision

Wei Conversion

const units = {
  wei: '1',
  kwei: '1000',
  mwei: '1000000',
  gwei: '1000000000',
  szabo: '1000000000000',
  finney: '1000000000000000',
  ether: '1000000000000000000'
};

// Convert between units
function convertBalance(value, fromUnit, toUnit) {
  const weiValue = BigInt(value) * BigInt(units[fromUnit]);
  return weiValue / BigInt(units[toUnit]);
}

Best Practices

1. Always handle BigInt for wei values
2. Cache balance queries to reduce RPC calls
3. Use appropriate decimal precision for display
4. Check balance before transactions
5. Monitor balance changes for security

Error Codes

Code	Message	Description
-32600	Invalid Request	Invalid JSON
-32602	Invalid params	Invalid method parameters
-32603	Internal error	Internal JSON-RPC error
-32000	Invalid input	Invalid address format

Related Methods

• eth_accounts - Get available accounts
• eth_getTransactionCount - Get nonce
• eth_sendRawTransaction - Send ZETA
• eth_call - Read token balances