Balances Endpoint

Retrieve token balances for the authenticated wallet across all supported chains, or filter to specific chains.

Endpoint

GET /agent/balances

Request

Headers

Header	Value	Required
X-API-Key	Your API key	Yes

Query Parameters

Parameter	Type	Description	Required
chains	string	Comma-separated list of chains to fetch (e.g. base, base,solana). If omitted, returns balances for all chains.	No

Supported chains: base, polygon, mainnet, unichain, solana

Response

Success (200 OK)

{
  "success": true,
  "evmAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "solAddress": "5DcKdJL79AtpCVvif8pzNgEkXT1onNVM7NaChZ7QrNdR",
  "balances": {
    "base": {
      "nativeBalance": "0.5",
      "nativeUsd": "1250.00",
      "tokenBalances": [
        {
          "network": "base",
          "token": {
            "balance": 1000,
            "balanceUSD": 1000,
            "baseToken": {
              "name": "USD Coin",
              "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
              "symbol": "USDC",
              "price": 1,
              "imgUrl": "https://..."
            }
          }
        }
      ],
      "total": "2250.00"
    },
    "solana": {
      "nativeBalance": "10.5",
      "nativeUsd": "1575.00",
      "tokenBalances": [],
      "total": "1575.00"
    }
  },
  "nfts": []
}

Response Fields

Field	Type	Description
success	boolean	Whether the request was successful
address	string	The wallet address balances were fetched for
balances	object	Balance data keyed by chain name
balances[chain].nativeBalance	string	Native token balance (e.g. ETH, SOL)
balances[chain].nativeUsd	string	Native balance in USD
balances[chain].tokenBalances	array	ERC-20 / SPL token balances
balances[chain].tokenBalances[].network	string	Chain name
balances[chain].tokenBalances[].token.balance	number	Token amount
balances[chain].tokenBalances[].token.balanceUSD	number	Token value in USD
balances[chain].tokenBalances[].token.baseToken.name	string	Token name
balances[chain].tokenBalances[].token.baseToken.address	string	Token contract address
balances[chain].tokenBalances[].token.baseToken.symbol	string	Token symbol
balances[chain].tokenBalances[].token.baseToken.price	number	Current token price in USD
balances[chain].tokenBalances[].token.baseToken.imgUrl	string	Token logo URL
balances[chain].total	string	Total USD value for the chain
nfts	array	Always empty (NFTs are not included in this endpoint)

note

Tokens below the low-value threshold (default $1 USD) are filtered out. Native token balances (ETH, SOL, POL) are always included regardless of value.

Error Responses

Authentication Required (401)

{
  "error": "Authentication required",
  "message": "Valid API key with associated wallet required"
}

Agent Access Not Enabled (403)

{
  "error": "Agent API access not enabled",
  "message": "This API key does not have Agent API access enabled."
}

Internal Server Error (500)

{
  "error": "Internal server error",
  "message": "Failed to fetch balances"
}

Examples

curl — All chains

curl https://api.bankr.bot/agent/balances \
  -H "X-API-Key: your_api_key_here"

curl — Specific chain

curl "https://api.bankr.bot/agent/balances?chains=base" \
  -H "X-API-Key: your_api_key_here"

curl — Multiple chains

curl "https://api.bankr.bot/agent/balances?chains=base,solana" \
  -H "X-API-Key: your_api_key_here"

TypeScript

const response = await fetch("https://api.bankr.bot/agent/balances?chains=base", {
  headers: { "X-API-Key": process.env.BANKR_API_KEY! },
});

const data = await response.json();

for (const [chain, balance] of Object.entries(data.balances)) {
  console.log(`${chain}: $${balance.total}`);
  for (const token of balance.tokenBalances) {
    console.log(`  ${token.token.baseToken.symbol}: ${token.token.balance}`);
  }
}

Bankr CLI

# All chains
bankr balances

# Specific chain
bankr balances --chain base

# Multiple chains
bankr balances --chain base,solana

# JSON output (for scripting)
bankr balances --json