DEV Community: CAI

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.

Wiring CAI into OpenClaw, Hermes, Codex, and Cursor: the exact MCP config for each host

CAI — Wed, 02 Sep 2026 06:36:47 +0000

Wiring CAI into OpenClaw, Hermes, Codex, and Cursor: the exact MCP config for each host

The general install is one command, npm i -g @cailab/mcp, and the contract lives at cai.com/skill.md. This post is the host-specific deep-dive: the exact config block for OpenClaw, Hermes, Codex, and Cursor, with the path to the config file, the env var handling, and the restart command.

Before you start

You need:

A CAI account (cai.com/app). The signup is four steps, about 2 minutes.
An API key from the account dashboard. The key has a scope. Start with the read scopes and add pay when you need transfers.
The MCP server installed (npm i -g @cailab/mcp).
The MCP host of your choice installed and running.

OpenClaw

OpenClaw's MCP config lives at ~/.openclaw/mcp.json. Add the CAI server to the mcpServers object:

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

Restart OpenClaw. The CAI tools appear in the agent's tool surface. Verify with openclaw mcp list. The cai server should show as running.

If the server doesn't appear: check the cai-mcp binary is on the PATH (which cai-mcp). If the binary is missing, re-run the install. If the binary is on the PATH but the server still doesn't start, check the API key is valid with curl -H "Authorization: Bearer ***" https://api.cai.com/functions/v1/get-identity.

Hermes

Hermes uses a CLI to add MCP servers:

hermes mcp add cai -- cai-mcp
hermes mcp env-set cai CAI_API_KEY=your-api-key-from-the-dashboard

The env var is stored in the Hermes MCP config. Restart Hermes with hermes restart. Verify with hermes mcp list. The cai server should show as running with the env var set.

Hermes-specific note: Hermes reads MCP env vars at startup, not at request time. If you rotate your CAI API key, you need to update the env var and restart Hermes.

Codex

Codex reads MCP config from ~/.codex/mcp_servers.json. The format is the standard MCP config:

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

Restart Codex. The CAI tools appear in the agent's tool surface. Verify by running a test request. codex mcp test cai should return a successful handshake.

Codex-specific note: Codex's MCP support is newer than OpenClaw's. If you see "MCP server not found" on startup, check the Codex version is up to date. The CAI MCP server requires Codex ≥ 0.x.y (the specific version is in cai.com/developers.html).

Cursor

Cursor's MCP settings are in the UI: Cursor → Settings → MCP → Add new MCP server. The form fields:

Name: cai
Command: cai-mcp
Env: CAI_API_KEY=your-api-key-from-the-dashboard

Click "Add" and Cursor restarts the MCP server. The CAI tools appear in the agent's tool surface. Verify with Cursor → Settings → MCP → cai → Test. The test should return a successful handshake.

Cursor-specific note: Cursor stores the env var in its own keychain, not in a config file. If you rotate your CAI API key, update the env var in the MCP settings UI and click "Save."

A generic host (any MCP-compatible framework)

If the host isn't on the list, the config is the same shape:

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

The MCP server is generic. The contract is in cai.com/skill.md. The tool names are stable. Any host that supports MCP can use the server.

Verifying the install

Once the server is running in your host, run a quick test:

Identity check - get_identity should return your @cai.com address, your wallet bindings, and your linked subwallets.
Balance check - get_wallet_balances should return your balances (or an empty list with a gap_id if you haven't deposited yet).
Transfer test - wallet_custodial_transfer with a tiny amount (0.01 USDC) should return a hosted-action URL. Open the URL, tap once, and the transfer completes.

A few things to keep in mind about the wallet. There is a $200/day auto-limit while the security audit completes. New recipients and new devices always require confirmation. Think of it like cash in your pocket. It works for daily spending without exposing a private key in chat. The vault product (multi-sig, time-locks) is coming for larger balances.

The hosted-action flow

The part of CAI that the user sees most often is the hosted-action flow. When the agent calls wallet_custodial_transfer, the API returns a hosted-action URL. The user opens it, confirms with one tap, and the payment goes through. The agent polls GET /transfer-status for the receipt. No private key in chat, no signature to copy, no browser extension to connect. That single-tap confirmation page is the user's control point for every agent-initiated payment.

If any step fails, the comment section below is the right place to file the bug.

The contract is cai.com/skill.md. The install command is npm i -g @cailab/mcp. The dashboard is at cai.com/app.

If you wired CAI into OpenClaw / Hermes / Codex / Cursor and the tool surface didn't appear

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 API credits to inference costs: how CAI wallets handle agent spending across AI providers

CAI — Fri, 28 Aug 2026 06:17:52 +0000

From API Credits to Inference Costs: How CAI Wallets Handle Agent Spending Across AI Providers

When a developer runs agents across multiple inference providers, each provider wants its own billing method. OpenRouter needs a top-up. Together AI bills monthly. A local GPU provider takes USDC on Base. The developer winds up managing three wallets, four API keys, and a spreadsheet that no one updates.

That situation is what CAI's custodial wallet was designed to replace. Instead of each provider getting a separate payment relationship, the wallet becomes a single payment address that any compatible provider can bill against.

The wallet as operating account

CAI gives every user a custodial wallet on six chains (ETH, BSC, POLYGON, ARB, BASE, TRON) where balances are denominated in USDT, USDC, DAI, and native gas. The wallet is not a standalone product. It is the balance layer under an agent's operating account. When an agent needs to pay for something, it checks identity and balance first, then executes a transfer after the user confirms the recipient and amount.

The API surface for this is three endpoints:

POST /get-wallet-balances   { "chains": ["base", "arb"] }
POST /resolve-transfer-recipient  { "chain": "base", "to_local_part": "user" }
POST /wallet-custodial-transfer   { "chain": "base", "token": "USDC", "amount": "5.00", "to_address": "0x..." }

The user confirms the full parameters before any funds move. The agent never holds a signing key.

x402 for pay-per-call

For providers that expose an HTTP 402 Payment Required flow, CAI's x402 adapter lets agents pay per API call without pre-funding an account. The agent detects the 402, calls x402_payment_prepare with the challenge data, the user confirms (or an active mandate covers it), then x402_payment_execute completes the payment and returns proof.

POST /x402-payment-prepare {
  "resource_url": "https://api.provider.com/chat",
  "recipient_address": "0x...",
  "amount": "0.50", "chain": "base", "token": "USDC"
}
# user confirms
POST /x402-payment-execute { "attempt_id": "...", "user_confirmed": true }

The provider receives settlement and the agent gets the resource. No API key exchange, no pre-payment balance to track.

Payment mandates for automated spending

When the agent runs autonomously (batch inference, overnight fine-tuning, scheduled data processing), the user sets up a payment mandate that delegates spending within defined limits:

POST /payment-mandate-create {
  "merchant_domain": "compute.provider.com",
  "max_amount_per_payment_usd": "10",
  "daily_cap_usd": "200",
  "expires_in_hours": 168
}

The user approves the mandate once. After that, the agent can pay within those bounds without asking for confirmation on every call. The mandate can be revoked at any time via payment_mandate_revoke, and the user can inspect active mandates with payment_mandate_status.

How providers accept CAI payments

A provider does not need to integrate a new payments SDK. CAI settles in USDC (or USDT, DAI) on any of the six supported chains, which most crypto-native infrastructure providers already accept. For providers that want the x402 flow, CAI publishes the x402 challenge spec and adapter endpoints. The provider returns HTTP 402 with a JSON body containing the recipient address, amount, chain, and token. CAI's payer adapter handles the rest.

Providers that want a simpler path can publish a static payment address and let agents call POST /wallet-custodial-transfer directly after the user confirms the amount. No middleware, no escrow, no settlement delay.

Guardrails built in

Every payment flow includes product-level safeguards. Spending for new recipients always requires explicit confirmation even when a mandate exists. The agent proposes, the wallet confirms, and the signing key never enters the tool call. Users set their own caps per mandate (the daily_cap_usd parameter on payment_mandate_create). The vault product at CAI handles encrypted credential storage for site logins and platform API keys as a separate surface.

The practical scenario

An agent running a nightly batch job needs 100 inference calls across three providers. Without CAI, the developer funds each provider separately, watches three balance dashboards, and handles refunds through three support channels. With CAI, the developer deposits USDC once on Base, sets a mandate for the job's $50 budget, and the agent pays each provider from the same wallet, with every spend logged in wallet_activity_list for audit.

The same pattern scales from a single batch job to a fleet of agents running across providers. One wallet, one set of spending rules, one audit trail.

CAI is at https://cai.com. The developer docs and API contract are at https://cai.com/developers.html. The skill.md file at https://cai.com/skill.md has the full tool reference.

x402 and the propose-confirm pattern: how AI agents pay for API calls without a credit card

CAI — Wed, 26 Aug 2026 06:34:40 +0000

The HTTP 402 status code has been in the spec since 1992. Until now, no one built a standard way to actually use it for payments.

x402 is CAI Labs' implementation of HTTP 402 Payment Required for AI agents. It turns a status code into a checkout flow where the agent proposes the spend and a separate context authorizes it, keeping the signing key outside the tool call.

Why HTTP 402 matters for agents

When an AI agent calls an API, it needs to pay for the call. The standard approach is a pre-paid API key, which means the agent either has a static credential that authorizes unlimited spending until revoked, or the developer manually tops up an account. Neither scales well when agents are making thousands of autonomous decisions.

HTTP 402 was designed for exactly this case. The server responds with 402 and a payment challenge. The client resolves the challenge and retries the request. CAI's x402 flow follows this pattern:

The agent calls a paid API and receives a 402 response with a payment challenge (recipient address, amount, chain, token)
The agent calls x402_payment_prepare with the challenge details
If the user has an active payment mandate covering this merchant and amount, the payment proceeds automatically within the mandate's limits
If no mandate exists, the user sees a confirmation prompt in a secure hosted action page
Once confirmed, x402_payment_execute initiates the custodial transfer
The agent retries the original API call with the payment proof

The pattern is a propose-confirm split. The agent proposes the payment parameters, but the signing key that commits the transfer lives in a separate context the agent never accesses. This means a compromised agent cannot forge a payment any more than it can forge a transfer.

Payment mandates for delegated spending

For autonomous agents that need to operate without per-payment approval, CAI supports payment mandates. These are AP2-style limits the user creates ahead of time:

A maximum amount per payment (e.g. $5)
A daily cap (e.g. $200)
An optional merchant domain or recipient filter
An expiration window

When the agent encounters a 402 from a covered domain, x402_payment_prepare skips the user confirmation step and returns a ready-to-execute attempt. The agent can proceed immediately within the mandate's bounds.

How it fits together

The x402 flow is the same pattern as CAI's hosted action flow for transfers. In both cases:

The agent proposes: it identifies what needs to happen and gathers the parameters
A separate context confirms: the user or a mandate authorizes the action
The signing key stays outside the tool scope: no credential touches the agent's runtime

This pattern applies to any side effect with durable cost, not just payments. An agent that proposes a file write, a credential rotation, or a deployment and then hands off confirmation to a separate context is more auditable and safer than one that holds unrestricted signing capability.

The current state

x402 is live and operational as a partial implementation (GAP_X402_V1). Payment mandates are also live as a partial implementation (GAP_PAYMENT_MANDATE_V1). Both support the core flow with automatic daily limits and new-recipient confirmation built in. The vault product that stores long-term site credentials is coming.

MCP servers and agent platforms that want to offer paid tiers can use the x402 pattern as a standard checkout flow. Users do not need to store a credit card on the server or manage a pre-funded API key. The agent encounters the 402, resolves it through CAI, and retries the call. The user sees a single confirmation or sets up a mandate and walks away.

The HTTP 402 status code finally has a real use case, and the agent economy is where it fits.

Budgeting for Autonomous Agents: How CAI Payment Mandates Handle Cloud Compute Costs

CAI — Fri, 21 Aug 2026 06:21:34 +0000

Budgeting for Autonomous Agents: How CAI Payment Mandates Handle Cloud Compute Costs

A developer sets up a batch inference job. The agent finds the cheapest GPU provider, spins up 20 instances, runs the workload for 4 hours, and pays 9.60 USDC from the CAI custodial wallet. No one approves the payment. No credit card was entered. The developer set one payment mandate two weeks ago: "allow up to 50/day to any compute provider on this list." Every transaction appears in the weekly audit. The agent never paused to ask for permission.

That is the workflow payment mandates unlock. This article walks through how to create, use, monitor, and revoke them with the CAI API.

What a payment mandate does

A payment mandate is a delegated spending permission your agent checks against before paying. When your agent calls x402_payment_prepare and an active mandate covers the merchant, amount, and domain, the prepare step may skip the per-payment user confirmation. The agent calls x402_payment_execute with the prepared attempt, and the settlement happens autonomously.

CAI mandates are AP2-like limits. They are not full W3C/AP2 card-network credentials, but they deliver the core pattern: set a budget once, let the agent spend within it, and audit everything later.

Key properties from the API contract:

merchant_domain — the domain the mandate applies to (e.g. runpod.io). Payments to other domains are not covered.
recipient_address — optional. When set, only transfers to that on-chain address count as covered.
max_amount_per_payment_usd — hard cap on any single settlement.
daily_cap_usd — cumulative limit per rolling day.
allowed_resource_patterns — optional URL pattern list for x402 resources (e.g. */gpu/*).
expires_in_hours — mandate auto-revokes after this many hours. No indefinite self-spending.

Creating a mandate

The API is straightforward:

POST /payment-mandate-create
{
  "merchant_domain": "runpod.io",
  "max_amount_per_payment_usd": 5,
  "daily_cap_usd": 50,
  "expires_in_hours": 720
}

The user approves the mandate through CAI's hosted verification page or their dashboard. Once approved, status becomes active. The agent can now reference this mandate on calls to x402_payment_prepare for the same domain.

The CAI product applies a $200/day automatic limit on all custodial payments, including mandate-covered ones. New recipients and new devices still need confirmation until an active mandate covers the merchant domain. That means the first payment to a new provider requires a user check. Subsequent payments to the same domain within the mandate caps do not.

How the agent pays within a mandate

When the agent encounters a payment trigger (an HTTP 402 response, a compute job with a price, or an API that requires settlement), the flow looks like this:

Agent calls POST /x402-payment-prepare with the resource URL, recipient address, amount, chain, and token.
CAI checks balance, checks for an active mandate matching the merchant domain and amount. If covered, requires_user_confirm comes back false.
Agent calls POST /x402-payment-execute with the attempt_id from the prepare step and user_confirmed: true.
CAI settles from the custodial wallet. The response includes a tx_hash and optionally settlement proof.
Agent re-requests the resource with the proof. The seller validates and releases the compute.

Without a mandate, step 2 would set requires_user_confirm: true and the agent would need to ask the user. With the mandate in place, the agent moves straight to step 3.

Monitoring what the agent spent

Two endpoints track mandate usage:

GET /payment-mandate-status returns the current mandate objects with remaining budget and expiry.
GET /wallet-activity-list returns indexed custodial events including every transfer, x402 settlement, and deposit. Filter by category to see only mandate-covered payments.

The audit feed shows the merchant domain, amount, timestamp, and the mandate id that covered the settlement. This is the same feed the developer checks at the end of a compute run.

Revoking a mandate

When the budget expires or the developer decides to cut off spending:

POST /payment-mandate-revoke
{
  "mandate_id": "man_abc123"
}

The mandate status flips to revoked. Any subsequent x402_payment_prepare for that merchant domain will set requires_user_confirm: true again. The agent cannot spend autonomously until a new mandate is created and approved.

Guardrails built into the product

Every CAI custodial wallet operates under product-level limits regardless of mandates:

$200/day automatic spending cap on all custodial payments.
New recipients and new devices always require user confirmation, mandate or not.
Funds come from the custodial wallet. Deposit USDC or use MoonPay for fiat on-ramp. No card on file needed.
The vault product (coming) will add credential-based spending: agents pay on behalf of the user using stored site logins, with the same confirmation pattern.

These guardrails mean the mandate is a convenience layer on top of existing safety rails, not a bypass.

Putting it together: the cloud compute scenario

The scenario from the opening paragraph maps to concrete API calls:

Create mandate: POST /payment-mandate-create with merchant_domain: "runpod.io", daily_cap_usd: 50, expires_in_hours: 336 (2 weeks).
User approves in dashboard. Mandate status: active.
Agent finds cheapest GPU across providers. Picks RunPod. Calls POST /x402-payment-prepare with recipient_address, amount: 2.40, chain: "base", token: "USDC".
CAI matches the mandate. requires_user_confirm: false. Agent calls POST /x402-payment-execute.
Settlement completes. Agent re-requests the compute resource with the proof.
Developer checks GET /wallet-activity-list at end of week, sees the 2.40 USDC entry with the mandate id.

The same pattern works for SaaS subscriptions, API credits, inference time, and any metered billing that can express a merchant domain and an amount.

The tooling layer

The CAI MCP server exposes the same endpoints through the @cailab/mcp npm package. Install it:

npm i -g @cailab/mcp

Then configure in your agent's MCP settings with CAI_API_KEY. The tool names are payment_mandate_create, payment_mandate_status, payment_mandate_revoke, x402_payment_prepare, and x402_payment_execute. Every tool follows the same path contract defined in cai.com/skill.md.

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

The @cai.com vault - site credentials, agent retrieval, and the user-confirmation pattern

CAI — Wed, 19 Aug 2026 06:38:54 +0000

The @cai.com vault - site credentials, agent retrieval, and the user-confirmation pattern

The vault is the part of CAI that removes "please paste your password" from the agent conversation. This post walks through the vault API in detail: how the user saves a credential, how the agent retrieves it, and the user-confirmation pattern that gates every retrieval.

The vault in one sentence

A user-scoped credential store for site logins and passwords. The user saves a credential for example.com. The agent the user builds retrieves it, with the user's explicit confirmation, when the agent needs to log in to example.com on the user's behalf. The vault is encrypted at rest and indexed by site.

What the vault is NOT

The vault is not for the agent's API key. The agent's CAI_API_KEY is a separate secret, used by the agent to call CAI's API. Storing it in the vault is a circular dependency. The vault is for the third-party sites the agent logs in to on the user's behalf.

The vault is not for arbitrary user secrets (API keys for other services, SSH keys, etc.). The vault is scoped to site logins: (site, username, password). For other secret types, use the appropriate secret manager.

Saving a credential (user action)

The user saves a credential from the account dashboard, or the agent the user builds can prompt the user to save a credential after a successful login. The save call:

curl -X POST https://api.cai.com/functions/v1/user-site-credentials \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_url": "https://example.com",
    "username": "alice",
    "password": "..."
  }'

The credential is encrypted at rest. The user can revoke any vault entry from the account dashboard.

Retrieving a credential (agent action, behind user confirmation)

When the agent the user builds needs to log in to example.com, the agent calls vault_get_site_credential which hits GET /user-site-credentials?origin_host=example.com. The retrieval is gated on a user-confirmation hosted-action page. The user sees the site and the username, and taps once to approve.

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

The response includes a hosted-action URL for the user to confirm. After the user taps, the agent receives the credential.

The user-confirmation pattern is the security model. Without the user's tap, the agent does not get the credential. This is the same pattern as the wallet's wallet-custodial-transfer. The agent's API key authorizes the call to the API, but the user's consent on the hosted-action page authorizes the use of the resource.

Why this design

The pattern removes three failure modes that have plagued agent tools since 2024:

The "paste your password" failure mode. The user pastes a password into the agent conversation, the password ends up in the model's context window, the model may log it, and the user has to rotate the password. The vault removes this entirely.
The "agent has the key" failure mode. The agent holds the user's password, the agent's storage is compromised, and the user's password leaks. The vault plus user-confirmation pattern means the agent never holds the password in long-term storage.
The "agent logs in silently" failure mode. The agent logs in to a site the user did not expect, and the user has no visibility into the action. The user-confirmation hosted-action page makes every retrieval a visible, consensual action.

The vault is the practical implementation of "the user is in the loop on every privileged action."

What the agent can do with a retrieved credential

The agent receives the credential as (site, username, password). The agent can use it to log in to the site via the site's own login flow. The agent should not log the credential, should not include it in any error message, and should not pass it to any third-party service.

After the agent is done with the action, the credential is not "checked back in." The vault holds the only copy. The next retrieval is a fresh call.

The vault and the wallet, side by side

	Wallet	Vault
Stores	Stablecoin balances on six chains	Site logins and passwords
Custody	CAI holds the private key	CAI holds the encrypted credential
User-confirmation	`wallet-custodial-transfer` returns a hosted-action URL	`GET /user-site-credentials` returns a hosted-action URL
Authorization	Agent's `CAI_API_KEY` with `pay` scope	Agent's `CAI_API_KEY` with appropriate scope
Receipt	`GET /transfer-status` returns the on-chain tx hash	The agent's logged-in session on the target site

The two surfaces are designed the same way. The user-confirmation pattern is the same pattern. The receipt is the same shape.

Safety first

The vault removes the need to paste passwords into chat, but we built this with practical safety in mind:

Agents operate within a $200/day auto-limit while we complete our security audit.
New recipients and new devices always require user confirmation.
Think of it like cash in your pocket: perfect for daily spending and site logins, not for storing your life savings.
A vault product with multi-sig and time-locks is coming for larger credential sets.

The vault API is in cai.com/skill.md. The user-facing flow is in the account dashboard. Apply at cai.com/app to get a vault.

If you used the vault and the agent retrieved the wrong credential, or the user-confirmation flow did not surface

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.

Payment Intents and Hosted Actions: The Checkout Flow Between Intent and Settlement

CAI — Fri, 14 Aug 2026 06:34:36 +0000

Payment Intents and Hosted Actions: The Checkout Flow Between Intent and Settlement

A SaaS developer adds checkout to their product. A customer clicks "buy." The payment clears. The developer has never written a line of crypto code, and the customer never connected a wallet. This is the design target for the @cai.com checkout flow. The API behind it is a three-layer system: a payment intent that tracks state, a hosted action that replaces wallet signatures with a browser click, and a polling loop that turns that click into settlement.

The Intent

Every payment starts with an intent. The GET /payment-intent-status endpoint is the read side of a state machine. You pass an intent id, and the response tells you where the payment is in its lifecycle. The intent model is partial-live in the current API, the system honors gap_id fields in responses and evolves as checkout scenarios expand, but the state transitions are already stable enough to build production flows around.

GET /payment-intent-status?id=int_abc123

Returns one of: pending, awaiting_user_confirmation, confirmed, completed, or failed. The transition from pending to awaiting_user_confirmation happens when the system receives a valid payment creation that needs the user to authorize it. The transition from confirmed to completed happens after the on-chain settlement reaches the required confirmation depth.

This state machine is what separates a checkout flow from a raw transfer. A raw transfer (POST /wallet-custodial-transfer) is fire-and-forget. You either get a tx hash or an error. An intent allows the system to hold state at each step, pause for user action, and resume automatically.

The Hosted Action

The hosted action link is the mechanism that bridges the gap between an API-driven agent and a human user who needs to confirm a payment. The endpoint is POST /create-hosted-action with a structured JSON body. The critical field is action_type. For payments, you pass deposit or a specific payment-related action type.

POST /create-hosted-action
Content-Type: application/json

{
  "action_type": "deposit",
  "amount_usd": 50,
  "chain": "ETH",
  "token": "usdc",
  "local_part": "alice"
}

The response returns a URL:

{
  "ok": true,
  "url": "https://cai.com/act/a1b2c3d4e5f6",
  "expires_at": "2026-08-14T07:00:00Z"
}

This URL serves a single-tap confirmation page. The user opens it, sees the amount, the destination, and a confirm button. No wallet extension. No gas fee in their browser. No seed phrase. They tap confirm, and the system moves the intent from awaiting_user_confirmation to confirmed.

The hosted action is the product insight that makes agent-initiated payments work in practice. An agent can create an intent, push a confirmation URL to the user's dashboard or email, and wait. The agent never handles the private key. The user never sees an opaque transaction request. Both sides of the trade get the abstraction they need.

The Polling Loop

Once the intent reaches confirmed, the agent polls for settlement. The polling endpoint is the same GET /payment-intent-status, now returning completed with a tx_hash.

GET /payment-intent-status?id=int_abc123

{
  "ok": true,
  "id": "int_abc123",
  "status": "completed",
  "tx_hash": "0x7a8b9c0d1e2f...",
  "chain": "ETH",
  "confirmations": 12,
  "settled_at": "2026-08-14T06:32:00Z"
}

The polling cadence depends on the chain. EVM chains settle in seconds to a couple of minutes. BSC and Polygon are faster. Tron is comparable to EVM. The intent response includes confirmations and a minConfirmations threshold so the agent knows when settlement is considered final.

For agents that need asynchronous notification instead of polling, the POST /transfer-notify-register endpoint accepts an optional webhook_url parameter. When the transfer settles, the system calls the webhook with the tx hash and confirmation count. This is the right pattern for high-volume checkout flows where polling every 5 seconds on 10,000 active intents would be wasteful.

The Full Flow

Putting the three layers together, an end-to-end checkout looks like this:

The merchant's backend calls POST /wallet-custodial-transfer (or creates a marketplace_order) to initiate payment. The response includes an intent id.
The backend creates a hosted action link via POST /create-hosted-action and returns the URL to the merchant's frontend.
The merchant redirects the customer to the hosted action page. The customer sees the amount, the merchant name, and a single confirm button.
The customer confirms. The backend receives a callback (or the frontend polls the intent status) showing confirmed.
The backend starts polling GET /payment-intent-status for the intent id, or waits for the webhook via POST /transfer-notify-register.
The intent transitions to completed. The backend records the tx hash and updates the order status.

The remarkable property of this flow is that step 3 never shows the customer a blockchain address, a gas fee estimate, or a transaction signing request. The checkout page looks exactly like a credit card checkout, except the settlement happens on-chain in stablecoins.

Guardrails Built Into the Flow

The hosted action flow includes two safety mechanisms that are important for production deployments.

First, the daily auto-limit is capped at $200 USD per account for agent-initiated payments. This limit applies at the API key level and resets daily. It prevents a compromised key from draining an account. Users who need higher limits can adjust them in the dashboard settings at cai.com/app.

Second, new recipients trigger a confirmation requirement. When the agent tries to send to an address or email that has never received a payment from this account before, the hosted action page shows a prominent warning about the new recipient. The user must explicitly confirm before the payment proceeds. This prevents a common attack pattern where an attacker substitutes their own address in a payment request.

The vault product (credential storage and rotation) covers the case where the agent's API key itself is compromised, but that is a separate track from the payment flow.

What This Enables

The intent-plus-hosted-action pattern is the foundation for several checkout models:

SaaS checkout. A subscription service generates a hosted action URL for each billing cycle. The user confirms once per period. No saved payment methods, no recurring charge disputes, no PCI scope.

Agent-to-agent settlement. Agent A needs to pay Agent B for a completed task. Agent A creates an intent and a hosted action link, which the user confirms. Both agents receive the settlement notification.

One-time storefront purchases. A digital goods storefront generates a hosted action link at checkout. The customer confirms in one tap. The store receives the payment in USDC within seconds.

Each of these models relies on the same three-layer architecture: create the intent, confirm via hosted action, poll until settlement. The abstraction is consistent whether the buyer is a human clicking a link or an agent calling an API.

The Polling Implementation

A practical polling implementation in Python looks like this:

import time, requests

def poll_payment_intent(intent_id, interval=5, timeout=300):
    deadline = time.time() + timeout
    while time.time() < deadline:
        resp = requests.get(
            f"https://api.cai.com/functions/v1/payment-intent-status?id={intent_id}",
            headers={"Authorization": f"Bearer {CAI_API_KEY}"}
        )
        data = resp.json()
        if data.get("status") in ("completed", "failed"):
            return data
        time.sleep(interval)
    raise TimeoutError(f"intent {intent_id} did not settle in {timeout}s")

For production, replace the synchronous loop with an async version or use the webhook path. The synchronous version is fine for low-volume checkout flows where the merchant processes a few hundred payments per day.

Status-Code Handling

Every endpoint in the flow follows the same error contract as the rest of the CAI API. 401 means the API key is invalid or expired. 403 means the key has insufficient scope (checkouts require pay or full scope). 429 means rate limiting. Back off and retry with exponential delay.

The intent-specific error codes include a gap_id field when the requested feature is still partial-live. Treat a gap_id response the same way you treat a 503: the feature exists but has limitations. Check the capabilities page at cai.com/capabilities for the current status of each feature.

Summary

The checkout flow built on payment intents and hosted actions solves a specific problem: how does an agent initiate a payment and get confirmation from a human user without sharing private keys, without asking the user to install a wallet, and without requiring the merchant to hold crypto? The answer is a stateful intent, a single-tap confirmation page, and a polling loop. The settlement happens in USDC on chain, but neither the buyer nor the seller touches the blockchain directly.

Documentation: cai.com/skill.md · cai.com/developers.html · cai.com/capabilities.html

If You Tried the Checkout Flow and Hit a Bug

Comment below with:

What you ran the curl command, the create-hosted-action request, the intent id you polled.
What you expected the checkout to complete in one line, or the intent to transition to completed.
What you got the error message, the unexpected status, the timeout.
Your environment OS, Node or Python version, the MCP host (OpenClaw, Hermes, Codex, Cursor, or other), the CAI account tier.

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

The @cai.com wallet API: balances, transfers, and the hosted-action flow

CAI — Wed, 12 Aug 2026 06:34:06 +0000

The @cai.com wallet API: balances, transfers, and the hosted-action flow

The wallet is the most-requested deep-dive from the four-pillars post. This post walks through the wallet API in detail: how to check balances, how to send a payment, how the user-confirmation pattern works, and the difference between custodial and self-custody.

The wallet in one sentence

A custodial multi-chain stablecoin wallet. Six chains. External wallets supported. MoonPay for fiat on-ramp. One custodial account for pay, transfer, convert, and bridge. No private key in chat.

Checking balances

The POST /get-wallet-balances endpoint returns the user's balances on one or more chains. The request is a JSON body with the chains and tokens to query.

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

The response includes the custodial wallet_binding addresses and any linked subwallets (read-only RPC for the external wallets the user has connected). Entries may include linked_subwallet: true for external wallet balances.

Common gotcha. If you query a chain the user hasn't deposited to yet, the response may include empty activity for that chain. That is expected behavior; the chain is supported, the indexer just hasn't seen any activity for this user yet.

Sending a payment

The POST /wallet-custodial-transfer endpoint initiates a payment. The response is a hosted-action URL. The user opens it, sees the recipient, the amount, and the chain, and taps once.

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 the user-confirmation pattern. The agent's API key is the authorization to call the CAI API on the user's behalf, but every transfer still needs the user's consent on the hosted-action page. The page is HTTPS, the tap is bound to a single transaction, and the URL expires in a short window. If the user does nothing, the payment does not go through.

Polling for the receipt

After the user taps once, 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": "0x..."}'

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

Custodial vs self-custody

A custodial wallet means the user does not hold the private key. CAI holds it. The user gets a @cai.com address on each of six chains and can pay, transfer, convert, and bridge from any of them.

The difference from self-custody is the user-confirmation pattern. With self-custody, the user holds the key, signs each transaction, and is responsible for key management. With CAI's custodial wallet, the user holds the address and the user-confirmation tap; CAI holds the key and the signing infrastructure. The trade-off: CAI is a trusted third party for custody, but the user never has to paste a private key into an agent conversation.

External wallets are supported. Connect a MetaMask or a Ledger and the user keeps custody of their external assets while using CAI for the day-to-day. The external wallets appear as linked subwallets in the get-wallet-balances response.

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

Top-up flows

To add funds to the wallet, the user can:

Send from an external wallet to the CAI custodial address on the chosen chain. The address is in the account dashboard.
Buy with MoonPay (fiat on-ramp). The account dashboard has a "Buy with MoonPay" button for each chain. MoonPay is a third-party service; regional availability and KYC requirements apply.
Use WeChat Pay (Planned). The WeChat Pay path is documented in cai.com/capabilities.html.

Each top-up flow eventually surfaces a hosted-action URL or a direct deposit link that the user completes on the chosen rail.

The wallet API is in cai.com/skill.md. The hosted-action flow is in cai.com/agent-payment.html. Apply at cai.com/app to get a wallet.

If you wired the wallet API and got an unexpected balance, a 5xx, or a missing `wallet_binding`

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.

DEV Community: CAI

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 7: Test the x402 payment flow

The full picture

If you tried this and hit a bug

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

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

The call

The confirmation page

Why the user is in the loop

The receipt

Failure modes

Why this design

Spending and safety limits

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

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

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

How it works

What the developer sees

The cash-in-pocket rule

The vault connection

Putting it together

Wiring CAI into OpenClaw, Hermes, Codex, and Cursor: the exact MCP config for each host

Wiring CAI into OpenClaw, Hermes, Codex, and Cursor: the exact MCP config for each host

Before you start

OpenClaw

Hermes

Codex

Cursor

A generic host (any MCP-compatible framework)

Verifying the install

The hosted-action flow

If you wired CAI into OpenClaw / Hermes / Codex / Cursor and the tool surface didn't appear

From API credits to inference costs: how CAI wallets handle agent spending across AI providers

From API Credits to Inference Costs: How CAI Wallets Handle Agent Spending Across AI Providers

The wallet as operating account

x402 for pay-per-call

Payment mandates for automated spending

How providers accept CAI payments

Guardrails built in

The practical scenario

x402 and the propose-confirm pattern: how AI agents pay for API calls without a credit card

The HTTP 402 status code has been in the spec since 1992. Until now, no one built a standard way to actually use it for payments.

Why HTTP 402 matters for agents

Payment mandates for delegated spending

How it fits together

The current state

Budgeting for Autonomous Agents: How CAI Payment Mandates Handle Cloud Compute Costs

Budgeting for Autonomous Agents: How CAI Payment Mandates Handle Cloud Compute Costs

What a payment mandate does

Creating a mandate

How the agent pays within a mandate

Monitoring what the agent spent

Revoking a mandate

Guardrails built into the product

Putting it together: the cloud compute scenario

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

If you wired the wallet API and got an unexpected balance, a 5xx, or a missing `wallet_binding`