Skip to main content

​
Overview

The Token Balances API enables you to retrieve public token balances of addresses on Base. This includes tokens (i.e. ERC-20s) and the native gas tokens. You can retrieve public token balances using the REST API or CDP SDK.
Need balances for wallets you own? Use the Wallet API.

​
Core capabilities

  • Lightning-fast performance: Sub-1s query latency (P99) with real-time data updates within 1 second from tip of chain
  • Standardized responses: Unified data format with 99.9%+ uptime
  • Universal address queries: Access public balance data for addresses without ownership requirements
  • Comprehensive token coverage: Returns both native ETH and ERC-20 token balances

​
Base support and performance

The Token Balances API supports both Base Mainnet and Base Sepolia testnet with sub-1 second P99 latency. Base Mainnet tracks all tokens, while Base Sepolia tracks the top 100 most active token addresses for that network. The API uses a two-step process: first checking a database to find which tokens an address owns, then reading the exact balance from the token’s smart contract to ensure fast responses with accurate amounts.

​
Use cases

  • Portfolio Tracker dApp: Build a real-time portfolio tracker that monitors Base Mainnet whale wallets. Track how top addresses like exchange wallets allocate their holdings across different tokens.
  • DeFi Analytics Dashboard: Create analytics tools that analyze token distribution patterns. Monitor how DeFi protocols’ treasury addresses evolve over time or track liquidity provider positions across multiple DEXs.
  • Trading Infrastructure: Develop arbitrage bots that monitor specific addresses for balance changes. Enable pre-trade balance verification, market maker inventory tracking, and quick reaction to large holder movements.
  • Compliance & Risk Management: Build KYC/AML solutions that monitor address activity. Track token flows between addresses, generate audit trails, and flag suspicious patterns in real-time.
⌘I