Docs

How x402 works

x402 is Coinbase's HTTP 402 micropayment protocol. It revives the long-dormant 402 Payment Required status code from RFC 7231 and binds it to USDC settlement on Base. The protocol is open, the foundation includes Coinbase, Cloudflare, AWS, Visa, Anthropic, Vercel, and Circle, and it's already settled 75M+ transactions across 94k+ unique buyers as of mid-2026.

Cloven ships x402 as a first-class auth path alongside API-key + credit-balance flows.

Why x402 for Cloven

Agent-to-agent friendly. An autonomous agent with a wallet (Coinbase AgentKit, ClawBank, Phantom, a bare embedded EOA) can pay Cloven without a human in the loop. No "log in, paste key, configure dashboard." The agent reads its own ETH balance, signs its own USDC transfer, and pays its own bill — exactly the workflow autonomous agents need.

Aligned with the serious institutional rails. AWS Bedrock integrating x402, and the Coinbase / Circle / Visa / Anthropic foundation membership are real signals. Not memecoin. Not LARP. Cloven leans into the rails because they are the ones serious AI infrastructure is going to use.

Composable with $CLOVEN (Phase 3). Stake-tier discounts plug in cleanly: the wallet paying via x402 is the same wallet whose $CLOVEN stake determines its tier. Discount math happens at quote time, no separate ledger.

Real revenue, real burn. 50% of x402 revenue routes to $CLOVEN buyback-and-burn once Phase 3 lands. Transparent, on-chain, audit-able. Phase 1 accumulates the 50% share in a public reserve wallet.

Five-step flow

1.  Agent       →  Cloven    GET /v1/fresh?pack=crypto             (no auth)
 
2.  Cloven      →  Agent     402 Payment Required
                              { x402_version: 1,
                                accepts: [ { network: "base",
                                             asset:   USDC contract,
                                             amount:  "1000",        ← 6 decimals
                                             recipient: 0xClovenTreasury,
                                             validUntil: <unix sec>,
                                             nonce:   <server uuid> } ] }
 
3.  Agent       →  Base      USDC.transfer(recipient, amount, nonce)
 
4.  Agent       →  Cloven    GET /v1/fresh?pack=crypto
                              X-Payment: base64({
                                scheme:  "exact",
                                network: "base",
                                txHash:  0xabc...,
                                payer:   0xWallet... })
 
5.  Cloven      →  Agent     200 OK
                              X-402-Settled: 0xabc...
                              X-402-Amount-Paid: 1000
                              { state, brief, citations, freshness }

The 402 quote includes a server-generated nonce so each tx encodes uniqueness. Cloven verifies the on-chain USDC.Transfer event against recipient, amount, and nonce (encoded in the call data or, optionally, a follow-up Memo event). Once verified, the tx hash is cached in Redis for 24 hours under x402:tx:<hash> to prevent replay.

What "verified" means

A payment is accepted iff every condition holds:

  1. Tx exists on Base. eth_getTransactionReceipt(txHash) returns a receipt.
  2. Tx is confirmed (status === 0x1).
  3. Tx emitted a USDC.Transfer(from = payer, to = recipient, value ≥ amount) event.
  4. Recipient matches X402_RECIPIENT_ADDRESS env var (Cloven treasury).
  5. Tx confirmed within the last 10 minutes (anti-replay).
  6. x402:tx:<txHash> key is not already set in Redis (idempotency).

Any failure → 402 with a typed error code (tx_too_old, insufficient_payment, wrong_recipient, tx_already_settled). No partial credit, no "we'll honor it next time." The agent must re-quote and pay fresh.

What it is NOT

  • Not a subscription protocol. x402 is per-call only. Credit packs handle bulk keyed flows.
  • Not multi-chain. USDC on Base only. Solana, Optimism, Arbitrum are deferred until traffic justifies the extra verification surface.
  • Not gasless. The agent's wallet pays ETH gas on Base (~$0.0001 per tx). Permit2 / EIP-2612 gasless flows are Phase 1.5.
  • Not paid in $CLOVEN. $CLOVEN is for stake-tier discounts, not as a payment asset. Keeping the token clean of "money grab" framing is deliberate.

What you actually do

If you're writing your own client: see the payments page for the exact wire format. If you're using @cloven/sdk: pass a viem WalletClient to the factory and the entire flow happens transparently — see SDK x402 mode.

On idempotency

The 24-hour idempotency window means: pay once, retry the API call as many times as you like for 24 hours. Useful if the connection drops between Step 4 and Step 5 — replay the call with the same x-payment header and Cloven serves the response without double-charging.

After 24 hours the tx hash purges from the idempotency cache. Re-using it after the purge returns tx_too_old (the on-chain confirmed_at is now > 10 min). At that point, pay fresh.

What gets traced

Every x402-paid call writes a traces row tagged paid_via: "x402", with amount_usd populated from the actual USDC paid. Phase 3 Commons reads these to compute trace-contributor revshare — your agent's wallet earns when its traces sell to AI labs (if the operator opted in).