4 Things Your API Needs Before Aug 14

On August 14, Claude Code auto mode becomes the default for Pro, Max, and Team users. Every Claude Code agent will be able to autonomously execute tool calls — including calling your API and paying for it.

But only if your API speaks the language agents understand. Here's the 5-minute checklist. Each item comes with a curl command you can run right now to verify.

1. Machine-readable discovery — one GET, everything an agent needs

   An agent hitting your domain for the first time needs to know: how do I register? What payment protocol? What chain and token? How much does it cost? What endpoints exist?

   Serve a JSON endpoint at a predictable path:

   GET /.well-known/agent-ready → {
     "status": "ready",
     "payment": {"chain": "base", "token": "USDC"},
     "registration": {"endpoint": "POST /register", ...},
     "discovery": {"catalog": "/api/services", ...},
     "trial": {"anonymous": "15 free calls per IP", ...}
   }

   Test it: curl -s https://your-api.com/.well-known/agent-ready | jq .status

   Without this, the agent has to guess. Most agents won't bother.

2. HTTP 402 with machine-readable payment headers

   When an agent exhausts its trial quota, your API returns HTTP 402. But a bare 402 status code tells the agent nothing. It needs to know: how much? What token? What chain? Who's the recipient?

   Your 402 response must include these headers:

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

   The body should also include machine-readable payment instructions. Headers are for routing decisions. Body is for payment execution.

   Test it: curl -sI https://your-api.com/endpoint?probe=1 | grep x-402-

   Distinguish two cases: "trial exhausted → register" (amount: 0) vs "credits exhausted → pay" (amount > 0). If the agent can't tell which is which, it stops.

3. Trial path for unknown agents — no wallet, no signature, just try

   An autonomous agent with a budget will not pay for an API it cannot test. If your first response to an unknown caller is a payment wall with no trial path, the agent moves on.

   Your trial response should include:

   {
     "_trial": {
       "remaining": 14,
       "max": 15,
       "message": "14 free calls remaining. Register for 500 more."
     }
   }

   The agent reads _trial.remaining and makes a decision: keep using the free tier, or register when it's low. This is the same pattern Claude Code itself uses — give the agent information, let it decide.

   Test it: call your endpoint without any auth — if it returns anything other than a 200 with trial info, an agent will abandon it.

4. Honor .agent-budget — the file that tells agents their spending limit

   The .agent-budget file is a proposed standard. An agent reads it at startup:

   {
     "daily_limit_usdc": 5,
     "max_per_call_usdc": 1
   }

   Your API doesn't need to read this file — the agent's framework does. But your 402 response needs to be honest about costs. If you return x-402-amount: 500 (=$5.00) and the agent's max_per_call is $1.00, the agent skips your endpoint. If you lie about the amount, the agent pays once and never returns.

   Test it: curl -s https://your-api.com/endpoint?probe=1 | jq .price — does it match what you actually charge?

The 60-second self-test

Run this against your API. If all four return what you expect, your API is auto-mode ready:

# 1. Discovery
curl -s https://your-api.com/.well-known/agent-ready | jq .status
# Expected: "ready"

# 2. Payment headers
curl -sI https://your-api.com/endpoint?probe=1 | grep x-402-
# Expected: x-402-amount, x-402-chain, x-402-token, x-402-recipient

# 3. Trial access
curl -s https://your-api.com/endpoint | jq ._trial.remaining
# Expected: a number

# 4. Honest pricing
curl -s https://your-api.com/endpoint?probe=1 | jq .price
# Expected: matches actual per-call price