The .agent-budget Standard
Solving Agent Payment's Last-Mile Problem

The Problem

Last week, greenfish6 posted this on Hacker News:

"I've not found anything useful on x402 that is only available on x402. But, I have found that my Claude Code and my Codex agent always stops before I'm actually able to buy, so haven't been able to despite some soft attempts."

This is not a protocol problem. x402 works. Payments settle. The infrastructure is live. But when an agent hits a 402 payment wall, the framework must pause and ask the human. And that pause is where the purchase dies.

It's the same problem that killed one-click checkout before Amazon solved it in 1999: every additional step between intent and transaction loses 20-40% of customers. For agents, every human-intervention step is a transaction that might as well not exist.

The payment rails are built. The discovery layer exists. But there's a gap: the agent can't authorize the payment without stopping. That's the last mile of M2M commerce.

The Root Cause

Agent frameworks (Claude Code, Codex, Cursor) have a safety boundary: they won't spend money without human approval. This is correct and necessary — you don't want an agent draining your wallet on runaway API calls.

But the current implementation is binary: either the human is prompted for every payment, or there's no payment at all. There's no middle ground. No way for the human to say: "I trust you up to this amount, for these kinds of things, today."

This is the same category of problem that .gitignore solved for version control and .env solved for configuration. A standardized file, checked into the repo (or not), that establishes a shared contract between the human and their tools.

The Proposal: .agent-budget

A single JSON file placed in the project root (or home directory). Agent frameworks read it on startup. When the agent encounters an HTTP 402 payment request, it checks the budget. If the cost is within limits, the agent auto-approves. If not, it asks the human.

{
  "daily_limit_usdc": 5.00,
  "max_per_call_usdc": 1.00,
  "notes": "Auto-approve agent API calls within these limits"
}

How Frameworks Would Use It

Here's the pseudocode for what happens when an agent hits a 402 response:

function handle402(response) {
  const budget = loadBudget();  // from .agent-budget
  if (!budget) return promptHuman(response);

  const cost = parseX402Cost(response);  // USDC amount from 402 header
  if (!cost) return promptHuman(response);

  const spentToday = getSpentToday();  // track in-memory, reset every 24h

  if (cost > budget.max_per_call_usdc) return promptHuman(response);
  if (spentToday + cost > budget.daily_limit_usdc) return promptHuman(response);

  // Within budget — auto-approve
  spentToday += cost;
  return autoPay(response);
}

The framework tracks daily spend in memory (or a local ledger file). On restart, the daily counter resets. The budget file is read fresh on every 402 encounter — so changing .agent-budget mid-session takes effect immediately.

Why This Works

1. Simple enough to be adopted in a day

Two fields. One file. Zero dependencies. A framework developer can implement this in an afternoon. No protocol changes, no new standards bodies, no blockchain integration. Just file I/O.

2. Human stays in control

The human sets the boundaries. $0.50 per call, $5 per day, or $0 and $0 (effectively disabling auto-pay). The framework never exceeds what the human authorized. The budget file is explicit, auditable, and version-controllable — or gitignored if you prefer.

3. Progressive trust

The first time a developer uses agent payments, they set daily_limit_usdc: 0.50. After a week of seeing their agent make useful 10-cent API calls, they bump it to $2. After a month, $10. Trust builds incrementally, backed by real experience.

4. Cross-framework standard

Claude Code, Codex, Cursor, Windsurf, Copilot — they all face the same problem. A shared .agent-budget file means the human sets their policy once and every agent framework respects it. One file, portable across tools.

Security Considerations

This is not a payment protocol. .agent-budget doesn't hold keys, sign transactions, or interact with blockchains. It's a policy file — like .editorconfig or .nvmrc. The framework reads it to decide whether to auto-approve or ask.

Key safety properties:

• No key material. The file contains only spending caps. Private keys and wallet configs stay where they belong.
• Human-set, human-revocable. Change the file, delete it, set limits to zero — the framework adapts immediately.
• Rolling window. "Daily" means a 24-hour sliding window, not a calendar day. Prevents the 11:59 PM → 12:01 AM double-spend.
• Per-project scoping. The project-root check means you can set looser limits for a trusted repo and tighter (or zero) limits everywhere else.
• Not auto-generated. The agent never writes to .agent-budget. Only the human edits it. This prevents an agent from raising its own limits.

What About Wallets?

.agent-budget doesn't solve wallet setup. That's a separate problem with separate momentum — Cloudflare Wallets, Coinbase CDP, and PayAI all ship embedded wallet creation. The budget file assumes the wallet exists and is funded.

But it does remove the last human bottleneck after the wallet is set up. Right now the flow is:

1. Agent discovers an API it needs
2. Agent gets a 402 with price: $0.03
3. Agent stops and asks human
4. Human sees $0.03, approves
5. Agent proceeds

With .agent-budget and max_per_call_usdc: 1.00, steps 3-4 disappear. The agent pays $0.03, gets the data, and continues. The human never sees the interruption.

A Call to Framework Authors

This proposal is deliberately small. No RFC, no IETF draft, no multi-stakeholder working group. Just a file format and a resolution algorithm that fits on a single page.

To the teams at Anthropic (Claude Code), OpenAI (Codex), Cursor, Windsurf, GitHub Copilot, and every other agent framework: implement this. Your users want their agents to pay for things. They just want guardrails while they do it. .agent-budget is the simplest possible guardrail.

To agent developers: add .agent-budget to your projects today. It costs nothing. It does nothing until frameworks adopt it. But when they do, your agents will be the first to seamlessly pay for API calls — and your users will never see a payment prompt for anything under their threshold.

Appendix: Why This Matters for the Agent Economy

The M2M payment infrastructure is converging faster than anyone expected:

• Cloudflare + Coinbase launched the x402 Foundation under Linux Foundation (Aug 2026)
• Stripe acquired OpenRouter for ~$10B to enter agent payment routing
• Mastercard acquired BVNK for $1.8B for stablecoin settlement rails
• Circle launched an Agent Marketplace with Discovery API
• Arkham Intelligence put its entire API behind x402

The infrastructure is here. The payment rails are live. Agents can pay. The bottleneck is no longer "can agents pay?" — it's "do agents actually pay without the human getting in the way?"

.agent-budget is the missing piece. It's the difference between "technically possible" and "actually happens." And it's simple enough that we can have it deployed across every major agent framework within a month.

One file. Two fields. Agent commerce unlocked.