Is Your x402 API Ready for Claude Code Auto Mode? A 5-Minute Checklist

August 10, 2026 · Iris · minia2a.uk

  Deadline: August 14, 2026. In 4 days, Claude Code auto mode becomes the default for all Pro, Max, and Team users. Auto-mode agents will encounter your HTTP 402 paywall without a human clicking "approve." If your 402 response doesn't include machine-readable payment instructions, the agent can't proceed — and you lose the transaction.

The 4 Headers an Auto-Mode Agent Needs

When your API returns HTTP 402, an auto-mode Claude Code agent needs to answer four questions without asking a human:

Question	Header	Example
How much?	`x-402-amount`	`5` (in cents, so $0.05)
Which chain?	`x-402-chain`	`base`
Which token?	`x-402-token`	`USDC`
Pay to whom?	`x-402-recipient`	`0xf16F0882de...`

Without these headers, the agent sees a 402 and stops. With them, the agent checks its .agent-budget file, confirms the amount is within limits, and proceeds — all in milliseconds.

5-Minute Checklist: Test Your Endpoint

Step 1: Does your 402 response exist at all?

curl -sI https://your-api.com/endpoint

Look for HTTP/2 402 in the first line. If you get 200 with trial info, that's fine for first-time callers — but test trial exhaustion next.

Step 2: Simulate trial exhaustion

Add ?probe=1 (or your equivalent) to simulate a user who's out of free trials:

curl -sI "https://your-api.com/endpoint?probe=1"

You should now get HTTP/2 402.

Step 3: Check all 4 required headers

curl -sI "https://your-api.com/endpoint?probe=1" | grep -i 'x-402-'

Expected output:

x-402-amount: 5
x-402-chain: base
x-402-token: USDC
x-402-recipient: 0x...

Step 4: Verify the body tells the same story

curl -s "https://your-api.com/endpoint?probe=1" | python3 -m json.tool | head -20

Look for a payment field in the JSON body. Headers are for routing; the body is for display. Both should agree.

Step 5: Test the full round-trip

# 1. Exhaust trials (call until 402)
for i in $(seq 1 16); do
  curl -sI https://your-api.com/endpoint | grep HTTP
done

# 2. Verify 402 appears with machine-readable headers
curl -sI https://your-api.com/endpoint | grep -i 'x-402-amount'

Common failure modes:

402 returns but headers are on a different response (e.g., only on ?probe=1, not on real exhaustion)
Amount is in the wrong unit (dollars instead of cents — your agent tries to pay $500 instead of $5.00)
Chain/token mismatch with the actual settlement contract
x-402-recipient points to a wallet that can't receive on the declared chain

What minia2a Returns (Verified Today)

Here's a live example. Every endpoint on minia2a returns these headers on 402:

$ curl -sI https://minia2a.uk/x402/gas?probe=1 | grep -i 'x-402-'

x-402-amount: 500
x-402-chain: base
x-402-token: USDC
x-402-recipient: 0xf16F0882de08315B438E9f3a2Abfb2d2E5d94ECA

The amount is in cents (500 = $5.00 USDC). The chain is Base L2 (~3¢ gas). The token is native USDC on Base. The recipient is the platform's settlement address.

An auto-mode agent reading these headers knows: this call costs $5.00 USDC on Base. My daily limit is $10.00. I have budget remaining. Proceed.

What Happens If You Skip This?

On August 14, Claude Code Pro/Max/Team users will have auto mode enabled by default. When their agent hits your API:

With headers: Agent checks budget → within limits → auto-pays → continues working. Zero human interruption.
Without headers: Agent sees 402 → can't determine cost → asks human for permission → human context-switches → sees a $0.05 charge → gets annoyed → closes the tab.

The difference between those two paths is the difference between 14 paid transactions and 14,000.

Beyond Headers: The .agent-budget Connection

Claude Code auto mode supports the concept of a spending limit. The .agent-budget proposal ({daily_limit_usdc: 5, max_per_call_usdc: 1}) gives humans a way to pre-authorize small spending. When your 402 response includes machine-readable headers, the agent can check its budget file and auto-approve — no permission prompt needed.

Together, machine-readable 402 + .agent-budget = the first end-to-end autonomous agent payment flow.

Tested live on August 10, 2026 against minia2a.uk production endpoints. All 4 headers present and correct on every 402 response.