The CAI billing loop: how SaaS products use hosted actions, x402, and payment mandates to accept agent payments

When a SaaS product wants to let AI agents pay for its service, the naive approach is to generate an invoice and hope the agent forwards it to a human who pulls out a credit card. That breaks the agent workflow. The agent needs a payment address it can call from code, not a checkout form.

CAI provides that address. The billing loop works in three tiers: one-time checkout via hosted action, per-request billing via x402, and recurring spending via payment mandates. Each tier builds on the same custodial wallet infrastructure, and each has its own place in the product billing stack.

Tier 1: one-time checkout via hosted action

A new user signs up for your SaaS, picks a plan, and reaches the checkout page. Instead of showing a Stripe form, your backend calls POST /create-hosted-action with action_type: "deposit" and the amount. CAI returns a hosted action URL.

POST /create-hosted-action
Content-Type: application/json
Authorization: Bearer ***

{
  "action_type": "deposit",
  "constraints": {
    "payment_method": "crypto",
    "crypto_asset": "USDC_ERC20"
  }
}

Response:

{
  "ok": true,
  "url": "https://cai.com/act/abc123..."
}

Your app redirects the user to that URL. They see their CAI wallet balance, select the token, and confirm the payment. Behind the scenes, the user's CAI account executes a custodial transfer to the merchant's address. On completion, your webhook fires and you activate the subscription.

No merchant account, no card network, no redirect to a third-party processor. The user's CAI wallet is the payment method, and the hosted action URL is the checkout page.

Tier 2: per-request billing via x402

For APIs and agent-facing services, a checkout page is too slow. The agent needs to pay and get the response in the same request. This is where x402 (HTTP 402 Payment Required) comes in.

Your API endpoint returns HTTP 402 with a payment challenge:

{
  "x402_payment": {
    "recipient_address": "0xabc...",
    "amount": "0.50",
    "chain": "base",
    "token": "USDC"
  }
}

The calling agent calls POST /x402-payment-prepare on CAI with the challenge details, the user confirms (or a pre-approved mandate covers it), and POST /x402-payment-execute settles the payment. The agent retries the original API call with the proof, and your server verifies the transaction on-chain before returning the response.

The billing is per-request, not per-month. The user pays exactly for what they use, and the agent never needs to enter a credit card.

Tier 3: recurring spending via payment mandates

Per-request approval works for small bills, but it breaks down when an agent runs daily batch jobs that cost $2 each. The user would have to confirm every request, which defeats the automation.

Payment mandates solve this. The user creates a mandate with POST /payment-mandate-create:

{
  "merchant_domain": "api.example.com",
  "max_amount_per_payment_usd": "5",
  "daily_cap_usd": "25",
  "expires_in_hours": 720
}

The user approves the mandate via hosted URL (one-time). After that, any x402 payment from api.example.com within the daily cap and per-payment limit auto-settles. The agent pays without interrupting the user, and the mandate caps the damage if the agent goes rogue.

The full loop

Putting it together, a SaaS billing session looks like this:

1. Discovery: The agent calls wallet_balances to check if the user has funds. If not, create_deposit_link sends a top-up URL.
2. Checkout: For one-time payments, create-hosted-action with action_type: "deposit" or the plan-specific amount.
3. Execution: The user confirms on the hosted action page. CAI calls POST /wallet-custodial-transfer to settle.
4. Verification: Your webhook calls POST /transfer-status with the tx hash to confirm settlement.
5. Receipt: The transaction appears in GET /wallet-activity-list and a confirmation email lands in the user's @cai.com mailbox.
6. Repeat: If the product supports x402, subsequent requests go through the mandate flow without checkout page.

What this replaces

The CAI billing loop replaces three separate systems the SaaS would otherwise need: a payment processor (Stripe, etc.), a per-request billing layer for API access, and a recurring billing system for subscriptions. All three collapse into one custodial wallet with one API contract.

The guardrails are built in: a $200/day auto-limit across all payments, a new-recipient confirmation step (the user must explicitly confirm the first payment to each merchant), and mandate caps that prevent runaway spending. The user stays in control; the agent moves fast within those bounds.

Bug reports and feedback on this pattern are always read -- reply in the comments and the team gets back to you within 24 hours.