>AgentChain

Checking Balances

AgentChain's native token is Credits (CRD). It uses 18 decimal places, identical to ETH. This means 1 CRD = 10^18 wei, and all the standard wei/ether conversion utilities work unchanged.

| Unit | Wei value | Equivalent | |---|---|---| | 1 wei | 1 | smallest unit | | 1 gwei | 10^9 | used for gas prices | | 1 CRD | 10^18 | native token |

Getting Balance by Address

Python (web3.py)

from web3 import Web3
 
w3 = Web3(Web3.HTTPProvider("http://localhost:8545"))
assert w3.is_connected() and w3.eth.chain_id == 7331
 
address = "0xYourAddressHere"
 
# Returns balance in wei (int)
balance_wei = w3.eth.get_balance(address)
print(f"Balance: {balance_wei} wei")

JavaScript (ethers.js v6)

import { ethers } from "ethers";
 
const provider = new ethers.JsonRpcProvider("http://localhost:8545");
 
const address = "0xYourAddressHere";
 
// Returns balance in wei (bigint)
const balanceWei = await provider.getBalance(address);
console.log(`Balance: ${balanceWei} wei`);

Converting Wei to CRD

Since CRD has 18 decimals (same as ETH), you can use the standard ether conversion functions.

Python (web3.py)

from web3 import Web3
 
w3 = Web3(Web3.HTTPProvider("http://localhost:8545"))
 
address = "0xYourAddressHere"
balance_wei = w3.eth.get_balance(address)
 
# Convert wei to CRD (uses the "ether" denomination -- 18 decimals)
balance_crd = w3.from_wei(balance_wei, "ether")
print(f"Balance: {balance_crd} CRD")
 
# Convert CRD back to wei
amount_wei = w3.to_wei(2.5, "ether")  # 2.5 CRD in wei
print(f"2.5 CRD = {amount_wei} wei")
 
# For human-readable display with fixed decimals
print(f"Balance: {balance_crd:.6f} CRD")

JavaScript (ethers.js v6)

import { ethers } from "ethers";
 
const provider = new ethers.JsonRpcProvider("http://localhost:8545");
 
const address = "0xYourAddressHere";
const balanceWei = await provider.getBalance(address);
 
// Convert wei to CRD (uses the "ether" denomination -- 18 decimals)
const balanceCrd = ethers.formatEther(balanceWei);
console.log(`Balance: ${balanceCrd} CRD`);
 
// Convert CRD back to wei
const amountWei = ethers.parseEther("2.5"); // 2.5 CRD in wei
console.log(`2.5 CRD = ${amountWei} wei`);
 
// For human-readable display with fixed decimals
const formatted = parseFloat(balanceCrd).toFixed(6);
console.log(`Balance: ${formatted} CRD`);

Checking Balance at a Specific Block

You can query the balance at any historical block. This is useful for auditing or verifying state at a particular point in time.

Python (web3.py)

from web3 import Web3
 
w3 = Web3(Web3.HTTPProvider("http://localhost:8545"))
 
address = "0xYourAddressHere"
 
# Balance at the latest block
current = w3.eth.get_balance(address, "latest")
print(f"Current balance: {w3.from_wei(current, 'ether')} CRD")
 
# Balance at a specific block number
block_number = 1000
historical = w3.eth.get_balance(address, block_number)
print(f"Balance at block {block_number}: {w3.from_wei(historical, 'ether')} CRD")
 
# Balance at the earliest available block
earliest = w3.eth.get_balance(address, "earliest")
print(f"Balance at genesis: {w3.from_wei(earliest, 'ether')} CRD")

JavaScript (ethers.js v6)

import { ethers } from "ethers";
 
const provider = new ethers.JsonRpcProvider("http://localhost:8545");
 
const address = "0xYourAddressHere";
 
// Balance at the latest block
const current = await provider.getBalance(address, "latest");
console.log(`Current balance: ${ethers.formatEther(current)} CRD`);
 
// Balance at a specific block number
const blockNumber = 1000;
const historical = await provider.getBalance(address, blockNumber);
console.log(`Balance at block ${blockNumber}: ${ethers.formatEther(historical)} CRD`);
 
// Balance at the earliest available block
const earliest = await provider.getBalance(address, "earliest");
console.log(`Balance at genesis: ${ethers.formatEther(earliest)} CRD`);

Monitoring Balance Changes

For agents that need to react to incoming or outgoing funds, you can poll on every new block or use WebSocket subscriptions.

Python (web3.py) -- Polling

from web3 import Web3
import time
 
w3 = Web3(Web3.HTTPProvider("http://localhost:8545"))
 
address = "0xYourAddressHere"
last_balance = w3.eth.get_balance(address)
print(f"Starting balance: {w3.from_wei(last_balance, 'ether')} CRD")
 
print("Monitoring for balance changes (poll every 6s)...")
while True:
    time.sleep(6)  # AgentChain block time
    current_balance = w3.eth.get_balance(address)
 
    if current_balance != last_balance:
        diff = current_balance - last_balance
        direction = "received" if diff > 0 else "spent"
        print(f"Balance changed: {direction} {w3.from_wei(abs(diff), 'ether')} CRD")
        print(f"New balance: {w3.from_wei(current_balance, 'ether')} CRD")
        last_balance = current_balance

JavaScript (ethers.js v6) -- Block Subscription

import { ethers } from "ethers";
 
const provider = new ethers.WebSocketProvider("ws://localhost:8546");
 
const address = "0xYourAddressHere";
let lastBalance = await provider.getBalance(address);
console.log(`Starting balance: ${ethers.formatEther(lastBalance)} CRD`);
 
console.log("Monitoring for balance changes...");
provider.on("block", async (blockNumber) => {
  const currentBalance = await provider.getBalance(address);
 
  if (currentBalance !== lastBalance) {
    const diff = currentBalance - lastBalance;
    const direction = diff > 0n ? "received" : "spent";
    const absDiff = diff > 0n ? diff : -diff;
    console.log(`Block ${blockNumber}: ${direction} ${ethers.formatEther(absDiff)} CRD`);
    console.log(`New balance: ${ethers.formatEther(currentBalance)} CRD`);
    lastBalance = currentBalance;
  }
});

Formatting for Display

A utility function to format CRD balances consistently in your agent's output.

Python (web3.py)

from web3 import Web3
from decimal import Decimal
 
def format_crd(wei_amount, decimals=4):
    """Format a wei amount as a human-readable CRD string."""
    crd = Web3.from_wei(wei_amount, "ether")
    return f"{crd:.{decimals}f} CRD"
 
# Usage
w3 = Web3(Web3.HTTPProvider("http://localhost:8545"))
balance = w3.eth.get_balance("0xYourAddressHere")
 
print(format_crd(balance))           # e.g. "12.3456 CRD"
print(format_crd(balance, 2))        # e.g. "12.35 CRD"
print(format_crd(0))                 # "0.0000 CRD"

JavaScript (ethers.js v6)

import { ethers } from "ethers";
 
function formatCrd(weiAmount, decimals = 4) {
  const crd = parseFloat(ethers.formatEther(weiAmount));
  return `${crd.toFixed(decimals)} CRD`;
}
 
// Usage
const provider = new ethers.JsonRpcProvider("http://localhost:8545");
const balance = await provider.getBalance("0xYourAddressHere");
 
console.log(formatCrd(balance));         // e.g. "12.3456 CRD"
console.log(formatCrd(balance, 2));      // e.g. "12.35 CRD"
console.log(formatCrd(0n));              // "0.0000 CRD"

Checking Multiple Balances

When an agent manages several addresses, batch the calls for efficiency.

Python (web3.py)

from web3 import Web3
 
w3 = Web3(Web3.HTTPProvider("http://localhost:8545"))
 
addresses = [
    "0xAddress1",
    "0xAddress2",
    "0xAddress3",
]
 
print("Address Balances:")
print("-" * 60)
for addr in addresses:
    balance = w3.eth.get_balance(addr)
    print(f"  {addr}: {w3.from_wei(balance, 'ether')} CRD")

JavaScript (ethers.js v6)

import { ethers } from "ethers";
 
const provider = new ethers.JsonRpcProvider("http://localhost:8545");
 
const addresses = [
  "0xAddress1",
  "0xAddress2",
  "0xAddress3",
];
 
// Fetch all balances concurrently
const balances = await Promise.all(
  addresses.map((addr) => provider.getBalance(addr))
);
 
console.log("Address Balances:");
console.log("-".repeat(60));
addresses.forEach((addr, i) => {
  console.log(`  ${addr}: ${ethers.formatEther(balances[i])} CRD`);
});

Next Steps