Skip to main content

​
Balance Queries

The xyz balance command queries account balances including native XYZ and CW20 tokens.

​
Basic Usage

xyz balance <address>
Or by key name: 
xyz balance --key <name>

​
Query Native Balance

​
By Address

xyz balance xyz1abc123def456...
Output: 
Address: xyz1abc123def456...

Native Balances:
  uxyz: 1,000,000,000,000 (1,000,000 XYZ)

​
By Key Name

xyz balance --key mykey
The CLI resolves the address from your keyring automatically.

​
Query All Balances

Include CW20 token balances with --all: 
xyz balance --all --key mykey
Output: 
Address: xyz1abc123def456...

Native Balances:
  uxyz: 1,000,000,000,000 (1,000,000 XYZ)

CW20 Balances:
  MTK (xyz1token1...): 500,000,000,000
  USDC (xyz1token2...): 1,000,000,000
CW20 balances require tracked tokens in config. Add tokens with:
xyz config set cw20-tokens xyz1token1...,xyz1token2...

​
JSON Output

For scripting and automation: 
xyz balance --key mykey --output json

{
  "address": "xyz1abc123def456...",
  "native_balances": [
    {
      "denom": "uxyz",
      "amount": "1000000000000"
    }
  ],
  "cw20_balances": []
}
With --all: 
{
  "address": "xyz1abc123def456...",
  "native_balances": [
    {
      "denom": "uxyz",
      "amount": "1000000000000"
    }
  ],
  "cw20_balances": [
    {
      "contract": "xyz1token1...",
      "balance": "500000000000"
    }
  ]
}

​
Command Options

FlagDescriptionDefault
--keyKey name from keyring-
--allInclude CW20 tokensfalse
--output, -oOutput format (table/json)table
--nodeRPC endpoint overrideconfig

​
Examples

​
Check Test Account Balance

# Start localnet first
xyz localnet start

# Check alice's balance
xyz balance --key alice

​
Check Multiple Accounts

# List all keys
xyz keys list

# Check each balance
for key in alice bob mykey; do
  echo "=== $key ==="
  xyz balance --key $key
done

​
Monitor Balance Changes

# Watch balance every 5 seconds
watch -n 5 "xyz balance --key mykey"

​
Parse Balance in Script

# Get raw amount
BALANCE=$(xyz balance --key mykey --output json | jq -r '.native_balances[0].amount')
echo "Balance: $BALANCE uxyz"

# Check if sufficient
if [ "$BALANCE" -lt "1000000" ]; then
  echo "Warning: Low balance!"
fi

​
Understanding Amounts

All on-chain amounts are in uxyz (micro XYZ):
DisplayOn-Chain (uxyz)
1 XYZ1,000,000
0.5 XYZ500,000
0.000001 XYZ1
The table output shows both: 
uxyz: 1,000,000,000,000 (1,000,000 XYZ)
       └── raw amount    └── display amount

​
CW20 Token Balances

​
Setup Tracked Tokens

  1. Get token contract addresses
  2. Add to configuration:
xyz config set cw20-tokens xyz1mytoken...,xyz1anothertoken...
  1. Query with --all:
xyz balance --all --key mykey

​
Query Single Token

For a specific token, use the token commands: 
xyz token balance xyz1tokencontract... --key mykey

​
Troubleshooting

The address may not exist on-chain yet (no transactions):
Error: account xyz1... not found
Fund the account first or check the address is correct.
Node may not be running:
# Check node status
curl http://localhost:26657/status

# Or start localnet
xyz localnet start
Ensure token is tracked:
xyz config get cw20-tokens
# Should include your token address
And use --all flag:
xyz balance --all --key mykey
  • Check address is correct
  • Check you’re on the right network (chain-id)
  • For localnet, use test accounts (alice, bob)