Get Wallet Balances
Retrieve all token balances (native + ERC-20) for any EVM wallet address via Sim Dune API. Returns real-time USD valuations, token metadata (symbol, decimals, logo), and portfolio totals. Supports multi-chain queries (Ethereum, Polygon, Base, Arbitrum, etc.). Pagination: max 1000 tokens/request, use nextOffset for more. Ideal for: portfolio tracking, balance verification before transfers, wallet value monitoring, token ownership checks.
Catalog action Blockchain Data
Retrieve all token balances (native + ERC-20) for any EVM wallet address via Sim Dune API. Returns real-time USD valuations, token metadata (symbol, decimals, logo), and portfolio totals. Supports multi-chain queries (Ethereum, Polygon, Base, Arbitrum, etc.). Pagination: max 1000 tokens/request, use nextOffset for more. Ideal for: portfolio tracking, balance verification before transfers, wallet value monitoring, token ownership checks.
At a Glance
| Field | Value |
|---|---|
| Action ID | sim-dune-get-wallet-balances |
| Category | Blockchain Data |
| Connector | Not required |
| Requires gas | No |
| Funds movement | None declared |
| Tags | sim-dune, blockchain, wallet, balance, tokens, portfolio, erc20, native, usd, valuation, multi-chain, read |
Payload Schema
| Field | Type | Required | Description |
|---|---|---|---|
address | string | Yes | The EVM wallet address to query balances for. Must be a valid 42-character hex address starting with 0x. Example: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7 |
chainIds | array | No | Array of chain IDs to query. Common values: 1 (Ethereum), 137 (Polygon), 8453 (Base), 42161 (Arbitrum), 10 (Optimism). If omitted, queries all supported chains. |
excludeSpamTokens | boolean | No | Filter out spam/scam tokens and tokens with very low liquidity. Recommended to keep true to avoid cluttered results. Default: true |
filterSpamTokens | boolean | No | Post-process results through the B3OS token filter service to remove spam and low-liquidity tokens. Default: true |
includeMetadata | boolean | No | Include extended token metadata such as logo URLs, social links, and description. Increases response size but useful for UIs. Default: false |
filters | string | No | Filter balances by token type. Use 'erc20' to get only ERC20 tokens, 'native' to get only native tokens (ETH, MATIC, etc.). Omit to get all tokens. |
limit | number | No | Maximum number of token balances to return. Use for pagination. Range: 1-1000. Default: 100 |
offset | string | No | Cursor for pagination (use nextOffset from previous response) |
historicalPrices | array | No | Request historical prices at specified hour offsets. Up to 3 values allowed. Examples: [24] for 1 day ago, [24, 168, 720] for 1 day, 1 week, 1 month ago. |
Result Schema
| Field | Type | Required | Description |
|---|---|---|---|
address | string | Yes | The wallet address that was queried |
balances | array | Yes | Array of token balances |
totalValueUsd | number | No | Sum of all token values in USD across all chains. Represents total portfolio value. |
warnings | array | No | Any warnings or notices from the data provider, such as rate limiting or stale data indicators |
nextOffset | string | No | Cursor for next page of results |
Examples
json{ "type": "sim-dune-get-wallet-balances", "payload": { "address": "0x0000000000000000000000000000000000000000" }, "children": []}
bashcurl -X POST "https://api.b3os.org/v1/actions/sim-dune-get-wallet-balances/test" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "inputs": { "address": "0x0000000000000000000000000000000000000000" }}'
Payload fields can use workflow expressions such as {{$trigger.body.amount}}, {{$nodes.fetch.result.price}}, and {{$props.asset}} when the value should come from a trigger, prior node, or reusable workflow prop.