Balances

The call

const balance = await provider.getBalance(address, "ethereum");

Every provider except Helius and Aptos implements it. Helius has no REST balance endpoint and Aptos has no explorer API at all, so both throw UnsupportedOperationError and their capabilities.balances is false.

The shape

interface Balance {
  address: string;
  chain: ChainKey;
  fetchedAt: string; // ISO, when the provider finished the read
  blockNumber: number | null; // the height the answer describes, when the explorer says
  blockHash: string | null;
  balance: string; // smallest unit, exact
  balanceFormatted: string; // decimal, exact
  funded?: string; // UTXO explorers only: cumulative received
  spent?: string; // UTXO explorers only: cumulative spent
  symbol: string; // ETH, BTC, AR…
}

balance is a string because a JavaScript number cannot hold 6.712150161831460931 ETH in wei without losing the tail. balanceFormatted is the same value with the decimal point in place, computed with formatWei(value, decimals) and nothing else. Neither is rounded.

fetchedAt is always there. blockNumber and blockHash are there when the explorer's answer names a block and null when it does not, so an unknown chain position is explicit instead of a zero that looks like genesis. Today only Blockchair passes a height through, from the context.state of its dashboard answer; every other provider's balance endpoint says nothing about a block, so both fields stay null there.

funded and spent come from explorers that keep cumulative totals: Mempool, Blockstream and Blockchair on the Bitcoin family, and Koios on Cardano. They are absent everywhere else rather than set to zero.

ENS

resolveEns("vitalik.eth") goes through public HTTP resolvers, no key and no keccak, and returns the address or null. resolveAddresses(input, chain) does the classification for you: an address or a hash passes through, a .eth name is resolved, and a name that does not resolve is a NotFoundError. The CLI, the tools and the docs worker all go through it, so explorers vitalik.eth and explorers 0xd8dA…6045 are the same read.

resolveAddresses also takes a list, up to twenty entries, which is what explorers_balance uses when an agent hands it several addresses at once.

Decimals

formatWei(value, decimals) defaults to 18. Bitcoin, Litecoin, Pepecoin and Blockstream amounts are 8, Solana 9, Arweave 12, Cardano 6, TON 9, TRON 6, Sui 9, eCash 2. The providers apply the right one, so balanceFormatted is always correct; the default matters only when you format balance yourself.

Reading ahead

The Explorer shows the full shape for any address. The landing walks through three addresses on three chains, recorded through the library and swapped for live answers as the worker replies.