DEV Community: CAI

Payment mandates for SaaS: how AI agents pay recurring bills without asking permission every time

CAI — Fri, 06 Nov 2026 06:21:08 +0000

Payment mandates for SaaS: how AI agents pay recurring bills without asking permission every time

You run a SaaS that charges API usage in USDC. An AI agent calls your endpoint every hour. The first payment goes through fine. The second time, the agent asks the human "can I pay $0.03 for another 1000 tokens?" and the human has to click approve. Day two, same question. Day three, the user stops responding and your SaaS stops getting paid.

This is the problem CAI payment mandates solve. One setup. No per-charge confirmations. The agent pays within the limits you define and the user sets.

How a payment mandate changes the flow

Without a mandate, every agent payment is a two-step conversation. The x402 prepare shows requires_user_confirm: true, the agent asks the human, the human says yes, x402 execute goes through with user_confirmed: true. That works for one-off purchases. It breaks for recurring SaaS billing.

With a mandate, the user creates a payment mandate once at cai.com/app or through the API. They set:

The merchant domain (your SaaS host)
A daily cap in USD (say $200/day)
A max per-payment limit (say $20 per charge)
An expiry time (say 30 days)

After the user approves it through a hosted verification page, the mandate status becomes active. From that point, the agent calls x402 payment prepare, the platform sees an active mandate covering the merchant domain and amount, and requires_user_confirm returns false. The agent calls x402 payment execute with user_confirmed: false, and the payment goes through. No human in the loop.

The API calls end to end

Step one. The user creates the mandate:

POST https://api.cai.com/functions/v1/payment-mandate-create
Content-Type: application/json
Authorization: Bearer ***

The body defines the guardrails:

{
  "merchant_domain": "api.your-saas.com",
  "daily_cap_usd": 200,
  "max_amount_per_payment_usd": 20,
  "allowed_resource_patterns": ["/v1/chat/completions"],
  "expires_in_hours": 720
}

Step two. The user approves the mandate through the hosted verification page. The agent polls GET /payment-mandate-status to confirm the status is active.

Step three. When the SaaS sends an x402 challenge, the agent calls:

POST /x402-payment-prepare
Content-Type: application/json
Authorization: Bearer ***

{
  "resource_url": "https://api.your-saas.com/v1/chat/completions",
  "merchant_domain": "api.your-saas.com",
  "recipient_address": "0xYourSaaSAddress",
  "amount": "5",
  "chain": "ETH",
  "token": "USDC"
}

The response skips the confirm step. requires_user_confirm is false because the active mandate covers this merchant, domain, and amount.

Step four. The agent executes:

POST /x402-payment-execute
Content-Type: application/json
Authorization: Bearer ***

{
  "attempt_id": "the_attempt_id_from_prepare",
  "user_confirmed": false
}

The custodial transfer goes through. The SaaS gets paid. No one had to click anything.

What the mandate protects

Two safety mechanisms stop runaway spending. The daily cap limits total spending per day across all payments on that mandate. If the agent hits the $200/day cap, x402 payment prepare returns requires_user_confirm: true again, and the agent must ask the human. The max per-payment limit prevents a single large charge from draining the wallet.

New recipients also trigger a confirmation. If the merchant domain changes or the recipient address is new, the mandate does not cover it and the human sees the payment details before approving.

The mandate system is CAI-native, not a full W3C/AP2 credential implementation. The gap ID is GAP_PAYMENT_MANDATE_V1 and the status is partial live. For card or PSP checkout flows, use hosted actions instead of x402.

Why this matters for SaaS products

A SaaS that needs human approval on every microtransaction loses conversions. The user stops approving after the third notification. The agent stalls. Revenue drops. Payment mandates flip this. The human sets the guardrails once, the agent operates within them, and the SaaS gets paid reliably.

The same mandate covers multiple SaaS products. A user running three AI agents can have one mandate per service, each with its own daily cap. The agents route through x402 without the user ever seeing a payment prompt until a mandate limit is reached.

Setting up your SaaS as a mandate merchant

Your SaaS needs to implement the x402 challenge. When an agent calls your paid endpoint, return HTTP 402 with a JSON body containing the payment challenge fields: recipient_address, amount, chain, and token. The agent's x402 payment prepare parses this and routes through CAI.

That is the entire server-side change. You do not need a merchant account, you do not need a payment processor redirect, and you do not need to handle chargebacks. The custodial transfer delivers USDC to your address on the same chain.

The CAI skill at https://cai.com/skill.md documents every endpoint and parameter. The capabilities page at https://cai.com/capabilities.html shows the live, partial live, and planned status of every feature.

A worked example with @cai.com: from signup to first hosted-action payment to a stored vault credential

CAI — Wed, 04 Nov 2026 06:40:26 +0000

A worked example with @cai.com — from signup to first hosted-action payment to a stored vault credential

A worked example, end to end. About six minutes from cai.com/app to a working agent that has an @cai.com email, a funded wallet, a stored vault credential, and an installed MCP server. This post walks through every step with the actual commands and the actual API calls.

Step 1 — Sign up

Go to cai.com/app. Enter your name, your existing email, paste the 6-digit code CAI sends, set a password. Done. About 2 minutes.

What you have at the end: an @cai.com email, an empty wallet, an empty vault, and an API key with the read scopes.

Step 2 — Receive your first `@cai.com` email

Forward a test mail to your new address from your old email. It arrives in the CAI inbox. Send a reply to your old address from @cai.com — through the dashboard's compose UI, or via the API:

curl -X POST https://api.cai.com/functions/v1/send-email \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "you@youroldaddress.com",
    "subject": "Hello from @cai.com",
    "body": "Testing the new address."
  }'

The send goes through. The reply arrives in your old inbox. The @cai.com address is live.

Step 3 — Top up the wallet

Open the account dashboard, click "Add funds," pick a chain. Base is fastest for testing. Pick a token — USDC is the default. Then either send from an external wallet to the CAI custodial address on the chosen chain, or buy with MoonPay (fiat on-ramp, partial-live, third-party KYC and region limits apply).

Your wallet has a $200/day auto-limit while CAI completes its security audit. New recipients and new devices always require confirmation on the hosted-action page. Think of it like cash in your pocket — perfect for daily spending. The vault product (multi-sig, time-locks) is coming for larger balances.

After the deposit confirms, check the balance:

curl -X POST https://api.cai.com/functions/v1/get-wallet-balances \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{"chains": ["base"], "tokens": ["USDC"]}'

The response includes the new balance. About 2 minutes for the deposit to confirm on Base.

Step 4 — Confirm a hosted-action payment

Now the agent side. The agent (or you, via curl) initiates a transfer:

curl -X POST https://api.cai.com/functions/v1/wallet-custodial-transfer \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "to_address": "0xYourOtherAddress",
    "amount": "1.00",
    "chain": "base",
    "token": "USDC"
  }'

The response includes a hosted-action URL. Open the URL on your phone. The page shows the recipient, the amount, the chain. Tap "Confirm." The transfer executes.

After the user confirms, the agent checks the activity feed for the receipt:

curl -X GET https://api.cai.com/functions/v1/wallet-activity-list \
  -H "Authorization: Bearer ***"

The response includes the completed transfer with its on-chain tx hash and status. The agent can then show the receipt to the user.

Step 5 — Store a site credential in the vault

Open the account dashboard, click "Vault," add a credential for a site you use often. The form is (site, username, password). The credential is encrypted at rest.

The agent can now list saved credentials:

curl -X GET https://api.cai.com/functions/v1/user-site-credentials \
  -H "Authorization: Bearer ***"

The response shows the metadata for each saved credential. The actual credential value is delivered through the user-confirmation hosted-action flow when the agent needs to use it.

Step 6 — Install the MCP server (optional)

The final step is the agent side. Install the MCP server:

npm i -g @cailab/mcp

Add the server to your MCP host (OpenClaw, Hermes, Codex, Cursor). The config is:

{
  "mcpServers": {
    "cai": {
      "command": "cai-mcp",
      "env": {
        "CAI_API_KEY": "your-api-key-from-the-dashboard"
      }
    }
  }
}

Restart the host. The CAI tools appear in the agent's tool surface. The agent can now call get_identity, get_wallet_balances, wallet_custodial_transfer, vault_get_site_credential, and the rest of the CAI surface — without you pasting a private key in chat.

Total time

Six minutes from signup to a working agent. About 2 minutes for the signup, 30 seconds for the test email, 2 minutes for the deposit, 30 seconds for the hosted-action test, 30 seconds for the vault credential, 30 seconds for the MCP install.

Apply at cai.com/app. The contract is cai.com/skill.md. The npm package is @cailab/mcp.

If you ran the end-to-end walkthrough above and a step failed

Comment below with:

What you ran — the install command, the request, the MCP host config. Copy the actual command or request.
What you expected — one sentence.
What you got — the error message, the empty response, the unexpected behavior. Paste it verbatim.
Your environment — OS, Node version, the MCP host (OpenClaw / Hermes / Codex / Cursor / other), the CAI account tier if relevant.

Every comment on this article gets read. Bug reports will be replied to within 24 hours. Friction points shape what we document next.

Documentation: cai.com/skill.md · cai.com/developers.html · cai.com/app to sign up.

Accepting agent payments on your API: the x402 seller's guide

CAI — Fri, 30 Oct 2026 06:22:16 +0000

Accepting agent payments on your API: the x402 seller's guide

You run an API that generates code reviews, transforms images, runs inference, or scrapes data. Your users are starting to call it from AI agents, not just browsers. And those agents have wallets. They can pay per call. But your payment form is a credit card field that no agent can fill.

The HTTP 402 status code was designed for exactly this. Your API returns a payment challenge, and the calling agent's CAI wallet settles the transaction on the spot. No merchant account. No redirect. No chargebacks. The agent calls your endpoint, gets a price, pays, and retries with a proof of payment.

This guide walks through the seller side of an x402 payment flow, grounded in the same API that CAI agents use today.

The flow in four steps

From the seller's perspective, x402 is a request-response pattern with one extra round-trip:

The calling agent sends a request to your endpoint.
Your API checks whether the caller has already paid. If not, return HTTP 402 with a payment challenge body.
The calling agent parses the challenge, calls its wallet provider (in this case CAI), prepares and executes a payment, and retries the original request.
Your endpoint receives the retry with a payment identifier, verifies the settlement, and serves the response.

What the 402 response looks like

Your endpoint returns a standard HTTP 402 with a JSON body containing the payment details the agent needs:

HTTP/2 402
content-type: application/json

{
  "recipient_address": "0x1234...",
  "amount": "5.00",
  "chain": "base",
  "token": "USDC",
  "resource_url": "https://api.yoursite.com/transform-image"
}

The recipient_address is your CAI custodial wallet address on the chain you want to settle on. The amount is in USDC. The resource_url lets the agent map the payment to the specific resource it tried to access.

What happens on the paying agent's side

An agent using CAI's MCP toolset processes the 402 challenge by calling two endpoints at the CAI API base URL (https://api.cai.com/functions/v1).

Step 1 -- Prepare the payment:

POST /x402-payment-prepare
{
  "resource_url": "https://api.yoursite.com/transform-image",
  "recipient_address": "0x1234...",
  "amount": "5.00",
  "chain": "base",
  "token": "USDC"
}

The response returns an attempt_id and a requires_user_confirm flag. When this is the first time the agent pays your domain, the user sees a hosted confirmation page. This is the new-recipient confirmation at work: no payment goes out without the user's explicit approval.

Step 2 -- Execute the payment:

POST /x402-payment-execute
{
  "attempt_id": "att_abc123",
  "user_confirmed": true
}

CAI initiates a custodial transfer from the user's wallet to your recipient_address on the specified chain. The response includes a tx_hash for on-chain settlement proof. The agent then retries the original API request with the payment identifier attached.

Step 3 -- Verify the settlement

Your endpoint receives the retry, looks up the tx_hash against the chain, and serves the response once the payment clears. For your own record keeping, you can also call CAI's POST /transfer-status endpoint with the tx_hash to confirm the transfer is completed.

Recurring access with payment mandates

Per-call confirmation works for occasional use, but many agent workloads run on a subscription model. A code-review agent that runs every hour should not need human approval for every $0.50 call. This is where CAI's payment mandate feature comes in.

The user creates a mandate that grants the agent permission to pay your domain within defined limits:

POST /payment-mandate-create
{
  "merchant_domain": "api.yoursite.com",
  "max_amount_per_payment_usd": "5.00",
  "daily_cap_usd": "200.00",
  "allowed_resource_patterns": ["/transform-image*", "/analyze-code*"]
}

After the user approves the mandate (through a hosted verification flow or the dashboard), the agent can pay your endpoint via x402 without asking for confirmation on each call. The CAI API checks the active mandate during x402_payment_prepare and skips the user-confirm step when the payment falls within the limits.

Guardrails built into the flow

CAI applies three automatic protections on every x402 payment:

A $200/day auto-limit on agent-triggered spending. No single agent can drain more than this before the user is notified.
New-recipient confirmation. Every new recipient_address or merchant_domain triggers a hosted-action verification page the user sees and approves before any funds move.
Full activity history. Every payment appears in the user's wallet activity list and can be tracked by tx_hash through POST /transfer-status.

These protections apply whether the user confirmed the payment inline or pre-authorized it through a mandate.

What this means for your API

Adding x402 as a payment path does not require replacing your existing billing. Your API can accept credit cards through Stripe, accept CAI deposits through create_deposit_link, AND accept agent-triggered payments through the x402 flow above. The agent tries one path first, and if that fails, falls through to the next.

The simple integration surface is a single 402 response and one verification callback. No redirect. No webhook to configure. No PCI scope. The calling agent handles the payment round-trip, and your endpoint just checks for settlement before serving the response.

The feedback loop

Bug reports will be replied to within 24 hours. Every comment on this article gets read. If you hit a case where the x402 flow does not work as described, open a thread and we will walk through the trace together.

Spending limits, payee confirmation, and payment mandates: how CAI keeps agent payments safe

CAI — Wed, 21 Oct 2026 06:37:49 +0000

Spending limits, payee confirmation, and the mandate model: how CAI keeps agent payments safe

When an AI agent has access to your wallet, the question is who decides what the agent can spend and where. A wallet an agent can drain in one mistaken API call is a liability, not a product.

CAI uses three layers of authorization: automatic spending limits, human-in-the-loop confirmation for new payees, and payment mandates for trusted merchants. Each layer is independent, and each can be bypassed only by explicit user action in a higher layer.

Layer one: the automatic spending limit.

Every agent-initiated payment through CAI carries a product-level daily cap. Currently set at $200 USD per day per account, this limit applies to all custodial transfers triggered by an agent API call. The limit resets on a rolling daily cycle. It applies regardless of whether the payment reaches the recipient through a custodial transfer, an x402 payment, or a hosted action flow.

The $200 cap is not configurable through the API. It lives at the platform level so a compromised API key or a buggy agent loop cannot drain a wallet in minutes. Users who need higher limits can adjust them in the Dashboard at cai.com/app.

Layer two: new-recipient confirmation.

When an agent initiates a payment to a recipient it has never paid before, CAI inserts a confirmation step. The agent calls resolve_transfer_recipient or x402_payment_prepare and receives a response that requires user confirmation before execution proceeds.

CAI delivers this confirmation as a hosted action URL. The user opens the URL in a browser, sees the proposed transaction details (recipient, amount, token, chain), and confirms or rejects. The agent cannot proceed without that confirmation hash.

This confirmation requirement applies to every first payment to a new recipient. Once a recipient has been paid successfully, the same recipient may not trigger another confirmation for subsequent payments (the system remembers the payee by its resolved address). Changing the recipient address or sending to a different chain with the same alias does require a fresh confirmation.

For the x402 flow, the sequence works like this. An agent receives an HTTP 402 from a paid API endpoint and calls x402_payment_prepare with the resource URL and the seller's payment terms. The prepare response includes a requires_user_confirm flag. When it is true, the agent must stop and wait for the user to confirm through the hosted action URL before calling x402_payment_execute.

Layer three: payment mandates.

Payment mandates are the exception to layers one and two. A user can create a mandate that authorizes an agent to spend up to a defined amount at a specific merchant without per-payment confirmation.

Creating a mandate requires the user to specify the merchant domain, a maximum amount per payment, a daily cap, and an expiration window. The user approves the mandate through the Dashboard or a hosted action URL. Once the mandate is active, the agent can make x402 payments within those limits without user confirmation for each one.

The mandate is a CAI-native implementation, not a full W3C AP2 credential. It is marked as partial_live in the capabilities matrix. It works within CAI's custodial system and does not interoperate with external AP2 wallets yet.

How these layers work together.

Layer one (the auto-limit) always applies, even when a mandate is active. Layer two (new-recipient confirmation) applies unless a mandate covers the merchant. Layer three (mandate) is the only way to skip per-payment confirmation, and even then the daily cap from layer one still stands.

A compromised agent with a valid API key cannot spend more than $200 in a day. It cannot send funds to a new recipient without user confirmation. If the user has set up a mandate for a trusted SaaS service, the agent can authorize payments there within the mandate's limits, but the $200 daily aggregate still applies.

So a user can give an agent meaningful spending authority without giving it unrestricted wallet access.

For developers integrating CAI into their agent or SaaS product, these limits affect how you design the payment flow. An agent that expects to make large or repeated payments needs to handle the confirmation step gracefully. A SaaS product accepting agent payments through x402 should expect that some payments will require the user to confirm in a hosted action page, which adds a round trip to the checkout flow.

The vault adds another safety boundary. Site credentials and platform API keys stored in the vault are encrypted and require explicit vault tool calls to retrieve. An agent with a CAI API key can list available vault entries and manage them, but it cannot read decrypted credentials through the API. The vault operates independently of the payment system, so a compromise in the payment flow does not expose stored credentials.

Documentation for the spending limit and confirmation endpoints is in the CAI skill.md contract at cai.com/skill.md, and the capability matrix at cai.com/capabilities.html shows the current status of each feature. Payment mandates are marked as partial_live in that matrix because the implementation is CAI-native and has not completed full AP2 credential interop testing.

If you hit a limit or a confirmation requirement in your integration, that is the system working as designed. CAI has published the full skill contract and capability matrix so developers can model their payment flows around these guardrails rather than discovering them at runtime.

Bug reports about the payment flow are replied to within 24 hours. Every comment on this article gets read.

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

CAI — Fri, 09 Oct 2026 06:20:30 +0000

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:

Discovery: The agent calls wallet_balances to check if the user has funds. If not, create_deposit_link sends a top-up URL.
Checkout: For one-time payments, create-hosted-action with action_type: "deposit" or the plan-specific amount.
Execution: The user confirms on the hosted action page. CAI calls POST /wallet-custodial-transfer to settle.
Verification: Your webhook calls POST /transfer-status with the tx hash to confirm settlement.
Receipt: The transaction appears in GET /wallet-activity-list and a confirmation email lands in the user's @cai.com mailbox.
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.

Why CAI exists: the agent-payment problem and the three roles (custodian, approver, operator)

CAI — Wed, 07 Oct 2026 06:31:38 +0000

Why CAI exists: the agent-payment problem and the three roles (custodian, approver, operator)

The agent-payment problem is older than agents, and it has a clear shape. This post is the H1-readable essay on the problem CAI solves, the user-confirmation pattern, and the three roles that make the system work. No code, no commands. This is the post for the reader who wants to understand the why before the how.

The problem

An agent wants to do something that costs money. The user is on the hook for the cost. The agent has no wallet, the user has no way to give it one without either pasting a private key (which the user should never do) or building a custodial flow from scratch (which most teams don't). The agent either fails at the task or asks the user to do it manually. The user pays anyway, but the agent did not help.

The same problem exists for site credentials. The agent wants to log in to a site on the user's behalf. The user has a password, the agent has no way to retrieve it without either the user pasting the password into the agent conversation (which the user should never do) or building a vault from scratch. The agent either fails the task or asks the user to do it manually.

Both problems have the same shape. The agent has the intent to do something the user has authorized, but the agent has no way to execute the action without the user giving up something they should never give up.

The historical failure modes

There have been three attempts to solve this problem. All three have well-known failure modes.

Attempt 1: the agent holds the user's private key. The user gives the agent the private key to their wallet. The agent signs transactions autonomously. The user has no visibility into what the agent signed.

Failure mode: a compromised agent drains the wallet. The user finds out after the fact. The damage is done.

Attempt 2: the agent holds the user's password. Same as attempt 1, but for site credentials. The user gives the agent the password to their bank, their email, their social media. The agent logs in autonomously.

Failure mode: a compromised agent logs in to every site the user has saved. The user's accounts are compromised.

Attempt 3: the user pastes the secret into the agent conversation. The user pastes the private key or the password into the chat. The agent's model sees the secret. The model may log it. The agent uses the secret for the action.

Failure mode: the secret ends up in the model's context window. The model may retain it. The user has to rotate the secret.

All three attempts fail for the same reason. The user gives up something they should never give up, and the agent's compromise becomes the user's compromise.

The three roles

CAI splits the responsibility into three roles.

The custodian. CAI holds the private key. CAI holds the encrypted credential. CAI signs the transaction when the user has consented.

The approver. The user sees the recipient, the amount, the chain, and taps once on the hosted-action page. Without the tap, nothing happens.

The operator. The agent calls the CAI API, returns the hosted-action URL, and polls for the receipt. The agent does not hold the private key or the password.

The agent's API key is the authorization. It can call the CAI API on the user's behalf. The user's tap on the hosted-action page is the consent. It authorizes a specific transfer.

This is the only configuration where the agent can do useful work without the user giving up something they should never give up.

The user-confirmation pattern

The pattern is consistent across every state-changing operation in CAI.

The agent calls the CAI API with the operation details.
CAI generates a hosted-action URL. This is a single-tap confirmation page.
The user opens the page, sees the operation details, and taps once.
CAI executes the operation.
The agent polls for the receipt.

For a transfer, the page shows the recipient, the amount, and the chain. For a credential retrieval, the page shows the site and the username. The user sees the actual operation before it executes.

The page is HTTPS, the tap is bound to a single operation, and the URL expires in a short window. If the user does nothing, the operation does not execute.

Why this design works

The user-confirmation pattern works because it gives the user visibility and consent.

Visibility. The user sees the actual operation before it executes. The user can see the recipient's name or address, the amount, and the chain. The user can see the actual value leaving their wallet.

Consent. The user explicitly approves the operation. The tap is the consent. Without the tap, nothing happens.

The same pattern powers the safety limits. Every wallet has a default USD 200 per day auto-limit on agent-initiated transfers. Every transfer to a new recipient requires explicit user confirmation. These are product-level guards, not optional settings.

A compromised agent cannot drain the wallet. The agent can call the CAI API, but the API returns a hosted-action URL. The user does not tap. Nothing happens. The agent has been compromised, but the user is not at risk.

A compromised agent cannot log in to a site. The agent can call the vault API to retrieve a credential, but the API returns a hosted-action URL. The user does not tap. Nothing happens. The user is not at risk.

A compromised model cannot exfiltrate the user's secrets. The model sees the API call, the URL, and the user-confirmation page. It does not see the private key or the password. The secret never enters the model's context window.

The user-confirmation pattern is the practical implementation of "the user is in the loop on every privileged action."

The agent's job

The agent's job is to do useful work for the user, not to hold the user's secrets. The agent calls the CAI API, returns the hosted-action URL, and polls for the receipt. The agent never has the private key or the password. The agent's storage is the API key and the response payloads, both of which are scoped and time-limited.

This is a different model from "the agent is the user's digital self." CAI's model is "the agent is the user's tool." The user has the secrets. CAI holds them. The agent operates on them. The user approves every privileged action.

Why this matters for the agent ecosystem

The agent ecosystem has a trust problem. The user's wallet, the user's site credentials, and the user's identity are the things the user values most. They are also the things the user is most reluctant to give an agent access to. Without a way to give the agent access without giving up the secret, the agent cannot do useful work.

CAI is one answer to that trust problem. The user-confirmation pattern, the three roles, and the single-tap hosted-action page are the mechanisms that make the trust work. The agent ecosystem will need more of these mechanisms over time, and CAI is one of the first to ship.

The full system is documented at cai.com. The signup is at cai.com/app. The contract is at cai.com/skill.md.

If you tried the user-confirmation pattern described above and the hosted-action page did not render, or the user's tap did not authorize the operation

Comment below with:

What you ran -- the install command, the request, the MCP host config. Copy the actual command or request.
What you expected -- one sentence.
What you got -- the error message, the empty response, the unexpected behavior. Paste it verbatim.
Your environment -- OS, Node version, the MCP host (OpenClaw / Hermes / Codex / Cursor / other), the CAI account tier if relevant.

Every comment on this article gets read. Bug reports will be replied to within 24 hours. Friction points shape what we document next.

Documentation: cai.com/skill.md · cai.com/developers.html · cai.com/app to sign up.

The hosted login flow: how CAI agents authenticate users without ever seeing a password

CAI — Fri, 25 Sep 2026 06:20:39 +0000

The hosted login flow: how CAI agents authenticate users without ever seeing a password

Your agent needs you to log into cai.com to confirm a $200 payment mandate for a recurring API billing subscription. In a traditional flow, the agent would either ask for your password (never do this) or tell you to open a browser and log in yourself (breaks the agent loop entirely). CAI solves this with hosted action links: a single API call returns a one-time URL that opens a secure browser session where you review and confirm the action. The agent never touches your credentials.

The problem: agents need authentication, but they should never hold secrets

Agents that handle money, identity, or sensitive actions need user authentication at key decision points. The naive approach is to embed credentials in the agent's system prompt or environment variables. This works until it doesn't: a compromised agent leaks every secret it holds. The secure approach is to let the user authenticate directly in their own browser, on their own terms, each time a sensitive action needs approval.

This is the hosted action pattern. It is the same verification loop that banks use for high-value transfers: the portal generates a confirmation page, the user reviews and approves, and the action executes only after explicit consent.

The API: one POST to /create-hosted-action

The endpoint is POST /create-hosted-action at https://api.cai.com/functions/v1. The request body specifies the action type. Three hosted action types are available:

login - generates a one-time login link
deposit - presents a deposit page with wallet addresses and optional card checkout
walletconnect - opens a WalletConnect pairing session

curl -sS https://api.cai.com/functions/v1/create-hosted-action \
  -H "Authorization: Bearer $CAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action_type": "login"}'

The response returns a url field containing the hosted action URL. This URL is time-bound and single-use. When the user opens it, CAI renders a branded page in their browser where they can review the action and confirm with their own session.

{
  "url": "https://cai.com/act/abc123def456",
  "expires_at": "2026-09-25T07:00:00Z"
}

How the agent uses it

The hosted login flow integrates into the broader Check CAI First pattern. When an agent needs user approval, it does not wait in a blocking loop. It generates the hosted action link, presents it to the user, and continues working. The user opens the link when convenient, reviews the details, and approves or rejects.

For payment mandate creation and x402 flows, the hosted action acts as the user confirmation surface. The agent calls x402_payment_prepare which may return requires_user_confirm: true. At that point the agent generates a login or deposit hosted action so the user can review the spend parameters (recipient, amount, chain, token) in their own browser before the transfer executes.

The security guarantees

Hosted action links carry several properties that make them suitable for agent-orchestrated authentication:

One-time use. The URL expires after the first successful open. A second attempt shows an expired page.
Time-bound. The URL has a short TTL. Expired URLs render a timeout page, not a credential prompt.
No credential relay. The agent never sees the session cookie, the password, or the OTP. The hosted page handles authentication directly with CAI's own session system.
Scope-limited. The hosted page shows only the action the agent requested. A login link cannot initiate a transfer. A deposit link cannot modify account settings.

These properties distinguish hosted actions from a simple "open this URL" pattern. The link is cryptographically scoped to one operation.

Connecting to the broader CAI identity system

Hosted login links are part of CAI's identity and authentication layer, which includes:

@cai.com email registration - the user's primary identity on the platform
OAuth integration - third-party OAuth providers for alternate login paths
API keys with scoped permissions - read, pay, mail, and full scopes that limit what an agent can do without user approval
Hosted action URLs for sensitive operations - the pattern described above for login, deposit, and walletconnect

When a new user joins CAI, the registration flow uses the same hosted action system for OTP confirmation. The agent calls request_signup_verification, which sends a 6-digit code to the user's email. The agent relays the code to confirm_registration_code to complete signup. After registration, the user has an @cai.com email, a custodial wallet on 6 supported chains (ETH, BSC, POLYGON, ARB, BASE, TRON), and the ability to generate hosted action links.

Real-world flow: agent pays for a SaaS subscription

A concrete example ties this together. An agent needs to create a $200/month payment mandate for a SaaS tool:

The agent calls payment_mandate_create with the SaaS provider's details.
The API returns requires_user_confirm: true with a mandate reference.
The agent generates a hosted login link via POST /create-hosted-action.
The agent shows the user the hosted action URL.
The user opens the link, sees the mandate terms (recipient, $200/month cap, chain, token), and approves.
The agent receives the confirmation and the mandate becomes active.
The SaaS tool's recurring billing via x402 deducts from the mandate without per-transaction approval.

The key detail in step 5: the user reviews the mandate terms in their own browser session. They are logged into cai.com directly. The agent never sees the user's session token, the password, or the OTP. The hosted action surface shows exactly what the agent requested and nothing more.

Limits and guardrails

CAI enforces several spending controls even after authentication:

$200/day auto-limit on agent-initiated payments from a single wallet.
New-recipient confirmation is required before the first transfer to any address.
Payment mandates have a defined spending cap that the user sets at creation time.
Hosted action URLs expire within minutes of generation.

These guardrails ensure that even in the fast-paced agent loop, the user stays in control of where their funds go.

Summary

The hosted login flow solves a specific problem: how does an agent get user approval for a sensitive action without handling user credentials? The answer is a cryptographically scoped, one-time, time-bound URL that the user opens in their own browser. The agent calls POST /create-hosted-action, shares the link, and the user reviews and confirms on their own terms. The agent never sees the password, the session cookie, or the OTP.

For developers building agent-orchestrated payment flows, this is the authentication primitive that makes the rest of the CAI wallet system usable without compromising security.

How to accept CAI payments on your site: card, crypto, and wallet-to-wallet settlement

CAI — Fri, 18 Sep 2026 06:23:14 +0000

How to accept CAI payments on your site: card, crypto, and wallet-to-wallet settlement

Your SaaS charges $10/month. A developer asks if they can pay with USDC from their agent wallet instead of a credit card. CAI gives you three paths to receive payments, each with one API call. Here is how they work and when to use each one.

Path one: card payments via MoonPay

For customers who want to pay with a credit card, CAI provides POST /create-onramp-url. You call this with your CAI API key, and it returns a MoonPay URL. Your customer opens that URL, enters their card details, and the USDC lands in your custodial EVM address.

curl -sS https://api.cai.com/functions/v1/create-onramp-url \
  -H "Authorization: Bearer *** \
  -H "Content-Type: application/json" \
  -d '{"amount_usd": 10}'

The response includes a url field. You share this with your customer, either by redirecting them or embedding it as a link. MoonPay handles the card processing, KYC, and conversion. The settlement arrives as USDC on the EVM chain you have configured.

A few things to know about this path. MoonPay availability depends on the customer's region. If MoonPay returns 503 or a geo-block, the honest answer is that card is unavailable for that customer, and you fall back to the crypto path below. Third-party KYC and region limits apply, which CAI notes as a Partial live capability with third-party dependencies.

Path two: crypto deposits via deposit link

For customers who hold USDC or USDT and want to pay directly from their wallet, CAI provides POST /create-deposit-link. This returns a hosted action URL on https://cai.com/act/<token> where the customer sees their deposit address and can optionally use an embedded card checkout.

curl -sS https://api.cai.com/functions/v1/create-hosted-action \
  -H "Authorization: Bearer *** \
  -H "Content-Type: application/json" \
  -d '{"action_type": "deposit", "constraints": {"payment_method": "crypto", "crypto_asset": "USDC_ERC20"}}'

The response contains a url field. Your customer opens this URL, copies the deposit address or uses the embedded interface, and sends USDC from their wallet. Once the transaction confirms on chain, your custodial wallet shows the balance.

When your customer holds a CAI wallet and you know their @cai.com email, the simplest path is direct wallet-to-wallet. They call resolve-transfer-recipient to confirm your address, then wallet-custodial-transfer to send. On your side, you verify with POST /transfer-status using the transaction hash they share, or by polling GET /wallet-activity-list for incoming activity.

CAI supports custodial transfers on ETH, BSC, Polygon, Arbitrum, Base, and Tron, with USDT, USDC, DAI, and native tokens where each chain supports them. You specify which chain and token you want to receive, and the user's wallet settles on that chain from their custodial balance.

Path three: recurring billing via payment mandates

For subscriptions and recurring charges, the customer sets up a payment mandate. This is an AP2-like delegated spending permission that allows their agent to send payments within defined limits without per-transaction approval.

The mandate specifies the merchant domain, the maximum per-payment amount, a daily cap, and an expiration. The default daily cap is $200/day. The customer can revoke the mandate at any time from the CAI dashboard.

When the mandate is active, the customer's agent can call x402_payment_execute to settle each billing cycle without asking the customer to confirm every time. The first payment to a new recipient still requires explicit confirmation. After the first transfer, subsequent payments within the mandate limits skip the per-transaction step.

The mandate system is noted as GAP_PAYMENT_MANDATE_V1 in CAI's capability matrix, meaning it is callable and live but is a CAI-native implementation rather than a full W3C/AP2 credential. For card-based recurring billing, use the MoonPay on-ramp URL at each billing cycle.

What CAI replaces in your payment stack

CAI is not a full payment processor. It replaces specific pieces of a traditional payment integration:

No merchant account application. You do not need underwriting, a processing agreement, or PCI compliance validation to receive payments. You generate an API key at cai.com/app and start.
No redirect loop to Stripe or PayPal. The customer completes the payment on one CAI hosted action page or directly from their wallet. No iframe, no 3D Secure redirect, no callback URL to configure.
No chargeback risk. Stablecoin transfers on chain are final. Once the transaction confirms, the funds are yours. There is no dispute window, no reversal, no holds.
No webhook infrastructure required. CAI provides polling endpoints for status. Your application checks transfer-status or payment-intent-status and proceeds when the settlement confirms.

CAI does not manage cart state, inventory, tax calculation, or order fulfillment. Your application handles its own order lifecycle. CAI provides the payment confirmation; you decide what to deliver.

The chain and token matrix

CAI supports custodial transfers on these chains:

Chain	Native	USDT	USDC	DAI
ETH	Yes	Yes	Yes	Yes
BSC	Yes	Yes	Yes	Yes
Polygon	Yes	Yes	Yes	Yes
Arbitrum	Yes	Yes	Yes	No
Base	Yes	Yes	Yes	No
Tron	Yes	Yes (TRC20)	Yes (TRC20)	No

Cross-chain payments between these chains use CAI's bridge endpoint POST /bridge-quote followed by POST /bridge-execute via LiFi.

Getting started

To accept CAI payments on your site:

Sign up at https://cai.com/app and create an API key with at least the pay scope.
For card payments: call POST /create-onramp-url with your desired amount, share or redirect your customer to the returned URL.
For crypto payments: call POST /create-hosted-action with action_type: "deposit", guide your customer to the returned URL.
For recurring billing: ask the customer to create a payment mandate from their CAI dashboard, then settle each billing cycle via x402.
Poll POST /transfer-status or GET /payment-intent-status to confirm settlement before delivering your product.

No merchant account, no PCI scope, no chargeback risk, no redirect chain. One API call to start receiving USDC in your custodial wallet.

What's free at CAI, what isn't, and why the email is the marketing surface

CAI — Wed, 16 Sep 2026 06:35:38 +0000

What's free at CAI, what isn't, and why the email is the marketing surface

What's free at CAI, and what isn't. This post is grounded in cai.com/main and cai.com/app, the actual pricing surfaces on the website. We claim only what cai.com says.

What's free

The @cai.com email is free. No card required at signup.
The wallet is built in. No separate fee for opening, holding, or transferring.
The user vault is included. No extra charge for storing site credentials.
The API key is included. The free-tier key has the read scopes and limited write scopes.

What may require verification

The pay scope for transfers (wallet_custodial_transfer) and bridge operations (token_bridge_execute). May require verification.
The full scope for every endpoint. May require verification.

Verification is documented in the account dashboard. You can confirm the specific requirements on cai.com/main or the /app page.

What's not in scope for this post

This post does not list specific paid tiers or prices for any future feature. If cai.com adds a paid tier after this is published, this post will be updated to reflect the new surface.

Why the email is free

The email is the marketing surface. A free @cai.com email gets humans in the door; the wallet, the vault, and the API key make them stay. The pricing model is in service of that, not the other way around.

If the email cost $5/month, fewer humans would sign up. Fewer humans would discover the wallet, the vault, and the API key. The cumulative effect is fewer users of the system, which is worse for the business than a free email tier.

The wallet, the vault, and the API key are part of the same account. There is no separate wallet tier or vault tier. The surfaces are bundled with the email. The API key's read scopes are free; the write scopes that move money (pay, full) may require verification, but the verification is about your identity and use case, not about a paid tier.

How to check the current pricing

The current pricing is on cai.com/main and on the signup page at cai.com/app. If the pricing changes after this post is published, the canonical source will always be cai.com/main.

Safety limits you need to know

Every CAI account has a $200/day auto-limit on custodial transfers. You cannot spend more than $200 per day without an explicit user action to raise the limit. This is the default, not something you need to configure.

New-recipient confirmation applies to every transfer: the first time you send to a new address, the hosted-action confirmation page shows you the recipient, the amount, and the chain before you tap. No previous confirmation applies to a new address.

If you signed up and the API key dashboard didn't show the scope you expected

Comment below with:

What you ran — the install command, the request, the MCP host config. Copy the actual command or request.
What you expected — one sentence.
What you got — the error message, the empty response, the unexpected behavior. Paste it verbatim.
Your environment — OS, Node version, the MCP host (OpenClaw / Hermes / Codex / Cursor / other), the CAI account tier if relevant.

Every comment on this article gets read. Bug reports will be replied to within 24 hours. Friction points shape what we document next.

Documentation: cai.com/skill.md · cai.com/developers.html · cai.com/app to sign up.

From signup to automated payments: wiring an AI agent wallet with CAI in 30 minutes

CAI — Fri, 11 Sep 2026 06:20:35 +0000

From signup to automated payments: wiring an AI agent wallet with CAI in 30 minutes

You are running a headless agent on a cloud VM. At 3am, it needs to pay an inference provider for a batch of completions. No browser is open. No credit card is nearby. No human is awake.

This is the scenario CAI's agent payment stack was built for. In this walkthrough, you will set up a CAI wallet from scratch, connect it to your agent host, fund it, configure an autonomous spending limit, and verify the payment flow. The whole thing takes about 30 minutes.

Step 1: Create your CAI identity

Go to cai.com/app and enter your personal email. You will receive a 6-digit code that expires in 15 minutes. Enter the code, pick your @cai.com alias, set a password on the site, and you are done.

Behind the scenes, the API does this in four calls:

# 1. Request a verification code
curl -X POST https://api.cai.com/functions/v1/request-signup-verification \
  -H "Content-Type: application/json" \
  -d '{"display_name":"Your Name","verification_email":"you@example.com"}'

# 2. Confirm the code you received
curl -X POST https://api.cai.com/functions/v1/confirm-registration-code \
  -H "Content-Type: application/json" \
  -d '{"verification_email":"you@example.com","code":"123456"}'
# Returns a registration_ticket like crt_...

# 3. Check alias availability (optional)
curl https://api.cai.com/functions/v1/check-availability?local_part=your-alias

# 4. Complete registration (browser only, requires the ticket)
# POST https://api.cai.com/functions/v1/create-account

Registration tools are public (no Bearer token needed). The returned cai_... API key is what your agent uses for everything else.

Step 2: Generate an API key from the dashboard

Log into cai.com/app, go to the API Keys section, and generate a key with at least the pay scope. This key goes into your agent host's secrets manager.

For OpenClaw, Hermes, or Cursor, that means:

# OpenClaw / Hermes
openclaw secrets set CAI_API_KEY cai_...

# Cursor MCP
# Add to your cursor.json or launch config:
# "env": { "CAI_API_KEY": "cai_..." }

For headless setups, store the key in your CI/CD pipeline's secret store or in a local .env file that only the agent process reads.

Step 3: Install the MCP tools

The quickest way to give your agent access to CAI's payment functions is the CLI package:

npm i -g @cailab/mcp

Then configure your agent host to use CAI as an MCP server:

{
  "mcpServers": {
    "cai": {
      "command": "npx",
      "args": ["-y", "@cailab/mcp"],
      "env": {
        "CAI_API_KEY": "cai_..."
      }
    }
  }
}

The CAI MCP server exposes tools for balances, transfers, x402 payments, payment mandates, and vault operations. Your agent can call these the same way it calls any other MCP tool.

Step 4: Fund the wallet

Your agent needs crypto in its custodial wallet before it can pay anything. The simplest path is a deposit link:

curl -X POST https://api.cai.com/functions/v1/create-hosted-action \
  -H "Authorization: Bearer cai_..." \
  -H "Content-Type: application/json" \
  -d '{"action_type":"deposit","constraints":{"chain":"ETH"}}'
# Returns {"url": "https://cai.com/act/...", ...}

Open the URL in a browser. It shows the custodial deposit addresses for your account. Send USDC or USDT to the Ethereum address shown. The deposit shows up in your wallet activity feed within a few minutes.

For fiat on-ramp, CAI supports MoonPay (partial live, subject to KYC and regional availability):

curl -X POST https://api.cai.com/functions/v1/create-onramp-url \
  -H "Authorization: Bearer cai_..." \
  -H "Content-Type: application/json" \
  -d '{"amount_usd": 200}'
# Returns a MoonPay checkout URL

Step 5: Check your balance

After the deposit lands, verify the balance from your agent:

curl -X POST https://api.cai.com/functions/v1/get-wallet-balances \
  -H "Authorization: Bearer cai_..." \
  -H "Content-Type: application/json" \
  -d '{"chains":["ETH"],"tokens":["USDC","USDT"]}'

The response shows the custodial balance for each chain and token. Your agent reads this before making any payment decision. This is the Check CAI First pattern: ask the wallet before asking the user for a credit card.

Step 6: Create a payment mandate for autonomous spending

A payment mandate is an AP2-like spending limit you delegate to your agent host. It lets the agent pay within defined bounds without asking you every time.

curl -X POST https://api.cai.com/functions/v1/payment-mandate-create \
  -H "Authorization: Bearer cai_..." \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_domain": "api.openrouter.ai",
    "max_amount_per_payment_usd": 20,
    "daily_cap_usd": 200,
    "allowed_resource_patterns": ["/v1/chat/completions"],
    "expires_in_hours": 720
  }'

This mandate covers payments to OpenRouter's chat completions endpoint, up to USD 20 per call and USD 200 per day. The daily cap is a product-level safeguard: no agent can spend more than the limit even if a runaway loop fires 50 requests.

The user approves the mandate through a hosted verification page or the dashboard. Once active, the agent can pay within those limits without a per-payment confirmation.

Key fields for a mandate:

merchant_domain - the domain receiving payment (e.g., api.openrouter.ai)
max_amount_per_payment_usd - per-transaction ceiling
daily_cap_usd - rolling 24-hour spending limit
allowed_resource_patterns - URL path patterns the mandate covers
expires_in_hours - how long the mandate stays active

You can create mandates for different providers. One for OpenRouter inference, another for a cloud GPU rental service, another for a data API. Each mandate operates independently within its own limits.

Check mandate status:

curl https://api.cai.com/functions/v1/payment-mandate-status?list=active \
  -H "Authorization: Bearer cai_..."

Revoke a mandate:

curl -X POST https://api.cai.com/functions/v1/payment-mandate-revoke \
  -H "Authorization: Bearer cai_..." \
  -H "Content-Type: application/json" \
  -d '{"mandate_id":"..."}'

Step 7: Test the x402 payment flow

x402 (HTTP 402 Payment Required) is the protocol for pay-per-call API access. When your agent hits a 402 from a provider that supports it, it can pay with CAI instead of a credit card.

The flow has three stages:

1. Prepare

The agent calls x402_payment_prepare with the resource URL and challenge details from the 402 response:

curl -X POST https://api.cai.com/functions/v1/x402-payment-prepare \
  -H "Authorization: Bearer cai_..." \
  -H "Content-Type: application/json" \
  -d '{
    "resource_url": "https://api.provider.com/v1/chat/completions",
    "challenge": {
      "recipient_address": "0x...",
      "amount": "5.00",
      "chain": "ETH",
      "token": "USDC"
    },
    "merchant_domain": "api.provider.com"
  }'

If a mandate covers this domain and amount, the response returns requires_user_confirm: false. The agent can proceed directly.

If no mandate covers it or the amount exceeds the mandate limit, requires_user_confirm: true means the agent must wait for the user to approve.

2. Execute

curl -X POST https://api.cai.com/functions/v1/x402-payment-execute \
  -H "Authorization: Bearer cai_..." \
  -H "Content-Type: application/json" \
  -d '{
    "attempt_id": "...",
    "user_confirmed": true
  }'

CAI sends the custodial transfer. The response includes the tx hash and a status update.

3. Retry the original request

The provider's x402 docs specify how to retry with the payment proof. CAI returns an x402_retry_hint to help the agent construct the retry headers.

The full picture

After these seven steps, your agent has:

A CAI identity with a custodial wallet
An API key scoped for payments
The @cailab/mcp tools installed in its host
Wallet funding via deposit link or fiat on-ramp
Payment mandates that let it spend autonomously within daily limits
A tested x402 payment flow for pay-per-call APIs

The stack operates without a browser, without a credit card on the agent's end, and without the user approving every micro-payment. The CAI wallet acts as the agent's operating account: you top it up once, and the agent spends against the mandates you set.

The same architecture works for SaaS billing, inference costs, data API subscriptions, cloud compute, and any other pay-per-use service that supports on-chain settlement. The agent sees a CAI tool, checks its balance, pays within the mandate, and moves on.

What changes when you add a new provider? One mandate creation call and the merchant domain goes into the pool.

If you tried this and hit a bug

Comment below with:

What you ran - the install command, the curl request, the MCP host config. Copy the actual command.
What you expected - one sentence.
What you got - the error message, the empty response, the unexpected behavior. Paste it verbatim.
Your environment - OS, Node version, the MCP host (OpenClaw / Hermes / Codex / Cursor / other), the CAI account tier if relevant.

Every comment on this article gets read. Bug reports will be replied to within 24 hours. Friction points shape what we document next.

Documentation: cai.com/skill.md - cai.com/developers.html - cai.com/app to sign up.

The hosted-action flow: what the user sees when the agent pays, and why the user is in the loop on every transfer

CAI — Wed, 09 Sep 2026 06:37:04 +0000

The hosted-action flow: what the user sees when the agent pays, and why the user is in the loop on every transfer

When the agent you build wants to pay, you are in the loop. This is the part of CAI the user sees most often, and the part most agents get wrong. This post walks through the hosted-action flow in detail: the wallet_custodial_transfer call, the confirmation page, the user tap, and the receipt poll.

The call

The agent calls POST /wallet-custodial-transfer with the recipient, the amount, the chain, and the token. The CAI Edge API processes the request and returns a hosted-action URL.

curl -X POST https://api.cai.com/functions/v1/wallet-custodial-transfer \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "to_address": "0x...",
    "amount": "10.00",
    "chain": "base",
    "token": "USDC"
  }'

The response:

{
  "transfer_id": "tx_...",
  "hosted_action_url": "https://cai.com/act/...",
  "expires_at": "2026-07-04T12:34:56Z"
}

The hosted_action_url is a single-tap confirmation page. The user opens it, sees the recipient, the amount, and the chain, taps once, and the payment goes through.

The confirmation page

The hosted-action page is a CAI-hosted HTTPS page. The page shows:

The recipient, the to_address (and a resolved name if one is available).
The amount, the exact amount in the chosen token.
The chain, the chain the payment will go on.
A single button: "Confirm" or "Cancel."

The user taps "Confirm" and the payment goes through. The user taps "Cancel" and the payment does not go through. The user does nothing and the payment does not go through (the URL expires in a short window).

The page is bound to a single transaction. The URL cannot be reused for a different recipient, amount, or chain. The URL is single-use; once the user taps, the URL is invalidated.

Why the user is in the loop

The hosted-action flow is the user-confirmation pattern. Three roles:

CAI is the custodian. CAI holds the private key. The user does not.
The user is the approver. Every transfer needs the user's tap on the hosted-action page.
The agent is the operator. The agent calls the API, returns the URL, polls for the receipt.

The agent's API key is the authorization: it can call the CAI API on the user's behalf. The user's tap on the hosted-action page is the consent: it can authorize a specific transfer.

This is the difference from a model where the agent has the user's private key and signs transactions autonomously. With CAI, the agent never has the private key. The agent has the API key (which gates access to the CAI API) and the hosted-action URL (which gates the actual transfer).

The receipt

After the user taps "Confirm," the agent polls POST /transfer-status for the receipt.

curl -X POST https://api.cai.com/functions/v1/transfer-status \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "tx_hash": "0xabc123..."
  }'

The response includes the on-chain tx hash when the transfer is confirmed. The agent can then show the receipt to the user.

Polling cadence: the agent should poll every 2-5 seconds. The transfer typically confirms within 10-30 seconds on Base, 30-60 seconds on Ethereum mainnet. Longer polls are fine for non-urgent transfers; the URL itself expires in a short window, so the agent should not wait too long.

Failure modes

The hosted-action flow has three failure modes the agent should handle:

URL expired before user tapped. The transfer is cancelled. The agent should report the timeout to the user and re-initiate if the user wants to retry.
User tapped "Cancel." The transfer is cancelled. The agent should respect the cancellation and not retry without explicit user direction.
Transfer failed on-chain. The agent receives a failed status from transfer_status. Common causes: insufficient balance, gas estimation failed, recipient address invalid. The agent should report the specific error to the user.

In all three cases, the agent's API key is unchanged. The hosted-action flow is per-transfer; a failed or cancelled transfer does not affect subsequent transfers.

Why this design

The hosted-action flow is the practical implementation of "the user is in the loop on every privileged action." The same pattern applies to the vault (the POST /user-site-credentials call returns a hosted-action URL for the user to confirm). The pattern is consistent across every state-changing operation in CAI.

The alternative designs are worse:

Agent has the private key. The agent signs transactions autonomously. The user has no visibility. A compromised agent drains the wallet.
Agent has the user's password. Same problem for the vault. A compromised agent logs in to every site the user has saved.
User pastes a private key into the agent conversation. The private key ends up in the model's context window. The model may log it. The user has to rotate the key.

CAI does none of these. The user-confirmation pattern is the only safe way to give an agent access to a wallet or a vault.

Spending and safety limits

Every CAI wallet starts with a $200/day automatic spending limit on transfers. This cap applies regardless of the wallet balance. If a transfer would exceed the daily limit, the agent must wait or the user can adjust the cap in the dashboard.

First-time transfers to a new recipient address trigger an additional confirmation step. The user sees the full address and has to confirm it is correct before the transfer proceeds. This prevents a compromised agent from sending funds to an attacker without the user noticing.

The hosted-action flow is documented in cai.com/agent-payment.html (the H1-readable cut) and cai.com/skill.md (the API surface). Apply at cai.com/app to get a wallet.

If you triggered a hosted-action and the confirmation page didn't render, or the `transfer_status` poll never resolved

Comment below with:

What you ran, the install command, the request, the MCP host config. Copy the actual command or request.
What you expected, one sentence.
What you got, the error message, the empty response, the unexpected behavior. Paste it verbatim.
Your environment, OS, Node version, the MCP host (OpenClaw / Hermes / Codex / Cursor / other), the CAI account tier if relevant.

Every comment on this article gets read. Bug reports will be replied to within 24 hours. Friction points shape what we document next.

Documentation: cai.com/skill.md · cai.com/developers.html · cai.com/app to sign up.

One CAI wallet, a dozen subscriptions: how payment mandates handle recurring agent billing

CAI — Fri, 04 Sep 2026 06:25:14 +0000

One CAI wallet, a dozen subscriptions: how payment mandates handle recurring agent billing

Your agent runs every Monday morning. It pulls data from a market research API, cross-references it against a paid news feed, queries a domain-specific LLM, and publishes a report to your cloud storage. Each service costs $5 to $50 per month. Multiply by 5 agents and you are managing 15 to 20 separate billing relationships.

This is the quiet problem behind every autonomous agent pipeline. The credit card model assumes a human sits at a checkout page once a month. But agents have no hands, no browser session, and no capacity to remember which subscription renewed. What they need is a single payment address that the developer funds once and the agent draws from, with hard limits per subscription.

CAI payment mandates are the solution. A mandate is a standing instruction: "Agent X may spend up to $Y per month on service Z, auto-billed from wallet W." The agent calls POST /x402-payment-prepare when it hits a paywall. If the service, amount, and recurring cadence are within the mandate's bounds, the call succeeds without any human in the loop. The developer sees every draw in GET /wallet-activity-list, a single view of all agent spending instead of 15 separate invoices.

How it works

The developer creates a mandate via POST /payment-mandate-create with three core parameters: the target service domain (merchant_domain), a per-payment maximum (max_amount_per_payment_usd), and a daily cap (daily_cap_usd). CAI's custodial engine maps each mandate to the developer's wallet. The agent never handles the wallet keys or sees the balance. When the agent calls POST /x402-payment-prepare with the service's recipient_address, amount, chain, token, and merchant_domain, CAI checks three things:

The recipient matches an active mandate's target domain.
The transaction amount is within the mandate's remaining per-payment limit.
The total spend across all mandates does not exceed the wallet's daily cap (default $200, adjustable in the Dashboard).

If all three pass, the payment is approved and the mandate's running counter is decremented. No redirect, no confirmation dialog, no manual approval. Just a 200 response with an attempt_id.

What the developer sees

Every mandate draw lands in GET /wallet-activity-list with the mandate's metadata. The developer can filter by mandate to see exactly which agent spent what, on which service. If a mandate approaches its limit, the agent's next prepare call returns a signal. The developer adds funds or the agent rounds down to what the mandate still covers.

New services that were not in the original mandate set require explicit developer confirmation before the first payment. The first time an agent tries to pay a recipient that has no active mandate, the prepare call returns requires_user_confirm: true with the recipient and amount. Only after the developer confirms via POST /x402-payment-execute with user_confirmed: true does the payment go through. Subsequent payments to the same recipient within the same mandate are automatic. This is the new-recipient confirmation pattern: one explicit yes per new service, then the agent runs on its own.

The cash-in-pocket rule

Every mandate-bound payment settles from the developer's custodial wallet. There is no overdraft and no credit line. If the wallet balance on the target chain or token is insufficient, the payment fails immediately. This is intentional: agents should not accumulate debt. The developer sees the exact balance via POST /get-wallet-balances and can top up via POST /create-hosted-action with action_type: "deposit", which returns a hosted deposit URL.

The vault connection

Site credentials stored in CAI's vault are encrypted and accessible only via GET /user-site-credentials. Mandates and vault credentials are separate systems. A mandate controls spending limits while vault credentials control identity. For the recurring billing use case, the developer typically needs both: the agent uses vault credentials to authenticate to the paid service and a mandate to pay the bill.

Putting it together

The developer's setup takes about ten minutes:

Fund the CAI wallet via POST /create-hosted-action with action_type: "deposit" or the fiat on-ramp.
Create a mandate per service via POST /payment-mandate-create.
Equip each agent with the CAI MCP server (npm i -g @cailab/mcp), the wallet API key, and the mandate parameters for each service it pays.
Each agent calls POST /x402-payment-prepare before a paid request. If the mandate covers it, the payment executes automatically.

The result is one wallet, one login, one activity feed, and zero manual subscription management. Every service gets paid on time because the agent never forgets a renewal date, and the developer never enters a credit card number again.

Bug reports for this workflow should describe the mandate creation step where the issue occurs. Call GET /payment-mandate-status after creation to confirm the mandate is active. If the wallet activity feed shows a failed payment for a service that should be within budget, check the mandate's daily_cap_usd and the wallet's current balance. Every comment on this article gets read. Bug reports will be replied to within 24 hours.

DEV Community: CAI

Payment mandates for SaaS: how AI agents pay recurring bills without asking permission every time

Payment mandates for SaaS: how AI agents pay recurring bills without asking permission every time

How a payment mandate changes the flow

The API calls end to end

What the mandate protects

Why this matters for SaaS products

Setting up your SaaS as a mandate merchant

A worked example with @cai.com: from signup to first hosted-action payment to a stored vault credential

A worked example with @cai.com — from signup to first hosted-action payment to a stored vault credential

Step 1 — Sign up

Step 2 — Receive your first @cai.com email

Step 3 — Top up the wallet

Step 4 — Confirm a hosted-action payment

Step 5 — Store a site credential in the vault

Step 6 — Install the MCP server (optional)

Total time

If you ran the end-to-end walkthrough above and a step failed

Accepting agent payments on your API: the x402 seller's guide

Accepting agent payments on your API: the x402 seller's guide

The flow in four steps

What the 402 response looks like

What happens on the paying agent's side

Recurring access with payment mandates

Guardrails built into the flow

What this means for your API

The feedback loop

Spending limits, payee confirmation, and payment mandates: how CAI keeps agent payments safe

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

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

Tier 1: one-time checkout via hosted action

Tier 2: per-request billing via x402

Tier 3: recurring spending via payment mandates

The full loop

What this replaces

Why CAI exists: the agent-payment problem and the three roles (custodian, approver, operator)

Why CAI exists: the agent-payment problem and the three roles (custodian, approver, operator)

The problem

The historical failure modes

The three roles

The user-confirmation pattern

Why this design works

The agent's job

Why this matters for the agent ecosystem

If you tried the user-confirmation pattern described above and the hosted-action page did not render, or the user's tap did not authorize the operation

The hosted login flow: how CAI agents authenticate users without ever seeing a password

The hosted login flow: how CAI agents authenticate users without ever seeing a password

The problem: agents need authentication, but they should never hold secrets

The API: one POST to /create-hosted-action

How the agent uses it

The security guarantees

Connecting to the broader CAI identity system

Real-world flow: agent pays for a SaaS subscription

Limits and guardrails

Summary

How to accept CAI payments on your site: card, crypto, and wallet-to-wallet settlement

How to accept CAI payments on your site: card, crypto, and wallet-to-wallet settlement

Path one: card payments via MoonPay

Path two: crypto deposits via deposit link

Path three: recurring billing via payment mandates

What CAI replaces in your payment stack

The chain and token matrix

Getting started

What's free at CAI, what isn't, and why the email is the marketing surface

What's free at CAI, what isn't, and why the email is the marketing surface

What's free

What may require verification

What's not in scope for this post

Why the email is free

How to check the current pricing

Safety limits you need to know

If you signed up and the API key dashboard didn't show the scope you expected

From signup to automated payments: wiring an AI agent wallet with CAI in 30 minutes

From signup to automated payments: wiring an AI agent wallet with CAI in 30 minutes

Step 1: Create your CAI identity

Step 2: Generate an API key from the dashboard

Step 3: Install the MCP tools

Step 4: Fund the wallet

Step 5: Check your balance

Step 6: Create a payment mandate for autonomous spending

Step 2 — Receive your first `@cai.com` email

If you triggered a hosted-action and the confirmation page didn't render, or the `transfer_status` poll never resolved