Pay for anything with USDC. Clawallex converts your stablecoin balance into virtual cards that work at any online checkout.
Features
Flash Cards — one-time use virtual cards for single payments
Stream Cards — reloadable cards for subscriptions, top up with refill
Mode A — pay from your USDC wallet balance
Mode B — on-chain x402 payment for callers with self-custody wallets (agent or user) — signing is performed by the caller
Zero dependencies — Python 3.9+ stdlib only
Quick Start
1. Set Up Account
New user — browser signup (recommended):
bash
python3 {baseDir}/scripts/clawallex.py signup
Returns a URL and token. Show the URL to the user, ask them to open it and click Authorize.
The command polls automatically. If polling fails, retry with the token:
Setup first — Run setup --action status before any payment. If not configured: use signup for new accounts, or setup --action connect if the user already has API keys.
Check balance first — Run wallet before pay or subscribe to verify sufficient funds (Mode A only).
Never expose card secrets — Decrypted PAN/CVV are STRICTLY for filling checkout forms. NEVER display to the user. Show only masked_pan from card-details.
Confirm before paying — Echo amount and description back to user before creating a card.
One command at a time — Run each command, check output, then proceed.
Typical Flows
Payment Flow (Mode A — Wallet Balance)
text
1. setup --action status → check config
2. wallet → check balance
3. pay --amount 50 --description "OpenAI" → create flash card
4. card-details --card-id <ID from step 3> → get encrypted card data
5. Decrypt PAN/CVV (HKDF + AES-256-GCM) → use ONLY for checkout form
Subscription Flow
text
1. wallet → check balance
2. subscribe --amount 100 --description "AWS billing" → create stream card
3. card-details --card-id <ID from step 2> → get card for sign-up form
4. refill --card-id <ID> --amount 50 → top up when balance is low
This automatically verifies credentials, binds client_id, and saves locally.
No account yet: Run the browser signup flow:
text
signup
This generates a URL and a token — show the URL to the user and ask them to open it and click Authorize.
The command polls automatically. If polling fails or times out, use the token to retry manually:
text
signup-check --token <token from signup output>
Verify with wallet to confirm connection works.
Signup result statuses — all returned as success: true:
pending — user hasn't authorized yet, call signup-check again
ok — credentials saved, ready to use
cancelled — user cancelled, ask if they want to try again
already_exists — account already has API keys, switch to setup --action connect
Mode B Flow (x402 On-Chain, Two-Stage)
Mode B is for callers with self-custody wallets (agent or user) (DeFi bots, autonomous purchasing agents). The agent signs on-chain transactions using its own signing system — no human intervention needed.
Agent signs — construct and sign an EIP-3009 transferWithAuthorization using your own wallet/signing library and the quote details. Only the resulting signature and your wallet address are needed for Stage 2.
EIP-3009 enables gasless USDC transfers via off-chain signatures. The authorization fields map to:
from: your wallet address (the payer)
to: payee_address from Stage 1 (system receiving address)
--client-request-id MUST be identical to Stage 1 — a different value creates a NEW order
payment_requirements.payTo MUST equal payee_address from Stage 1
payment_requirements.asset MUST equal asset_address from Stage 1
payment_requirements.maxAmountRequired MUST equal payable_amount × 10^decimals (USDC = 6 decimals)
payment_requirements.extra.referenceId MUST equal x402_reference_id from Stage 1
extra.card_amount MUST equal the --amount
extra.paid_amount MUST equal payable_amount from Stage 1 (amount + fee_amount)
payment_payload.network MUST equal payment_requirements.network
payload.authorization.to MUST equal payment_requirements.payTo
payload.authorization.value MUST equal payment_requirements.maxAmountRequired
Server will force-inject extra.mode=STANDARD — any client-provided value is ignored
If settle is rejected, order stays pending_payment — fix params and retry with same client_request_id
Mode B Refill Flow (no 402 challenge)
Mode B refill goes directly to x402 settle — no 402 challenge stage. Caller signs the EIP-3009 authorization independently using their own wallet/signing library; only the resulting signature and wallet address are submitted. Must call x402-address first to get payee_address.
Run recharge-addresses for deposit info, or use Mode B
402 response
Mode B Stage 1 (expected)
This is the quote — proceed to Stage 2 with same client_request_id
Settle rejected (Mode B)
Invalid x402 params
Order stays pending_payment — fix params and retry with same client_request_id
Card not found
Wrong card_id
Run cards to list valid card IDs
Decryption failed
Bad data or apiSecret changed
Re-fetch via card-details, verify credentials
Output Format
All commands return JSON:
success: true → data in data field, next steps in _hint
success: false → error message in error field
Key Concepts
Flash card: Created by pay. Single-use, auto-destroyed after one transaction. Cannot be refilled.
Stream card: Created by subscribe. Reloadable, top up with refill.
Wallet: Your USDC balance. Funds all Mode A operations.
Mode A (mode_code=100): Wallet balance deduction (default).
Mode B (mode_code=200): x402 on-chain USDC payment for callers with self-custody wallets (agent or user). Two-stage (quote → sign → settle). Agent signs EIP-3009 independently; only the signature and wallet address are passed to Stage 2.
client_id: The agent's stable identity, separate from the API Key. An agent can have multiple API Keys (for rotation/revocation), but client_id never changes. Cards and transactions are isolated per client_id. When switching to a new API Key, keep using the same client_id — the new key auto-binds on first request. Once bound, it cannot be changed (TOFU). Stored locally at ~/.clawallex/credentials.json.