Clawallex

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

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:

python3 {baseDir}/scripts/clawallex.py signup-check --token <token>

Existing user — connect with API keys:

Get your API Key and Secret at app.clawallex.com/dashboard/settings, then run:

python3 {baseDir}/scripts/clawallex.py setup --action connect --api-key YOUR_KEY --api-secret YOUR_SECRET

2. Verify

python3 {baseDir}/scripts/clawallex.py wallet          # check balance
python3 {baseDir}/scripts/clawallex.py cards            # list cards

Hard Rules

1. 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.
2. Check balance first — Run wallet before pay or subscribe to verify sufficient funds (Mode A only).
3. 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.
4. Confirm before paying — Echo amount and description back to user before creating a card.
5. One command at a time — Run each command, check output, then proceed.

Typical Flows

Payment Flow (Mode A — Wallet Balance)

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

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

Command Reference

All commands:

python3 {baseDir}/scripts/clawallex.py <command> [args]

Setup & Identity

Payments

Wallet & Cards

Advanced (x402 On-Chain)

Setup Flow

When the user wants to use Clawallex for the first time:

1. Run setup --action status to check current configuration.
2. If not configured, ask: "Do you have a Clawallex account?"
   • Yes, have API keys: Ask for API Key and Secret, then run:

     setup --action connect --api-key KEY --api-secret SECRET
     

     This automatically verifies credentials, binds client_id, and saves locally.
   • No account yet: Run the browser signup flow:

     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:

     signup-check --token <token from signup output>
     

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

Stage 1 — Quote:

pay --amount 200 --description "GPU rental" --mode-code 200 --chain-code ETH --token-code USDC

The 402 response is EXPECTED — it is a quote, NOT an error. Returns:

• client_request_id, payee_address, asset_address, x402_reference_id
• final_card_amount, issue_fee_amount, fx_fee_amount, fee_amount, payable_amount

Fee structure:

• flash card: fee_amount = issue_fee_amount + fx_fee_amount
• stream card: fee_amount = issue_fee_amount + monthly_fee_amount + fx_fee_amount

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)
• value: maxAmountRequired (payable_amount in token minimal units, USDC = 6 decimals)
• validAfter / validBefore: unix timestamps (seconds) defining the signature validity window
• nonce: random 32-byte hex, must be unique per authorization

Stage 2 — Settle (MUST use same client_request_id):

pay --amount 200 --description "GPU rental" \
  --mode-code 200 \
  --client-request-id "uuid-from-stage-1" \
  --x402-version 1 \
  --payment-payload '{
    "scheme": "exact",
    "network": "ETH",
    "payload": {
      "signature": "0x<agent EIP-3009 signature>",
      "authorization": {
        "from": "0x<agent wallet address>",
        "to": "<payee_address from stage 1>",
        "value": "<maxAmountRequired, e.g. 207590000>",
        "validAfter": "<unix timestamp seconds>",
        "validBefore": "<unix times