Skip to main content

Query address balances

Once you've connected a wallet to a network, you can query its on-chain balance. Connect using cg.connect() and call .addressBalance().

Example usage​

import { importWallet, ChainGate } from 'chaingate'

const wallet = importWallet({ phrase: 'some bip39 phrase ...' })
const cg = new ChainGate({ apiKey: 'your-api-key' })

const ethereum = cg.connect(cg.networks.ethereum, wallet)
const { address, confirmed, unconfirmed } = await ethereum.addressBalance()

console.log('Address:', address)
console.log('Confirmed balance:', confirmed.base().toString(), confirmed.symbol)
console.log('Unconfirmed balance:', unconfirmed.base().toString(), unconfirmed.symbol)

// Convert to fiat
const confirmedUsd = await confirmed.toCurrency('usd')
console.log('Confirmed balance (USD):', confirmedUsd)

Confirmed vs. unconfirmed​

  • confirmed: The fully confirmed (on-chain) portion of your funds. Generally considered spendable.
  • unconfirmed: Funds awaiting sufficient confirmations or still in the mempool. Not all blockchains differentiate this, so unconfirmed might be 0 in some networks.

Understanding the balance values​

The returned balance includes confirmed and unconfirmed Amount objects. Each provides:

  • .base() — Value in base units as a Decimal (e.g., 0.005 ETH).
  • .min() — Value in minimal units as a bigint (e.g., 5000000000000000n wei).
  • .symbol — The currency symbol (e.g., 'ETH', 'BTC').
  • .name — Human-readable name (e.g., 'Ether', 'Bitcoin').
  • .toCurrency(fiat) — (async) Converts the amount to the given fiat currency at current market rates.

Example​

console.log(confirmed.base().toString()) // "0.005"
console.log(confirmed.min().toString())  // "5000000000000000"
console.log(confirmed.symbol)            // "ETH"

const eurValue = await confirmed.toCurrency('eur')
console.log(eurValue) // "14.89"

Checking a different address index​

For HD wallets, you can check the balance at a different address index:

const { confirmed } = await ethereum.addressBalance({ index: 1 })

Supported fiat currencies​

You can convert balances into more than 120 fiat currencies using their standard 3-letter codes:

usd, eur, gbp, jpy, cny, aud, cad, chf, inr, brl, mxn, and many more.

const gbpValue = await confirmed.toCurrency('gbp')
console.log(gbpValue) // "12.45"

Key points​

  • Confirmed & Unconfirmed: Some networks use a concept of "unconfirmed" funds. Others may report 0 for unconfirmed.
  • One wallet, multiple networks: Connect the same wallet to different networks and call .addressBalance() on each.
  • Easy formatting: The Amount class provides .base(), .min(), .symbol, and .toCurrency() for display.
  • Live data: Each call queries the blockchain, so the data is always up to date.
  • Fiat conversion: Use .toCurrency('usd'), .toCurrency('eur'), etc.