# x402 payment workflow (CAI payer adapter)

> Level-3 reference for [skill.md](../skill.md). Fetch: `https://cai.com/skill-references/x402-payment-workflow.md`

## When to use

- Agent hits **HTTP 402 Payment Required** on an API or resource URL.
- Seller documents stablecoin payment (USDC/USDT) to an on-chain address.
- User wants **delegated** small API payments via **payment mandates** (AP2-like limits).

## Flow

1. **Prepare:** `POST /x402-payment-prepare` with `resource_url` and challenge fields (`recipient_address`, `amount`, `chain`, `token`) or embedded `challenge` JSON from the 402 response.
2. **Branch:**
   - `balance_sufficient: false` → `create_deposit_link`, then retry prepare.
   - `requires_user_confirm: true` → ask user to confirm amount, merchant, recipient; then execute with `user_confirmed: true`.
   - Active **mandate** covers payment → execute without per-payment chat confirm.
3. **Execute:** `POST /x402-payment-execute` with `attempt_id` (+ `user_confirmed` when required).
4. **Proof:** response `tx_hash`; follow up with `transfer_status` and `wallet_activity_list` (category `x402`).
5. **Retry resource:** Re-call the original HTTP resource per seller x402 documentation. CAI returns `x402_retry_hint` — the external agent performs the retry.

## Payment mandates

Create delegated limits so agents can pay recurring API fees without asking every time:

```
payment_mandate_create → user approves → payment_mandate_status (active)
→ x402_payment_prepare / x402_payment_execute within max_amount and daily_cap
```

Revoke anytime: `payment_mandate_revoke`.

## Do not claim

- Universal x402 middleware on every seller (honor `GAP_X402_V1`).
- Full Google AP2 credential / card mandate interoperability (honor `GAP_PAYMENT_MANDATE_V1`).
- Automatic HTTP retry to the seller — agent must re-request the resource after payment proof.