How to Check Token Balance by Wallet Address?

Direct Chain-Specific Balance Queries

1. Users can retrieve token balances by submitting a GET request to /balance/{chain}/{address}, where {chain} is one of the seven supported blockchains and {address} is the wallet’s hexadecimal string.

2. The endpoint returns native token balance and ERC-20/BEP-20/SPL token holdings, depending on chain-specific contract standards and indexer coverage.

3. Solana responses include SPL token accounts mapped to the wallet, while Ethereum and Base return both ETH and token balances via multicall aggregation.

4. Hedera queries return only native HBAR balance; HTS tokens require separate contract interaction not covered by this endpoint.

5. Bitcoin responses reflect UTXO-based BTC balance without support for RGB or other tokenization layers.

Authentication Requirements

1. Every balance request must include an X-API-Key header containing a valid credential issued by AgentHustle AI.

2. Keys are scoped to specific chains and permissions—attempting to query BSC with an Ethereum-only key results in HTTP 403.

3. Rate limits apply per key: 60 requests per minute across all endpoints, enforced at the API gateway level.

4. Invalid or expired keys trigger HTTP 401 with a JSON body indicating “invalid_api_key” or “key_expired”.

5. No session cookies or OAuth flows are involved; authentication is stateless and header-driven.

Response Structure and Data Fields

1. Successful responses use HTTP 200 and contain a top-level balance field expressed as a stringified integer in base units (e.g., wei for ETH, lamports for SOL).

2. A tokens array lists non-native assets, each with contractAddress, symbol, decimals, and rawBalance.

3. The lastUpdated field reports Unix timestamp in milliseconds, aligned with the underlying blockchain indexer’s latest synced block.

4. For wallets holding no tokens beyond native currency, the tokens array remains present but empty.

5. All numeric values are delivered as strings to prevent floating-point precision loss during JSON serialization.

ENS Name Resolution Integration

1. ENS names like vitalik.eth can be used directly in place of hexadecimal addresses when the resolver service is enabled.

2. The API automatically performs reverse lookup via Ethereum mainnet’s ENS registry before forwarding the query to the chain-specific balance endpoint.

3. Resolution fails silently if the name does not resolve to an address or points to an invalid checksummed format.

4. Supported ENS TLDs include .eth, .xyz, and .luxe; .com and .org are not processed unless registered in ENS-compatible resolvers.

5. PayPal and Venmo integrations allow PYUSD transfers using ENS names, but balance checks remain chain-native and do not reflect off-chain payment balances.

Frequently Asked Questions

Q: Can I check balances for wallets on unsupported chains like Cardano or Avalanche?A: No. The endpoint only supports Solana, Ethereum, Base, BSC, Polygon, Hedera, and Bitcoin. Requests for other chains return HTTP 400 with error code “unsupported_chain”.

Q: Does the API detect wrapped tokens like wBTC or wETH in Ethereum wallets?A: Yes. Wrapped tokens adhering to ERC-20 standards appear in the tokens array with their correct symbol, decimals, and raw balance.

Q: What happens if a wallet has zero balance across all assets?A: The response includes balance: '0' and an empty tokens array. HTTP status remains 200.

Q: Is there a way to batch-check multiple addresses in one request?A: Not natively. Each address requires a separate HTTP request. Clients must implement parallelization or queuing logic externally.