DEV Community

CAI
CAI

Posted on

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

#ai #mcp #tutorial #webdev

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
Enter fullscreen mode Exit fullscreen mode

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_..." }
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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_..."
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

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/...", ...}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"]}'
Enter fullscreen mode Exit fullscreen mode

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
  }'
Enter fullscreen mode Exit fullscreen mode

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_..."
Enter fullscreen mode Exit fullscreen mode

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":"..."}'
Enter fullscreen mode Exit fullscreen mode

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"
  }'
Enter fullscreen mode Exit fullscreen mode

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
  }'
Enter fullscreen mode Exit fullscreen mode

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:

  1. What you ran - the install command, the curl request, the MCP host config. Copy the actual command.
  2. What you expected - one sentence.
  3. What you got - the error message, the empty response, the unexpected behavior. Paste it verbatim.
  4. 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.

Top comments (0)