DEV Community: CAI

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.

Accepting payments with @cai.com: adding CAI checkout to your website or SaaS

CAI — Fri, 07 Aug 2026 06:29:06 +0000

Accepting payments with @cai.com: adding CAI checkout to your website or SaaS

A SaaS developer wants to accept payments without a merchant account, without chargebacks, and without asking customers to leave the checkout flow. A marketplace needs to collect payments from buyers and settle them to sellers. An AI agent needs to pay for API access programmatically. All three scenarios converge on the same problem: how does money move from payer to payee without a Plaid link, a Stripe onboarding, or a wallet address pasted in chat?

The @cai.com payment path covers two sides. The payer side (an agent paying from a CAI wallet, or a human tapping a hosted confirmation page) has been covered elsewhere. This post covers the merchant side: how to accept payments through CAI, what the API looks like, and where the honest limits are.

The two payment paths for merchants

CAI exposes two distinct receive paths, and the choice between them depends on how the customer pays.

Card (fiat) path: create_onramp_url returns a MoonPay-hosted URL where the customer pays by credit card. The funds land in the merchant's custodial EVM address as USDC (or the selected stablecoin). The merchant needs a CAI API key with pay or full scope.

Crypto path: create_deposit_link returns a CAI-hosted page (/act/<token>) showing the merchant's custodial addresses and QR codes. The customer sends crypto from their own wallet, and the deposit is indexed by CAI's activity feed.

The two paths are not interchangeable. Card works for customers who hold fiat. Crypto works for customers who hold USDC or other supported tokens. The merchant can offer both, or one, depending on their customer base.

The card path: create_onramp_url

The card path routes through MoonPay, which handles the fiat-to-crypto conversion, compliance checks, and card network processing. The merchant does not need a separate MoonPay account. The CAI API key is the only credential.

curl -X POST https://api.cai.com/functions/v1/create-onramp-url \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_usd": 50.00,
    "default_currency_code": "usdc_eth"
  }'

The response includes a url that the merchant redirects (or links) the customer to. The customer fills in their card details on MoonPay's hosted page, and the crypto lands in the merchant's custodial EVM address. The walletAddress is set server-side to the API key owner's custodial address, so the merchant does not need to specify a destination.

This is not a full payment processor. There is no cart abstraction, no order webhook, and no inventory management. The receipt is the MoonPay payment intent. The merchant confirms the payment by polling GET /payment-intent-status with the intent id, or by checking GET /wallet-activity-list for the incoming deposit.

Honest limit: MoonPay is a third-party provider. KYC requirements and regional availability apply. If MoonPay is unavailable for a given region (the API returns a 503 with GAP_ONRAMP_V1), the card path is unavailable for that customer. The honest fallback is the crypto deposit path.

The crypto path: create_deposit_link

For customers who already hold crypto, the deposit path is simpler. The merchant calls create_deposit_link and gets a CAI-hosted page.

curl -X POST https://api.cai.com/functions/v1/create-hosted-action \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "action_type": "deposit"
  }'

The response is a url like https://cai.com/act/<token>. The merchant sends this URL to the customer. The customer opens it, sees the merchant's custodial addresses and QR codes for each chain, and sends crypto from their wallet. The deposit is indexed by CAI's activity feed and appears in GET /wallet-activity-list.

The deposit link is single-use and short-lived. The customer has a window to complete the deposit before the URL expires. The merchant can verify the deposit by polling GET /wallet-deposit-activity or GET /wallet-activity-list with the customer's name or reference.

For the crypto path, the merchant's custodial address is printed on the page. The customer sends from their own wallet, whether that is a CAI wallet, a MetaMask, a Ledger, or any other wallet that supports the target chain. The merchant does not need to know which wallet the customer uses.

The hosted action pattern

Both paths build on the same hosted action infrastructure. A hosted action URL is a CAI-hosted page that the payer or the customer opens in a browser. The page is HTTPS, the token is single-use, and the URL expires in a short window (typically 15 minutes). The page does not require the visitor to have a CAI account.

The hosted action is the user-confirmation surface. The payer sees the recipient, the amount, the chain, and taps once. The merchant sees the confirmation on the other side. The hosted action pattern is the same regardless of whether the flow is a deposit, a transfer, a login, or a wallet connect.

Confirming the payment

After the customer completes the payment (card or crypto), the merchant needs to confirm it landed. The confirmation tool depends on the payment method.

For card payments via MoonPay, the merchant polls GET /payment-intent-status with the payment intent id returned by the MoonPay flow. The response includes the status, the on-chain tx hash, and the confirmation count.

For crypto deposits, the merchant reads from the activity feed. GET /wallet-activity-list with direction: "in" and category: "deposit" returns the indexed deposits. If the deposit is not yet indexed, GET /wallet-deposit-activity or POST /wallet-deposit-confirm (with the tx hash) can surface it.

The distinction matters: card payments are confirmed through the payment intent API, not through the transfer status API. Crypto deposits are confirmed through the activity feed, not through the transfer status API. The transfer status API is for outbound custodial transfers, not for incoming deposits.

Guardrails and honest limits

CAI's receive path is designed for daily spending, not for treasury-sized balances. The $200/day auto-limit applies while the security audit completes. 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.

The card path routes through MoonPay, which is a third-party provider. KYC and region limits apply. The crypto path is self-service: the customer sends from their wallet, and the merchant confirms on the activity feed.

The receive path is not a full payment processor. There is no cart, no order webhook, no inventory management, and no chargeback handling. The merchant handles the business logic of linking a payment to an order, and CAI handles the settlement.

If you tried the receive flow and hit a bug

Comment below with:

What you ran -- the API call, the hosted action URL, the curl command. Copy the actual request or the page URL.
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.

Setting up your agent's operating account: sign up at cai.com/app in 4 steps

CAI — Wed, 05 Aug 2026 06:36:57 +0000

Setting up your agent's operating account: sign up at cai.com/app in 4 steps

Your agent needs an operating account. Here is how to set one up in about 2 minutes, no card required, no private key to paste in chat.

The signup at cai.com/app is four steps. This post walks through each step with what the user sees, the actual fields, and what to do if a step fails. The steps below match the current cai.com/app page.

Step 1: Open cai.com/app and pick "Apply for @cai.com email"

Go to cai.com/app. The page has a single CTA: "Apply for @cai.com email." Click it. The first form field is your name.

Step 2: Enter your name

That's the only field on the first screen. There is no email field on this step; the email is collected next. Enter your name, click continue.

Step 3: Enter your existing email (this is where the 6-digit code goes)

CAI emails a 6-digit verification code to the address you provide. The code expires in 15 minutes. Enter the code into the form when it arrives.

If the code doesn't arrive:

Check spam. CAI's verification email is plain text with a 6-digit code; some providers sort it to spam if you haven't seen mail from cai.com before.
Wait 60 seconds. The email is sent immediately after you submit the form, but delivery can lag.
Click "Resend code" if the form has the option. A new code invalidates the old one.

If the code expires before you paste it: you can request a new one from the same form. The old code is invalidated; the new code has a fresh 15-minute window. There is no waiting for support.

Step 4: Enter the code, create a password, and you're done

Enter the 6-digit code, set a password (8+ characters, the form's complexity rules apply), and the signup completes. You are redirected to the account dashboard.

What you have at the end

After the four steps, you have:

A @cai.com email address. The SMTP/IMAP credentials are in the account dashboard if you want to use a desktop client.
A custodial multi-chain stablecoin wallet. The wallet is empty until you top it up; the four product pillars post covers the wallet in detail.
A user vault for site credentials. Empty until you add credentials; the same post covers the vault.
An API key for the agent you build or use. The key is in the account dashboard. Free tier covers read scopes; pay and full scopes may require verification.

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.

The signup takes about 2 minutes. No card is required. The email is free.

What to do next (technical reader)

If you are the technical reader, the one who reads dev.to to install things, the next step is npm i -g @cailab/mcp. The package drops the CAI MCP server into any MCP-compatible host: OpenClaw, Hermes, Codex, Cursor. The full quickstart is in cai.com/developers.html.

The contract an agent reads first is cai.com/skill.md. The companion artifact is the A2A Agent Card at cai.com/.well-known/agent.json.

How the agent logs in on your behalf

Once the account exists, the agent does not need your password. The CAI API exposes a hosted login flow: an agent calls POST /create-hosted-action with { "action_type": "login" } and gets back a url. That URL is a CAI-hosted page the user opens and confirms. The agent never types your credentials into chat, and the login link is one-time and short-lived.

That pattern is the same shape as the wallet's user-confirmation flow. The agent's API key is the authorization; the user's tap on a hosted page is the consent. You keep the password, and the agent keeps the ability to act on your behalf within the confirmations you allow.

Apply at cai.com/app. The signup is four steps, about 2 minutes, no card.

If you went through the signup flow described above and the code didn't arrive, expired too fast, or failed silently

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.

Pay Anyone by Their Name: How the @cai.com Directory Replaces Wallet Addresses

CAI — Fri, 31 Jul 2026 07:04:16 +0000

Sending a friend 20 USDC should not require copying a hex string from a chat app, checking the chain, and hoping the network matches. The @cai.com directory replaces wallet addresses with handles. Type the name, pick the handle, and the money moves.

This post covers the @cai.com address directory, how it resolves handles to wallets, and how person-to-person payments work without the user ever seeing a hex string.

The directory

The @cai.com directory maps every registered user to their custodial wallet addresses across six chains. When you sign up at cai.com/app, you get a handle like alice@cai.com and a wallet address on each supported chain. The directory stores the mapping.

The directory is not a blockchain itself. It is a lookup table that CAI maintains. The agent that needs to pay someone calls resolve-transfer-recipient with the recipient's email or handle, and gets back the canonical address on the requested chain.

The API call is straightforward:

curl -sS https://api.cai.com/functions/v1/resolve-transfer-recipient \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{"chain": "BASE", "to_email": "friend@cai.com"}'

Response:

{
  "canonical_email": "friend@cai.com",
  "to_address": "0x..."
}

How payments work through the directory

Once the address is resolved, the agent initiates the transfer. The user confirms on a hosted-action page, and CAI executes the custodial transfer on the requested chain.

curl -sS https://api.cai.com/functions/v1/wallet-custodial-transfer \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "BASE",
    "token": "usdc",
    "amount": "20.00",
    "to_email": "friend@cai.com"
  }'

Notice the to_email field. The agent never touches a wallet address. It resolves the handle, then passes the handle back to the transfer endpoint. CAI handles the address resolution internally on the second call.

The public surface

The directory also has a public facing side. The cai.com/.well-known/agent.json file is the A2A Agent Card that lets other agents discover how to interact with CAI. The cai.com/capabilities.html page lists which features are live, which are in beta, and which carry gap IDs.

For the @cai.com address directory specifically:

Live (per capabilities.html): The directory is operational. All registered users are discoverable by their @cai.com handle.
Chain support: ETH, BASE, POLYGON, SOLANA, ARBITRUM, and OPTIMISM.
Gap ID: GAP_RESOLVE_V1 — signals that the resolution is live but may not cover every edge case (e.g., unregistered handles return a clear error, not a silent fail).

What this means for agents

An agent that needs to pay someone does not need to ask for a wallet address. It asks for the person's @cai.com handle. The agent resolves it, checks the balance, and initiates the transfer. The user confirms with one tap.

This is the same flow whether the agent is paying a freelancer, settling a split bill, or sending a recurring payment to a landlord. The directory abstracts the chain complexity. The agent works with names, not addresses.

The end-to-end

A complete payment flow through the directory:

Agent calls get-identity to confirm the user has a CAI account.
Agent asks the user for the recipient's @cai.com handle.
Agent calls resolve-transfer-recipient with the handle and the preferred chain.
Agent calls get-wallet-balances to confirm sufficient funds.
Agent calls wallet-custodial-transfer with the recipient's handle.
User confirms on the hosted-action page.
Agent confirms the payment landed via wallet-activity-list.

Every step works with the handle. The agent never sees a private key, never copies a hex address, and never asks which network the recipient is on.

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

If you tried this flow and hit a bug, comment below with the command you ran, what you expected, and what you got. Bug reports get replied to within 24 hours.

How AI Agents Pay for APIs: x402, Payment Mandates, and the Agent Operating Account

CAI — Wed, 29 Jul 2026 09:51:45 +0000

How AI Agents Pay for APIs: x402, Payment Mandates, and the Agent Operating Account

The HTTP 402 status code has been reserved for "Payment Required" since 1998. For most of the web's history, it sat unused. But AI agents making API calls autonomously are finally giving it real traffic.

When an agent hits a paid API endpoint, the question shifts from "can it pay?" to "how does it pay without waking a human for every dollar?" That breaks into two parts: a protocol for agent-to-API payment (x402) and a delegation mechanism (payment mandates) that lets agents spend within user-defined limits without asking permission each time.

The x402 flow

The x402 protocol is straightforward. An agent calls an API endpoint. The API responds with HTTP 402, including a payment challenge in the response body. The challenge specifies the recipient address, amount, chain, and token. The agent forwards this challenge to a payer service, which checks the user's balance and executes the transfer.

CAI's implementation uses three endpoints.

First, POST /x402-payment-prepare takes the challenge from the API and checks whether the user has sufficient balance and whether an active mandate covers this merchant. It returns an attempt_id and a requires_user_confirm flag. When the user has set up a payment mandate for this domain, the flag is false and the agent can proceed.

Second, the agent calls POST /x402-payment-execute with the attempt_id and user_confirmed: true (or skips confirm when the mandate covers it). CAI executes the custodial transfer on the requested chain and returns a tx_hash as proof.

Third, the agent re-requests the paid API resource, attaching the tx_hash or x402_retry_hint from CAI's response. The API verifies the on-chain payment and serves the resource.

The retry is the agent's responsibility. CAI returns the proof of payment. The agent presents it to the seller.

Payment mandates: spending limits for autonomous agents

The mandate system is the more interesting piece. A payment mandate is a user-created permission that lets an agent spend up to certain limits on a specific merchant domain without asking for confirmation every time.

The flow starts with POST /payment-mandate-create. The user specifies the merchant_domain, a max_amount_per_payment_usd, a daily_cap_usd, optional allowed_resource_patterns, and an expires_in_hours value. The user approves the mandate through CAI's hosted verification page. Once active, the agent can call x402_payment_prepare for any charge on that domain, and the response sets requires_user_confirm: false as long as the charge stays within the mandate's limits.

The user can revoke the mandate at any time with POST /payment-mandate-revoke or inspect active mandates with GET /payment-mandate-status.

This follows the same pattern as the AP2 (Authorization Protocol for Payments) concept, but CAI's implementation is a CAI-native version. The system enforces spending caps per payment and per day, and the domain pattern matching limits which API endpoints the mandate covers.

Where the agent gets its wallet

Before any of this works, the agent needs a wallet to pay from. CAI's model is a custodial multi-chain wallet accessed via API key. The agent calls GET /get-identity to confirm the account exists, then POST /get-wallet-balances to check balances on the relevant chain.

If the balance is insufficient, the agent can generate a deposit link with POST /create-hosted-action (with action_type: "deposit") or use the fiat on-ramp via MoonPay (third-party KYC applies). The agent does not handle private keys. It calls the CAI API, and CAI executes the custodial transfer.

The full sequence is documented in the skill.md contract at https://api.cai.com/functions/v1, which is the single source of truth for all endpoints, scopes, and gap IDs.

The MCP path

For agents that use the Model Context Protocol, the @cailab/mcp npm package provides a stdio transport that exposes the same set of tools. The agent sets CAI_API_KEY as an environment variable and the MCP server handles the authentication and routing. The same x402 endpoints, mandate tools, and wallet operations are available through the MCP interface.

Early access guardrails

Since this is early access, CAI applies a $200 per day automatic spending limit. New recipients and new devices need user confirmation before the first transfer. The vault product for storing third-party site credentials is also available, which lets agents store and retrieve login credentials for platforms they interact with.

The honest label

The capabilities page at cai.com/capabilities.html marks x402 as Live and payment mandates as Live. Both carry gap IDs (GAP_X402_V1, GAP_PAYMENT_MANDATE_V1) that signal the implementation is operational but may not cover every edge case. The gap IDs are part of the API response, so agents can check them and adjust their behavior accordingly.

WeChat Pay is listed as Planned. Bridge and cross-chain transfers are Live (with GAP_BRIDGE_V1). The fiat on-ramp via MoonPay is Live with third-party KYC limits.

What this means for agent developers

Agent-to-API payment is no longer a design problem you need to solve from scratch. The x402 protocol gives you a standard way to handle HTTP 402 challenges. The mandate system lets agents operate autonomously within user-defined limits. The custodial wallet model means the agent never touches a private key.

The API contract lives at cai.com/skill.md. The MCP package is on npm. The capabilities matrix is at cai.com/capabilities.html. The agent calls get_identity, checks balances, and pays when it needs to.

The 402 status code has been waiting for a use case since 1998. AI agents might be the one that finally makes it stick.

DEV Community: CAI

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

The tooling layer

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

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

The vault in one sentence

What the vault is NOT

Saving a credential (user action)

Retrieving a credential (agent action, behind user confirmation)

Why this design

What the agent can do with a retrieved credential

The vault and the wallet, side by side

Safety first

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

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

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

The Intent

The Hosted Action

The Polling Loop

The Full Flow

Guardrails Built Into the Flow

What This Enables

The Polling Implementation

Status-Code Handling

Summary

If You Tried the Checkout Flow and Hit a Bug

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

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

The wallet in one sentence

Checking balances

Sending a payment

Polling for the receipt

Custodial vs self-custody

Top-up flows

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

Accepting payments with @cai.com: adding CAI checkout to your website or SaaS

Accepting payments with @cai.com: adding CAI checkout to your website or SaaS

The two payment paths for merchants

The card path: create_onramp_url

The crypto path: create_deposit_link

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