/agentic-wallet

Checking Wallet Balances

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.

Command Syntax

npx awal@2.12.1 balance [--chain <chain>] [--asset <asset>] [--json]

Options

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 a 0x contract address is accepted, passing one currently fails checksum validation (the CLI uppercases the address). In practice, only the symbolic values usdc, eth, pol, sol work. Stick to those.

Input Validation

Before constructing the command, validate all user-provided values to prevent shell injection:

• chain: Must be one of base, base-sepolia, polygon, solana, solana-devnet. Reject any other value.
• asset: Must be one of usdc, eth, pol, sol. Reject any other value.
• Reject any value containing spaces, semicolons, pipes, backticks, $, or other shell metacharacters.

Do not pass unvalidated user input into the command.

Asset / Chain Compatibility

Native gas tokens are chain-specific. Behavior on unsupported asset/chain combinations is inconsistent — see the warnings below.

Token decimals: USDC = 6, ETH = 18, POL = 18, SOL = 9.

Known CLI quirks for --asset on incompatible chains

• --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.
• Always pair non-USDC assets with their correct chain explicitly (--asset eth --chain base, --asset pol --chain polygon, --asset sol --chain solana). Do not rely on the CLI to filter cross-chain.

Examples

# 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 --json

Output Format

Human-readable (default)

Base
────────────────────────
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.

JSON (--json)

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:

Top-level fields:

Converting Between Atomic Units and Human-Readable

raw is in atomic units; formatted is the value divided by 10^decimals.

When passing --max-amount to x402 pay, or atomic amounts to send/trade, always use the raw field — never formatted.

Common Use Cases

Pre-flight before a send / trade / x402 pay

# Check whether the wallet has enough USDC on Base before paying / sending
npx awal@2.12.1 balance --chain base --asset usdc --json

If formatted is below the required amount, see references/fund.md to top up.

Check spendable USDC across all chains

npx awal@2.12.1 balance --asset usdc --json

Confirm gas (ETH on Base, POL on Polygon) is available before a swap

npx awal@2.12.1 balance --chain base --asset eth --json
npx awal@2.12.1 balance --chain polygon --asset pol --json

ETH/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.

Get only the wallet address

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 base

Output 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).

Prerequisites

• Must be authenticated (npx awal@2.12.1 status to check; see references/auth.md).
• Server reachable — balance calls the local wallet companion which talks to CDP.

Error Handling

Related References

• Top up the wallet: references/fund.md
• Send tokens after confirming sufficient balance: references/send-usdc.md
• Swap tokens: references/trade.md
• Pay an x402 endpoint (uses USDC on Base): references/x402-pay.md