batch_card_balances
Check balances for multiple cards in one call.
clawallex_pay
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.
EIP-712 domain: name="USDC", version="2", verifyingContract=asset_address from Stage 1.
authorization fields: from=your wallet, to=payee_address, value=maxAmountRequired,
validAfter/validBefore=unix seconds validity window, nonce=random 32-byte hex (unique per auth).
authorization.from MUST equal payer_address submitted in Stage 1.
Stage 2 (Settle): POST again with SAME client_request_id + signed x402 data:
- payment_payload.network and payment_requirements.network MUST equal chain_code from Stage 1
- payment_requirements.payTo MUST equal payee_address from Stage 1
- payment_requirements.asset MUST equal asset_address from Stage 1
- maxAmountRequired = payable_amount × 10^6 (USDC decimals, e.g. '207.59' → '207590000')
- payment_requirements.extra.referenceId MUST equal x402_reference_id from Stage 1
- extra.card_amount = amount, extra.paid_amount = amount + fee_amount
If settle rejected, order stays pending_payment — fix params and retry with same client_request_id.
Fee: fee_amount = issue_fee_amount + fx_fee_amount. total = amount + fee_amount.
Example (Mode A): clawallex_pay({ amount: 50, description: 'OpenAI API credits' })
clawallex_refill
Top up the balance of a subscription (stream) card.
Only stream cards (card_type=200) can be refilled. Refill mode follows the card's creation mode.
Mode A: deducts from wallet balance. client_request_id is the idempotency key (auto-generated if omitted).
Mode B: x402 settle (no 402 challenge stage) — agent constructs and signs the payment independently.
Step 1: call get_x402_payee_address(chain_code, token_code) to get payee_address and asset_address.
payee_address → payment_requirements.payTo
asset_address → payment_requirements.asset (the USDC token contract on the target chain, e.g. BASE USDC)
Step 2: sign an EIP-3009 transferWithAuthorization using your wallet/signing library.
EIP-712 domain: name="USDC", version="2", verifyingContract=asset_address from Step 1.
authorization.from MUST equal payer_address submitted in the request.
Step 3: maxAmountRequired = amount × 10^6 (USDC has 6 decimals; refill has no extra fee, e.g. '50.00' → '50000000').
Step 4: submit with x402_reference_id, x402_version, payment_payload, payment_requirements.
- payment_payload.network and payment_requirements.network MUST equal chain_code used in Step 1
- payment_requirements.extra.referenceId MUST equal x402_reference_id
- x402_reference_id is the idempotency key (not client_request_id)
Tip: use get_card_balance first to check current balance.
Example: clawallex_refill({ card_id: 'c_123', amount: 50 })
clawallex_subscribe
Set up a reloadable virtual card for recurring/subscription payments.
Creates a stream card (card_type=200) that stays active and can be refilled via clawallex_refill.
Mode A (mode_code=100, default): wallet balance → stream 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, monthly_fee_amount, fx_fee_amount, fee_amount, payable_amount.
Agent signs: construct and sign an EIP-3009 transferWithAuthorization using your own wallet/signing library.
EIP-712 domain: name="USDC", version="2", verifyingContract=asset_address from Stage 1.
authorization fields: from=your wallet, to=payee_address, value=maxAmountRequired,
validAfter/validBefore=unix seconds validity window, nonce=random 32-byte hex (unique per auth).
authorization.from MUST equal payer_address submitted in Stage 1.
Stage 2 (Settle): POST again with SAME client_request_id + signed x402 data:
- payment_payload.network and payment_requirements.network MUST equal chain_code from Stage 1
- payment_requirements.payTo MUST equal payee_address from Stage 1
- payment_requirements.asset MUST equal asset_address from Stage 1
- maxAmountRequired = payable_amount × 10^6 (USDC decimals, e.g. '207.59' → '207590000')
- payment_requirements.extra.referenceId MUST equal x402_reference_id from Stage 1
- extra.card_amount = amount, extra.paid_amount = amount + fee_amount
If settle rejected, order stays pending_payment — fix params and retry with same client_request_id.
Fee: fee_amount = issue_fee_amount + monthly_fee_amount + fx_fee_amount. total = amount + fee_amount.
Example: clawallex_subscribe({ initial_amount: 100, description: 'AWS monthly billing' })
create_card_order
Advanced: create a virtual card with full control over payment mode and card type.
Most agents should use clawallex_pay or clawallex_subscribe instead.
Mode A (mode_code=100): wallet balance deduction, immediate settlement.
Mode B (mode_code=200): for callers with self-custody wallets — signing is performed by the caller. x402 two-stage flow:
Stage 1 (Quote): provide chain_code + token_code. The 402 response is EXPECTED (a quote, NOT an error).
Returns: payee_address, asset_address, x402_reference_id, fee breakdown, payable_amount.
Agent signs: construct and sign an EIP-3009 transferWithAuthorization using your own wallet/signing library.
EIP-712 domain: name="USDC", version="2", verifyingContract=asset_address from Stage 1.
authorization fields: from=your wallet, to=payee_address, value=maxAmountRequired,
validAfter/validBefore=unix seconds validity window, nonce=random 32-byte hex (unique per auth).
authorization.from MUST equal payer_address submitted in Stage 1.
Stage 2 (Settle): reuse SAME client_request_id + provide x402_version, payment_payload, payment_requirements, extra.
- payment_payload.network and payment_requirements.network MUST equal chain_code from Stage 1
- payment_requirements.payTo MUST equal payee_address from Stage 1
- payment_requirements.asset MUST equal asset_address from Stage 1
- payment_requirements.extra.referenceId MUST equal x402_reference_id from Stage 1
- maxAmountRequired = payable_amount × 10^decimals (USDC = 6, e.g. '207.59' → '207590000')
- extra.card_amount = amount, extra.paid_amount = amount + fee_amount
If settle rejected, order stays pending_payment — retry with same client_request_id.
card_type: 100=flash (single-use), 200=stream (reloadable).
Fee: flash = issue_fee + fx_fee; stream = issue_fee + monthly_fee + fx_fee.
get_card_balance
Get the current balance and status of a virtual card. Returns available_balance, card_currency, status, and updated_at.