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

Argument	Description
`contract`	Contract address
`message`	JSON query or @file.json

Basic Query

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

Output:

{
  "count": 42
}

Options

Flag	Description	Default
`--raw`	Compact JSON (no formatting)	false
`--node`	RPC endpoint	config

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

Aspect	Query	Execute
State Change	No	Yes
Transaction	No	Yes
Gas Cost	Free	Paid
Speed	Instant	Block 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

Unknown query variant

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

Invalid JSON

Validate your query:

echo '{"get_count":{}}' | jq .

Empty response

The contract may return empty for non-existent data. Check if the item exists first.

​Querying Contracts

​Usage

​Arguments

​Basic Query

​Options

​Query Formats

​Inline JSON

​With Parameters

​From File

​Output Formats

​Pretty (Default)

​Raw (Compact)

​Common Query Patterns

​Single Value

​Address Parameter

​Paginated List

​With Start After

​CW20 Token Queries

​Token Info

​Balance

​Minter

​All Accounts

​Scripting

​Extract Value

​Monitor State

​Conditional Logic

​Query vs Execute

​Error Handling

​Contract Not Found

​Invalid Query Message

​Query Error from Contract

​Troubleshooting