x402 賣家指南：如何讓 AI 智能體透過你的 API 付款

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

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

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

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

The flow in four steps

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

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

What the 402 response looks like

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

HTTP/2 402
content-type: application/json

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

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

What happens on the paying agent's side

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

Step 1 -- Prepare the payment:

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

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

Step 2 -- Execute the payment:

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

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

Step 3 -- Verify the settlement

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

Recurring access with payment mandates

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

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

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

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

Guardrails built into the flow

CAI applies three automatic protections on every x402 payment:

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

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

What this means for your API

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

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

The feedback loop

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