Base Address Balance API

To rank a token's holders, see the Token Holders API (EVM.Holders).

The Balances API returns current and historical token balances for an address on Base. To return only non-zero balances, add Amount(selectWhere: { gt: "0" }) on the Balance field (not in where). Use dataset: combined or dataset: archive as follows:

Dataset	When to use
combined	Latest balances. Queries realtime and archive databases and merges results.
archive	Historical snapshots with Block.Date, and balances for addresses not recently active.

Examples: All Token Balances · Native ETH (Base) · Balance on a Date · Specific Token · Holder Snapshot

Balance of an Address

Returns token balances for a wallet address. Use Amount(selectWhere: { gt: "0" }) to exclude zero balances.

Run in IDE

{
  EVM(network: base, dataset: combined) {
    Balances(
      where: {
        Balance: {
          Address: { is: "0xbaed383ede0e5d9d72430661f3285daa77e9439f" }
        }
      }
    ) {
      Currency {
        Symbol
        SmartContract
      }
      Balance {
        Amount(selectWhere: { gt: "0" })
        Address
      }
    }
  }
}

Native ETH (Base) Balance

Returns the native ETH balance for a wallet on Base (not ERC-20 tokens). Filter with Currency: { Native: true } instead of a token contract address.

Run in IDE

{
  EVM(network: base, dataset: combined) {
    Balances(
      where: {
        Balance: {
          Address: { is: "0xbaed383ede0e5d9d72430661f3285daa77e9439f" }
        }
        Currency: { Native: true }
      }
    ) {
      Currency {
        Symbol
        SmartContract
      }
      Balance {
        Amount(selectWhere: { gt: "0" })
        Address
      }
    }
  }
}

Parameters

• network: base: Base mainnet.
• dataset: combined: Merges realtime and archive data for the latest balance state.
• Balance.Address: Wallet address to query.
• Currency.Native: true: Native ETH on Base only (see Native ETH (Base) Balance).

Returned fields

• Currency.Symbol, Currency.SmartContract: Token metadata.
• Balance.Amount, Balance.AmountInUSD: Token balance and USD value (use selectWhere to filter non-zero amounts).

Balance on a Specific Date

Use Block.Date.till for a point-in-time snapshot. Use dataset: archive for historical dates and addresses not recently active.

Run in IDE

query {
  EVM(network: base, dataset: archive) {
    Balances(
      where: {
        Block: { Date: { till: "2026-05-01" } }
        Balance: {
          Address: { is: "0xbaed383ede0e5d9d72430661f3285daa77e9439f" }
        }
      }
    ) {
      Currency {
        Symbol
        SmartContract
      }
      Balance {
        Amount(selectWhere: { gt: "0" })
        AmountInUSD
        Address
      }
    }
  }
}

Balance for a Specific Token

Add a Currency.SmartContract filter. Always use the contract address, not the token name. Use 0x for native ETH on Base, or the ERC-20 contract address for a token.

Run in IDE

query {
  EVM(network: base, dataset: combined) {
    Balances(
      where: {
        Balance: {
          Address: { is: "0xbaed383ede0e5d9d72430661f3285daa77e9439f" }
        }
        Currency: {
          SmartContract: { is: "0x09403da25c27024c7418fc942dda8ffa70bc7c62" }
        }
      }
    ) {
      Currency {
        Symbol
        SmartContract
      }
      Balance {
        Amount(selectWhere: { gt: "0" })
        AmountInUSD
        Address
      }
    }
  }
}

Token Holder Snapshot

The number of unique holders, token supply, and Gini coefficient for the balance amount before a specific timestamp can be derived using the query below. These stats provide a useful holder snapshot for any given time.

Run in IDE

Click to expand GraphQL query

query MyQuery($network: evm_network!, $address: String!) {
  EVM(network: $network, dataset: combined) {
    Holders(
      where: {Currency: {SmartContract: {is: $address}}, Balance: {Amount: {gt: "0"}, LastChangeTime: {till: "2026-06-30T00:00:00Z"}}}
    ) {
      Balance {
        LastChangeTime(maximum: Balance_LastChangeTime)
      }
      holders: uniq(of: Holder_Address)
      supply: sum(of: Balance_Amount)
      gini(of: Balance_Amount)
    }
  }
}

{
  "network": "base",
  "address": "0x940181a94A35A4569E4529A3CDfB74e38FD98631"
}

Balance History by Date

Returns balance snapshots over time for an address. Use dataset: archive. Order by Block_Date descending and use limit to paginate. Add Currency.SmartContract under Currency to filter by a specific token.

Run in IDE

query {
  EVM(network: base, dataset: archive) {
    Balances(
      where: {
        Balance: {
          Address: { is: "0xbaed383ede0e5d9d72430661f3285daa77e9439f" }
        }
        Currency: {}
      }
      orderBy: { descending: Block_Date }
      limit: { count: 100 }
    ) {
      Currency {
        Symbol
        SmartContract
      }
      Balance {
        Amount(selectWhere: { gt: "0" })
        AmountInUSD
      }
      Block {
        Date
      }
    }
  }
}

Wallet Balance for a Specific Token on a Date

Get a wallet's balance for a specific token with Balance.Address and Currency.SmartContract. This example uses native ETH (SmartContract: "0x") with dataset: combined. For a balance on a calendar date, use Balance on a Specific Date with dataset: archive and Block.Date.till.

Run in IDE

query {
  EVM(network: base, dataset: combined) {
    Balances(
      where: {
        Balance: {
          Address: { is: "0xbaed383ede0e5d9d72430661f3285daa77e9439f" }
        }
        Currency: { SmartContract: { is: "0x" } }
      }
    ) {
      Currency {
        Symbol
        SmartContract
      }
      Balance {
        Amount(selectWhere: { gt: "0" })
        AmountInUSD
        Address
      }
    }
  }
}