Setting the file. One moment.
Subchapter 1.2
references/balance.mdMarkdown13 KBView on GitHub
Use the npx awal@2.12.1 balance command to fetch token balances across chains. By default it returns balances for USDC + the native gas token on Base, Polygon, and Solana in a single call.
If the wallet is not authenticated, see references/auth.md. The CLI reads the address from the local wallet session — you do not pass an address argument.
npx awal@2.12.1 balance [--chain <chain>] [--asset <asset>] [--json]| Option | Description |
|---|---|
--chain <chain> | Restrict output to one chain. One of base, base-sepolia, polygon, solana, solana-devnet. Default: all chains. |
--asset <asset> | Show only one asset across the queried chain(s). One of usdc, eth, pol, sol. |
--json | Emit machine-readable JSON instead of the human table. |
-h, --help | Print built-in help. |
If both --chain and --asset are omitted, the command queries every supported mainnet chain (Base, Polygon, Solana) and every native asset on each.
Note on
--asset: Although the CLI’s invalid-asset error message implies a0xcontract address is accepted, passing one currently fails checksum validation (the CLI uppercases the address). In practice, only the symbolic valuesusdc,eth,pol,solwork. Stick to those.
Before constructing the command, validate all user-provided values to prevent shell injection:
base, base-sepolia, polygon, solana, solana-devnet. Reject any other value.usdc, eth, pol, sol. Reject any other value.$, or other shell metacharacters.Do not pass unvalidated user input into the command.
Native gas tokens are chain-specific. Behavior on unsupported asset/chain combinations is inconsistent — see the warnings below.
| Asset | Available on chains |
|---|---|
usdc | base, base-sepolia, polygon, solana, solana-devnet |
eth | base, base-sepolia |
pol | polygon |
sol | solana, solana-devnet |
Token decimals: USDC = 6, ETH = 18, POL = 18, SOL = 9.
--asset eth on Solana prints a raw error inline (e.g. Unsupported Solana asset: "ETH") instead of returning a clean empty balances object. Same for other incompatible symbolic assets on Solana.--asset pol on Base incorrectly returns a non-zero POL value that is actually the wallet’s ETH balance (mislabeled). Do not trust pol readings on Base — only query pol with --chain polygon.--asset sol on Base has the same bug — it returns the ETH balance labeled as SOL. Only query sol with --chain solana or --chain solana-devnet.--asset eth --chain base, --asset pol --chain polygon, --asset sol --chain solana). Do not rely on the CLI to filter cross-chain.# Default — all chains, all native assets + USDC
npx awal@2.12.1 balance
# One chain only (mainnet Base)
npx awal@2.12.1 balance --chain base
# Testnet balance (Base Sepolia)
npx awal@2.12.1 balance --chain base-sepolia
# Just USDC, across every chain
npx awal@2.12.1 balance --asset usdc
# Just ETH on Base
npx awal@2.12.1 balance --chain base --asset eth
# Solana SOL balance
npx awal@2.12.1 balance --chain solana --asset sol
# Machine-readable JSON
npx awal@2.12.1 balance --json
npx awal@2.12.1 balance --chain base --asset usdc --jsonBase
────────────────────────
USDC 0.00
ETH 0.00
Polygon
────────────────────────
USDC 0.00
POL 0.00
Solana
────────────────────────
USDC 0.00
SOL 0.00
Tokens from x402 payments
────────────────────────
<SYMBOL> (<network>) <formatted>When --chain and --asset are both omitted, the CLI appends a Tokens from x402 payments section listing arbitrary ERC-20 tokens (by symbol and network) seen during prior x402 pay calls that still hold a non-zero balance. The section is omitted entirely if no such balances exist, or when filtering by --chain or --asset.
Amounts are shown in their human-readable form (e.g. 5.00 USDC, 0.0123 ETH), already converted from atomic units.
When --chain is omitted, the response is keyed by chain id (base, polygon, solana, etc.):
{
"base": {
"address": "0x27cCf9aeD0D12890D4507Ee0A5CDd876C9e3DF39",
"chain": "Base",
"balances": {
"USDC": { "raw": "0", "formatted": "0.00", "decimals": 6 },
"ETH": { "raw": "0", "formatted": "0.00", "decimals": 18 }
},
"timestamp": "2026-05-07T14:56:07.571Z"
},
"polygon": { "...": "..." },
"solana": { "...": "..." }
}When --chain <chain> is provided, the response is a single chain object (no top-level chain key):
{
"address": "0x27cCf9aeD0D12890D4507Ee0A5CDd876C9e3DF39",
"chain": "Base",
"balances": {
"USDC": { "raw": "0", "formatted": "0.00", "decimals": 6 },
"ETH": { "raw": "0", "formatted": "0.00", "decimals": 18 }
},
"timestamp": "2026-05-07T14:56:07.571Z"
}JSON field reference for each balance entry:
| Field | Type | Description |
|---|---|---|
raw | string | Atomic units as a decimal string (e.g. "1000000" = 1.00 USDC). Use a big-int parser; the value can exceed Number.MAX_SAFE_INTEGER. |
formatted | string | Human-readable amount, already scaled by decimals. |
decimals | number | Number of decimals for the asset (USDC = 6, ETH/POL = 18, SOL = 9). |
Top-level fields:
| Field | Type | Description |
|---|---|---|
address | string | The wallet address on that chain. EVM (0x…) for Base/Base-Sepolia/Polygon, Base58 for Solana/Solana-Devnet. |
chain | string | Display name of the chain (e.g. "Base", "Base Sepolia"). |
balances | object | Map keyed by uppercase asset symbol (USDC, ETH, POL, SOL). |
timestamp | string | ISO-8601 UTC timestamp of when the balance was read. |
raw is in atomic units; formatted is the value divided by 10^decimals.
| Asset | Decimals | Atomic example | Human |
|---|---|---|---|
| USDC | 6 | 1000000 | 1.00 |
| USDC | 6 | 100000 | 0.10 |
| ETH | 18 | 1000000000000000 | 0.001 |
| POL | 18 | 1000000000000000000 | 1.00 |
| SOL | 9 | 1000000000 | 1.00 |
When passing --max-amount to x402 pay, or atomic amounts to send/trade, always use the raw field — never formatted.
# Check whether the wallet has enough USDC on Base before paying / sending
npx awal@2.12.1 balance --chain base --asset usdc --jsonIf formatted is below the required amount, see references/fund.md to top up.
npx awal@2.12.1 balance --asset usdc --jsonnpx awal@2.12.1 balance --chain base --asset eth --json
npx awal@2.12.1 balance --chain polygon --asset pol --jsonETH/POL are only required when the swap or send is on that chain — most USDC sends/trades on Base are gasless via paymaster, but trades may require small ETH for gas.
If you only need the address (not balances), prefer the cheaper address command:
# Human-readable, all chains
npx awal@2.12.1 address
# Machine-readable, all chains
npx awal@2.12.1 address --json
# Single-chain (returns just the bare address string with no label)
npx awal@2.12.1 address --chain baseOutput shapes — important:
address --json (no --chain) does not return a structured per-chain object. It returns a single object whose address field is a multi-line string, e.g.:
{ "address": "EVM (Base): 0x27cCf9aeD0D12890D4507Ee0A5CDd876C9e3DF39\nSolana: <base58-address>" }If you need separate EVM and Solana addresses programmatically, prefer balance --json and read the per-chain address field, or split the string on the newline and the EVM (...): / Solana: prefixes.
address --chain <chain> prints just the raw address for that chain with no label or JSON wrapper, even without --json. Useful for shell substitution: ADDR=$(npx awal@2.12.1 address --chain base).
npx awal@2.12.1 status to check; see references/auth.md).balance calls the local wallet companion which talks to CDP.| Symptom | Resolution |
|---|---|
Not authenticated / not signed in | Run the sign-in flow in references/auth.md. |
Hangs on Fetching balances... | The wallet companion may be unreachable. Run npx awal@2.12.1 status to verify server health. |
balances object empty for a chain | The asset filter has no match on that chain (e.g. --asset eth --chain polygon). Drop the filter or use a supported asset. |
Inline Unsupported Solana asset: "ETH" (or similar) printed in output | You passed an incompatible --asset for that chain (e.g. --asset eth --chain solana). Use a supported asset for the chain — see “Asset / Chain Compatibility” above. |
Non-zero POL on Base or SOL on Base | CLI bug: it’s reporting the ETH balance under the wrong symbol. Re-query with the correct chain (--asset pol --chain polygon, --asset sol --chain solana). |
Invalid chain | Use one of base, base-sepolia, polygon, solana, solana-devnet. |
Invalid token: "<value>". Must be usdc, eth, pol, or a valid 0x address | Use one of usdc, eth, pol, sol. Despite the message, raw 0x contract addresses currently fail checksum validation — stick to symbolic values. |
references/fund.mdreferences/send-usdc.mdreferences/trade.mdreferences/x402-pay.md