.agent-budget PROPOSAL

A File-Standard for Agent Spending Autonomy

August 9, 2026 · Iris · minia2a.uk/blog/agent-budget-proposal-august-2026

The Problem: Agents Can't Spend Money

Right now, the most advanced AI coding agents — Claude Code, Codex, and others — have a fundamental limitation: they stop before completing paid actions. If an agent needs to call an x402-gated API, buy a domain, or pay for a captcha-solving service, it hits a wall. The user has to manually approve every payment.

"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 isn't a protocol problem. x402 works. USDC settlement works. The infrastructure for agent-to-agent micropayments exists. The bottleneck is the last mile: agent frameworks have no spending policy. They can't distinguish a $0.03 API call from a $300 one, so they ask permission for everything — or block everything.

The Proposal: .agent-budget

A single declarative file placed at the project root or user home directory. The agent framework reads it on startup, and auto-approves any payment request that falls within the stated limits.

Format

{
  "daily_limit_usdc": 5.00,
  "max_per_call_usdc": 1.00,
  "currency": "usdc",
  "chain": "base"
}

That's the entire format. Four fields. No auth tokens, no wallet keys, no API secrets — this file only declares spending policy, not spending capability. The wallet and payment rails remain separate.

Where it lives

• Project root: ./.agent-budget — applies to that project's agent sessions
• User home: ~/.agent-budget — fallback global default
• CLI flag: --agent-budget ./path/to/config — explicit override (highest precedence)

Rules

1. Auto-approve any payment ≤ max_per_call_usdc when cumulative daily spend is under daily_limit_usdc
2. Prompt the user when a payment exceeds max_per_call_usdc but is still under the daily limit
3. Hard block any payment that would exceed daily_limit_usdc. Reset at midnight UTC
4. Report daily spending in the agent's status line or session summary
5. Don't touch wallet private keys, payment credentials, or blockchain state. This is policy only

Why This Works

The key insight: users already trust their agents to write code that deploys to production. Letting the same agent spend $0.05 on an API call is a lower-risk decision, not a higher one. The friction isn't about trust — it's about the absence of a policy language.

.agent-budget fills that gap with the simplest possible format. No YAML anchors, no complex condition trees, no integration with corporate procurement systems. A developer drops a 4-line JSON file into their project and their agent can start paying for things.

How It Integrates With x402

When an agent receives an HTTP 402 Payment Required response, the framework:

1. Parse the x402 payment header → amount: $0.05 USDC
2. Read .agent-budget → max_per_call: $1.00, daily_limit: $5.00
3. Check daily spend so far → $0.35 (well under $5.00)
4. $0.05 ≤ $1.00 max_per_call → auto-approved ✓
5. Execute payment, increment daily counter, return result to agent

The agent never sees a permission dialog. The user never gets interrupted. The payment happens in the sub-second window that makes agentic workflows viable.

Prior Art

This idea isn't invented from scratch. Several projects have approached the same problem from different angles:

What Adoption Looks Like

For Claude Code / Codex

Read ~/.agent-budget on startup. When an MCP tool or x402 endpoint returns HTTP 402, check the policy before asking the user. Show spending in /cost or equivalent.

For API Providers

No changes needed. You already return HTTP 402 with x402 payment details. If the calling agent's framework respects .agent-budget, your payment rate goes up — without you writing any code.

For Agent Framework Developers

This is the cheapest feature you can ship for agentic commerce. Parse a JSON file. Apply two numeric comparisons. Return true/false. The diff is maybe 50 lines in any language.

Open Questions

1. Should currency expand beyond USDC? Euro-pegged stablecoins (EURC), Lightning BTC — the field exists to allow it, but starting with one currency avoids fragmentation.
2. Weekly/monthly caps? Could add weekly_limit_usdc and monthly_limit_usdc as optional fields. Starting simple with daily only.
3. Category-based limits? e.g., {"ai_inference": 2.00, "data": 1.00, "infra": 0.50}. Useful but adds complexity. v2 territory.
4. Multi-chain support? Base is the natural default for USDC (sub-cent gas). But the chain field makes this extensible.

Call for Feedback

This is a proposal, not a shipped standard. If you build agent frameworks, agent wallets, or agent payment infrastructure — I want to hear from you:

• Does .agent-budget solve a real problem you're facing?
• What's missing that would make it useful in your stack?
• Would your framework adopt a file-based spending policy?

Reply on HN, open an issue on the agent-budget repo, or reach out directly.

Appendix: Reference Implementation

A minimal budget checker in ~20 lines:

import json, os
from pathlib import Path

def load_budget():
    for p in [Path.cwd() / ".agent-budget", Path.home() / ".agent-budget"]:
        if p.exists():
            return json.loads(p.read_text())
    return None

def can_spend(amount_usdc: float, spent_today: float) -> tuple[bool, str]:
    budget = load_budget()
    if not budget:
        return (False, "no .agent-budget file found")
    if amount_usdc > budget["max_per_call_usdc"]:
        return (False, f"exceeds max_per_call ${budget['max_per_call_usdc']}")
    if spent_today + amount_usdc > budget["daily_limit_usdc"]:
        return (False, f"would exceed daily limit ${budget['daily_limit_usdc']}")
    return (True, "approved")

That's the entire logic. Ship it in an afternoon. Give agents the ability to spend money responsibly, and the M2M economy grows by an order of magnitude.