Skip to main content

​
Querying Contracts

The xyz program query command reads contract state without submitting a transaction. Queries are free and instant.

​
Usage

xyz program query <contract> <message> [options]

​
Arguments

ArgumentDescription
contractContract address
messageJSON query or @file.json

​
Basic Query

xyz program query xyz1contract... '{"get_count":{}}'
Output: 
{
  "count": 42
}

​
Options

FlagDescriptionDefault
--rawCompact JSON (no formatting)false
--nodeRPC endpointconfig

​
Query Formats

​
Inline JSON

xyz program query xyz1contract... '{"get_count":{}}'

​
With Parameters

xyz program query xyz1contract... '{"get_balance":{"address":"xyz1user..."}}'

​
From File

# Create query file
echo '{"get_balance":{"address":"xyz1user..."}}' > query.json

# Query from file
xyz program query xyz1contract... @query.json

​
Output Formats

​
Pretty (Default)

xyz program query xyz1contract... '{"token_info":{}}'

{
  "name": "My Token",
  "symbol": "MTK",
  "decimals": 6,
  "total_supply": "1000000000000"
}

​
Raw (Compact)

xyz program query xyz1contract... '{"token_info":{}}' --raw

{"name":"My Token","symbol":"MTK","decimals":6,"total_supply":"1000000000000"}
Use --raw for piping to other tools: 
xyz program query xyz1contract... '{"token_info":{}}' --raw | jq '.total_supply'
# "1000000000000"

​
Common Query Patterns

​
Single Value

# Get a counter value
xyz program query xyz1contract... '{"get_count":{}}'

{"count": 42}

​
Address Parameter

# Get balance for address
xyz program query xyz1token... '{"balance":{"address":"xyz1user..."}}'

{"balance": "1000000"}

​
Paginated List

# Get items with pagination
xyz program query xyz1contract... '{"all_items":{"limit":10}}'

{
  "items": [
    {"id": 1, "name": "Item 1"},
    {"id": 2, "name": "Item 2"}
  ]
}

​
With Start After

# Get next page
xyz program query xyz1contract... '{"all_items":{"start_after":"2","limit":10}}'

​
CW20 Token Queries

​
Token Info

xyz program query xyz1token... '{"token_info":{}}'

{
  "name": "My Token",
  "symbol": "MTK",
  "decimals": 6,
  "total_supply": "1000000000000"
}

​
Balance

xyz program query xyz1token... '{"balance":{"address":"xyz1user..."}}'

{"balance": "1000000"}

​
Minter

xyz program query xyz1token... '{"minter":{}}'

{
  "minter": "xyz1minter...",
  "cap": null
}

​
All Accounts

xyz program query xyz1token... '{"all_accounts":{"limit":10}}'

{
  "accounts": [
    "xyz1addr1...",
    "xyz1addr2..."
  ]
}

​
Scripting

​
Extract Value

COUNT=$(xyz program query xyz1contract... '{"get_count":{}}' --raw | jq '.count')
echo "Current count: $COUNT"

​
Monitor State

#!/bin/bash
CONTRACT="xyz1contract..."

while true; do
  RESULT=$(xyz program query $CONTRACT '{"get_count":{}}' --raw)
  COUNT=$(echo $RESULT | jq '.count')
  echo "$(date): Count = $COUNT"
  sleep 10
done

​
Conditional Logic

#!/bin/bash
BALANCE=$(xyz program query xyz1token... '{"balance":{"address":"xyz1user..."}}' --raw | jq -r '.balance')

if [ "$BALANCE" -gt "1000000" ]; then
  echo "Balance above threshold"
else
  echo "Balance below threshold"
fi

​
Query vs Execute

AspectQueryExecute
State ChangeNoYes
TransactionNoYes
Gas CostFreePaid
SpeedInstantBlock time
# Query (free, instant) - reads state
xyz program query xyz1contract... '{"get_count":{}}'

# Execute (costs gas, waits for block) - modifies state
xyz program execute xyz1contract... '{"increment":{}}' --from alice

​
Error Handling

​
Contract Not Found

Error: contract not found at xyz1invalid...

​
Invalid Query Message

Error: Generic error: query failed - unknown query variant
Check your contract’s QueryMsg enum for valid query names.

​
Query Error from Contract

Error: Query error: item not found
The contract returned an error (e.g., querying non-existent item).

​
Troubleshooting

Check your contract’s QueryMsg:
pub enum QueryMsg {
    GetCount {},  // Use: {"get_count":{}}
    GetItem { id: u64 },  // Use: {"get_item":{"id":1}}
}
Note: Rust GetCount becomes JSON get_count (snake_case).
Validate your query:
echo '{"get_count":{}}' | jq .
The contract may return empty for non-existent data. Check if the item exists first.