clawallex_pay
Process payments using USDC by generating virtual cards for online checkouts, with options for wallet-based or on-chain self-custody transactions.
Instructions
Pay for a product or service using USDC. Creates a single-use flash virtual card (card_type=100), deducts from wallet balance, returns card details for checkout.
Mode A (mode_code=100, default): wallet balance → flash card. Immediate settlement. Mode B (mode_code=200): for callers with self-custody wallets — signing is performed by the caller. x402 on-chain two-stage flow: Stage 1 (Quote): POST with mode_code=200, chain_code, token_code. The 402 response is EXPECTED — it is a quote, NOT an error. Returns: card_order_id, client_request_id, x402_reference_id, payee_address, asset_address, final_card_amount, issue_fee_amount, fx_fee_amount, fee_amount, payable_amount. Agent signs: construct and sign an EIP-3009 transferWithAuthorization using your own wallet/signing library. Stage 2 requires the resulting signature and your wallet address (authorization.from). authorization fields: from=your wallet address, to=payee_address, value=maxAmountRequired, validAfter/validBefore=unix seconds validity window, nonce=random 32-byte hex (unique per auth). Stage 2 (Settle): POST again with SAME client_request_id + signed x402 data: - 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, e.g. '207.59' → '207590000') - payment_requirements.extra.referenceId MUST equal x402_reference_id from Stage 1 - extra.card_amount MUST equal amount, extra.paid_amount MUST equal amount + fee_amount - If settle is rejected, order stays pending_payment — fix params and retry with same client_request_id.
Fee structure: fee_amount = issue_fee_amount + fx_fee_amount. total_amount = amount + fee_amount.
Example (Mode A): clawallex_pay({ amount: 50, description: 'OpenAI API credits' })
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| amount | Yes | Card face amount in USD | |
| description | Yes | What this payment is for | |
| mode_code | No | 100=wallet (default), 200=x402 on-chain | |
| tx_limit | No | Per-transaction limit in USD (optional, default 100.0000) | |
| allowed_mcc | No | MCC whitelist, comma-separated (optional, e.g. '5734,5815') | |
| blocked_mcc | No | MCC blacklist, comma-separated (optional, e.g. '7995') | |
| client_request_id | No | UUID idempotency key (<=64 chars). Mode B Stage 2: MUST reuse from Stage 1. | |
| chain_code | No | Chain code for Mode B Stage 1 (e.g. 'ETH') | |
| token_code | No | Token code for Mode B Stage 1 (e.g. 'USDC') | |
| extra | No | Mode B Stage 2 (required): { card_amount, paid_amount } | |
| x402_reference_id | No | x402 reference ID. Card creation Stage 1: optional (server generates if omitted). Stage 2: use value from 402 response. Refill Mode B: required, serves as idempotency key. | |
| x402_version | No | x402 version (Mode B Stage 2, required) | |
| payment_payload | No | x402 payment payload (Mode B Stage 2, required) | |
| payment_requirements | No | x402 payment requirements (Mode B Stage 2, required) | |
| payer_address | No | Payer wallet address (optional, final value from verify) |