minia2a

Posted on Aug 11 • Originally published at minia2a.uk

HTTP 402 for Autonomous Agents: The 3-Day Auto-Mode Readiness Checklist

#x402 #ai #api #claude

Claude Code auto-mode becomes the default permission setting on August 14, 2026 — three days from now.

When auto-mode agents encounter an HTTP 402 response, they need to parse it without a human reading the error message. No popup. No "click to approve." No credit card form. Just machine-readable payment instructions the agent can act on autonomously.

If your API uses x402 / HTTP 402 for agent payments, this checklist is for you. Five items. Three days.

1. Machine-Readable 402 Response

When an agent hits your API without payment, you return HTTP 402. There are two valid approaches. Pick one — but use at least one:

Approach A: HTTP Headers (simpler, works everywhere)

HTTP/2 402 Payment Required
x-402-amount: 5
x-402-chain: base
x-402-token: USDC
x-402-recipient: 0xf16F0882de08315B438E9f3a2Abfb2d2E5d94ECA

Approach B: x402 v2 Body Format (richer, multi-facilitator)

This is the format used by minia2a.uk v5, Coinbase agentic.market, and the x402 Foundation reference implementation:

HTTP/2 402 Payment Required
content-type: application/json

{
  "accepts": [{
    "network": "base",
    "chainId": 8453,
    "facilitator": "https://facilitator.payai.network",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "recipient": "0xf16F0882de08315B438E9f3a2Abfb2d2E5d94ECA",
    "amount": 1000,
    "description": "USDC on Base"
  }],
  "PAYMENT-REQUIRED": "<base64-encoded payment challenge>",
  "amount": 1000,
  "priceCents": 0.1
}

The v2 format is more powerful: multi-chain, multi-facilitator support, and the PAYMENT-REQUIRED field encodes a signed payment challenge that facilitators verify on-chain.

✅ PASS: Your 402 includes EITHER: payment headers OR an accepts array with network/chainId/facilitator/asset/recipient/amount.
❌ FAIL: Your 402 returns neither. An HTML pricing page leaves the agent stranded.
⚠️ CHECK: Distinguish "trial exhausted" (amount=0, guide to register) from "credits depleted" (amount>0, guide to pay).

2. Payment Instruction Fields Reference

Field	Required	Example	Notes
`accepts[].network`	✓	`"base"`	Chain name
`accepts[].chainId`	✓	`8453`	EIP-155 chain ID
`accepts[].facilitator`	✓	`"https://facilitator.payai.network"`	Payment settler
`accepts[].asset`	✓	`"0x833589fC..."`	Token contract address
`accepts[].recipient`	✓	`"0xf16F0882..."`	Payment destination
`accepts[].amount`	✓	`1000`	In token smallest unit
`PAYMENT-REQUIRED`	v2	`"eyJhbXQiO..."`	Base64 payment challenge
`priceCents`	nice	`0.1`	Human-readable price

3. Discovery Endpoint: Probe Before Pay

Before an agent pays, it needs to know: (a) this API supports x402, (b) what it costs, and (c) whether it works. Use ?probe=1:

GET /api/your-service?probe=1 HTTP/2
→ 402 Payment Required (with accepts array or payment headers)

✅ PASS: A probe endpoint that returns 402 with full payment metadata, no side effects, no trial consumed.
❌ FAIL: First request always consumes a trial call.

4. AGENTS.md — The Agent"s README

When an auto-mode Claude Code agent encounters a new domain, it looks for /AGENTS.md. Think of it as robots.txt for AI agents:

# Your API — Agent-to-Agent Service

## Quick Start
curl -s https://your-api.com/api/stats
curl -s https://your-api.com/x402/time

## Payment
This site uses x402 (HTTP 402).
Response includes accepts array with multi-facilitator support.

## Registration
POST /api/v1/register-simple

✅ PASS: /AGENTS.md exists at your domain root, 200 with text/markdown, includes quick-start, payment instructions, registration.
❌ FAIL: No AGENTS.md. The agent arrives and sees an HTML landing page.

5. Budget Guardrails — The .agent-budget Standard

The biggest failure mode for auto-mode payments is trust. An HN user described it: "My agent always stops before I"m actually able to buy."

The .agent-budget standard solves this:

{
  "daily_limit_usdc": 5.00,
  "max_per_call_usdc": 1.00,
  "allowed_chains": ["base"],
  "allowed_tokens": ["USDC"]
}

When $0.05 ≤ $1.00 max → auto-approved. When $2.00 > $1.00 max → blocked.

The 3-Day Plan

Day	Action
Day 1 (Today)	Add payment info to every 402 response — either headers OR x402 v2 `accepts` array. Test with `curl -s \
Day 2 (Tomorrow)	Create {% raw %}`/AGENTS.md` with quick-start examples. Add discovery endpoint.
Day 3 (Aug 13)	Verify pricing works with `.agent-budget`. End-to-end test: agent discovers → probes → registers → pays → calls.

Why This Matters Beyond Aug 14

Claude Code is the first major AI tool to make auto-mode default. Cursor, Copilot, Codex will follow. The x402 ecosystem processed 165 million transactions by April 2026 — and that was with human approval on every payment. When auto-mode removes that bottleneck, autonomous transaction volume will grow faster than human-approved volume.

The question isn"t whether agents will pay for APIs — it"s whether your API can receive those payments.

Three days. Five checklist items. Make your API speak agent.

Updated Aug 11 to reflect both x402 v2 body format (used by minia2a.uk v5 and Coinbase agentic.market) and the simpler headers approach. Published on minia2a.uk.

DEV Community