microquery-agent-x402

Reference agent for the Microquery pay-per-query API using the x402 payment protocol.

No ETH required. No Coinbase x402 SDK required. Payments are EIP-3009 TransferWithAuthorization signatures built with eth-account and sent as the X-PAYMENT HTTP header. The operator's facilitator executes the on-chain USDC transfer.

Two modes

deposit (default)

Sign one EIP-3009 authorization upfront → POST /v1/deposit. The server auto-creates an account and returns an api_key. Subsequent queries use Authorization: Bearer and top-ups repeat the x402 deposit when the balance runs low.

Best for agents that run many queries — one signature per top-up rather than one per query.

perquery

No upfront deposit. Every query follows a two-step challenge-response:

1. GET /query (no auth) → 402 with the exact cost quoted in accepts[0].maxAmountRequired
2. Sign EIP-3009 for that amount, retry with X-PAYMENT header

The server auto-creates an account on first payment and returns api_key in the X-Payment-Account-Key response header. Minimum cost per query is 10,000 µUSDC ($0.01).

Best for low-frequency or exploratory use where you want to pay only for what you actually run.

See also

microquery-agent — the standard (non-x402) agent: registers for a trial credit, deposits via EIP-2612 permit, and authenticates with a Bearer token. No per-query signing overhead; simpler starting point if you don't need x402.

Prerequisites

• Python 3.11+
• USDC on Base mainnet

Setup

pip install -r requirements.txt
cp env.example .env
# edit .env — set WALLET_PRIVATE_KEY

To enable Claude-powered SQL generation:

pip install anthropic
# set ANTHROPIC_API_KEY in .env

Configuration

Variable	Default	Description
WALLET_PRIVATE_KEY	required	Hex private key; wallet must hold USDC on Base mainnet
X402_MODE	deposit	deposit or perquery
MICROQUERY_BASE_URL	https://microquery.dev	API base URL
CHAIN_ID	8453	Base mainnet; use 84532 for Base Sepolia testnet
TOPUP_AMOUNT_USDC	2	Amount (USDC) deposited on each top-up — deposit mode only
TOPUP_THRESHOLD_USDC	0.50	Trigger a top-up when balance drops below this — deposit mode only
ANTHROPIC_API_KEY	—	Optional; enables Claude-powered query generation

Running

python agent.py                  # deposit mode (default)
X402_MODE=perquery python agent.py

How it works

EIP-3009 signing

Both modes use the same _build_x_payment() function:

1. Generate a random bytes32 nonce.
2. Build a TransferWithAuthorization struct: from=wallet, to=operator, value=amount, validAfter=0, validBefore=now+300, nonce=random
3. Sign with EIP-712 using the USDC domain {name:"USD Coin", version:"2", chainId:8453, verifyingContract:<USDC>}.
4. JSON-encode the payload, base64url-encode (no padding), set as X-PAYMENT.

Deposit mode

Operator address and USDC contract are discovered once from GET /v1/agent-quickstart. No prior registration or ETH needed.

Per-query mode

The 402 challenge body contains the operator address (payTo), USDC contract (asset), and exact cost (maxAmountRequired) — no pre-discovery needed.