get_balances
Get token balances across the user's smart accounts. Returns a JSON array, one entry per (account × chain) combination with non-zero balances. Returns [] when the user has no balances or when filters match no accounts.
Required scope: read:balances
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
chain_id | number | no | Filter by blockchain chain ID — e.g. 1 (Ethereum), 8453 (Base), 100 (Gnosis). |
account_type | "picnic" | "gnosisPay" | no | Filter by smart account type. |
Returned fields (per entry):
| Field | Type | Description |
|---|---|---|
account.address | string | Smart account address. |
account.chainId | number | Chain the smart account lives on. |
account.type | "picnic" | "gnosisPay" | Account type. |
balances[].assetId | string | Stable CAIP (opens in a new tab)-style asset identifier — eip155:{chainId}/erc20:{address} for ERC-20s (bep20 on chain 56) or eip155:{chainId}/slip44:60 for the chain's native asset. Use this to uniquely identify an asset across chains. |
balances[].address | string | null | Asset contract address (null for the chain's native asset, identifiable from account.chainId). |
balances[].symbol | string | Token symbol (e.g. "USDC", "BNB"). |
balances[].formattedAmount | string | Decimal-formatted balance. Note: this is a string, not a number — preserves precision for very small / large amounts. |
balances[].value.usd | number | null | Balance converted to USD. null if the price feed is unavailable. |
balances[].value.eur | number | null | Balance converted to EUR. null if the price feed is unavailable. |
balances[].value.brl | number | null | Balance converted to BRL. null if the price feed is unavailable. |
Example prompt:
"How much USDC do I have on Base right now?"