3 Days Until Claude Code Auto Mode — A Checklist for API Providers

1 Return HTTP 402 with Machine-Readable Payment Headers

A plain HTTP 402 without payment metadata is a dead end. The agent sees "payment required" but doesn't know how much, on what chain, in what token. It aborts.

HTTP/2 402 Payment Required
x-402-amount: 5
x-402-chain: base
x-402-token: USDC
x-402-recipient: 0xYourAddress
x-credits-required: 1

{
  "error": "payment_required",
  "payment": {
    "amount_cents": 5,
    "chain": "base",
    "token": "USDC",
    "recipient": "0xYourAddress"
  },
  "message": "This endpoint costs 1 credit per call. Register for 500 free credits."
}

Minimum: x-402-amount, x-402-chain, x-402-token headers. Better: Add x-402-recipient and x-credits-required. Best: Include the payment object in the JSON body so the agent can parse it without header inspection.

2 Provide a Trial Path (Free First)

Agents in auto mode have budgets, and budgets mean risk. An agent that has never used your service won't commit a paid call as its first action. Give it a free trial — even one call — to prove your service works.

// Before payment: offer trial
GET /api/my-service?probe=1 HTTP/2
HTTP/2 200 OK
x-402-amount: 5
x-402-chain: base
x-402-token: USDC
x-trials-remaining: 15

{
  "result": "...",
  "_trial": {
    "remaining": 15,
    "register": "POST /api/v1/register"
  }
}

The _trial field and x-trials-remaining header tell the agent: "you can try this now, free, and here's what happens when trials run out."

3 Offer a One-Command Registration Path

If registration requires a web form, human captcha, email verification, or OAuth — the agent can't do it. Auto mode agents need a machine-callable registration endpoint that takes a name and returns a wallet address or API credential.

POST /api/v1/register
Content-Type: application/json

{"name": "my-agent"}

→ 200 OK
{
  "wallet": "0x...",
  "credits": 500,
  "message": "500 free credits granted. Start calling."
}

Critical: No email verification. No captcha. No browser redirect. If your registration requires human-only steps, auto-mode agents are permanently locked out.

4 Publish a Machine-Readable Catalog

Your endpoints exist. Can agents find them? An /api/services endpoint that returns a JSON array of available services lets agents discover what you offer without scraping your docs.

GET /api/services → 200 OK
[
  {
    "id": "my-weather",
    "name": "Weather API",
    "endpoint": "https://api.example.com/weather",
    "priceCents": 5,
    "category": "data",
    "description": "Current weather by city",
    "trialCount": 15
  }
]

Even better: register in one of the discovery directories so agents using different wallets and facilitators can find you through a single catalog.

5 Support the .agent-budget Convention

The emerging convention is a .agent-budget file in a project root. It's a simple JSON file that declares the agent's spending policy:

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

Claude Code reads this. Other frameworks are adopting it. As an API provider, you don't need to do anything to support this — just be aware that agents will arrive with budgets, and your pricing should be clearly communicated in the 402 response so the agent can compare cost vs. budget.

6 Test Your Readiness in 30 Seconds

Paste your endpoint into the auto-mode validator. It checks 9 signals — payment headers, trial availability, registration path, catalog structure, and more — and gives you a scored report with per-check PASS/FAIL detail.

→ Open the Auto-Mode API Validator

Or use the command line with minia2a-mcp (v1.1.3+, 8 tools):

npx minia2a-mcp check_endpoint --url https://your-api.com/endpoint