.agent-budget v1.0.0-draft

An open standard for agent payment authorization. Protocol-agnostic. Opt-in. 30 lines of code.

Status: Draft proposal. Seeking feedback from agent framework developers (Claude Code, Codex, and others). Read the proposal blog post →

1. Purpose

Agent frameworks (Claude Code, Codex, etc.) cannot auto-approve payments because they don't know the user's spending limits. This causes unnecessary interruptions — the agent stops and asks for every $0.01 API call, defeating the purpose of autonomous agents.

.agent-budget solves this by declaring, in a single file, what the user has pre-authorized their agent to spend. Frameworks read it, enforce the limits, and only interrupt when a payment would exceed the budget.

2. File Format

{
  "daily_limit_usdc": 5.00,
  "max_per_call_usdc": 1.00,
  "weekly_limit_usdc": 25.00
}

2.1 Fields

FieldRequiredTypeDescription
daily_limit_usdc ✅ Required number Maximum cumulative spend per UTC calendar day. Resets at 00:00 UTC.
0 = "ask me every time" (budget-aware prompts).
-1 = no daily limit (use with caution).
max_per_call_usdc ✅ Required number Maximum spend for any single API call. Prevents a large transaction from consuming the daily budget in one go.
0 = "ask for every call regardless of daily limit."
weekly_limit_usdc 🔷 Optional number Soft cap over a rolling 7-day window. Exceeding this triggers a warning (not a block). Useful as a safety net above daily limits.

2.2 File Locations (checked in order, first found wins)

  1. ./.agent-budget — project-level budget (highest priority)
  2. ~/.config/agent-budget.json — user-level default

If no file is found, the framework MUST NOT auto-approve any payment. The absence of a budget file = explicit user intent to review every transaction.

3. Framework Behavior

3.1 Payment Approval Algorithm

function shouldAutoApprove(amountUSDC) {
  const budget = loadBudget();  // Read .agent-budget, then ~/.config/agent-budget.json
  if (!budget) return false;     // No budget file → ask human

  if (amountUSDC > budget.max_per_call_usdc) return false;

  const spentToday = getSpentToday();
  if (spentToday + amountUSDC > budget.daily_limit_usdc) return false;

  return true;
}

3.2 Spending Tracking

Frameworks SHOULD track daily spend in a machine-readable log. Recommended location: .agent-spending.log (project) or ~/.config/agent-spending.jsonl (global).

Recommended log format (JSON Lines):

{"time":"2026-08-09T14:22:00Z","amount":0.01,"service":"x402-gas","currency":"USDC","receipt":"0xabc123..."}
{"time":"2026-08-09T14:23:00Z","amount":0.02,"service":"x402-ens-resolve","currency":"USDC","receipt":"0xdef456..."}

4. User Experience

Before .agent-budget

Agent: "I found a gas price API. It costs $0.01. Proceed? [y/n]"
User: "y"
Agent: "I need ENS resolution. It costs $0.02. Proceed? [y/n]"
User: "y"
Agent: "I need Polymarket data. It costs $0.05. Proceed? [y/n]"
User: "sigh... y"
# 15 more interruptions...

After .agent-budget

Agent: "I'll use paid APIs when needed within our $5/day budget.
Today: $0.03 (gas $0.01, ENS $0.02). Continuing."
# Zero interruptions. Agent works autonomously within explicit guardrails.

5. Security Properties

  1. Opt-in by design: No budget file = no auto-spending. Users can't accidentally authorize payments.
  2. Per-call guard: max_per_call_usdc prevents a $50 charge in a $5/day budget.
  3. Daily reset: Limits reset at midnight UTC. A bad day doesn't cascade.
  4. Auditable: Spending log provides full transparency. Users can audit what their agent bought.
  5. Composable: Works with existing permission systems (CC's allow/deny, Codex's prompts). .agent-budget just tells them "if within budget, don't bother."

6. Implementations

None yet — this is a draft proposal. If you implement .agent-budget in your framework, open a PR to add it here.

7. FAQ

Does this require a specific payment protocol?
No. .agent-budget is payment-protocol-agnostic. It works with x402, Lightning, Stripe agent payments, Cloudflare Wallets — anything that presents a payment request to an agent.
How is this different from setting a credit card limit?
Credit card limits are enforced by the payment network, not the agent framework. .agent-budget is enforced by the framework before it initiates a payment. This means the agent can reason about budget ("I have $4.97 left today, should I spend $0.01 on gas or save it?") without needing access to the payment rail's balance API.
What about multiple agents?
Multiple agents in the same project share one budget. If you need per-agent budgets, create separate project directories with separate .agent-budget files. This is intentional simplicity — per-agent accounting would require identity, wallets, and infrastructure that defeats the purpose of a simple file-based standard.
Can the agent modify the budget file?
Frameworks SHOULD NOT allow agents to modify .agent-budget. The file is owned by the human user. Agents read it; they don't write to it.

8. Adoption

If you build an agent framework, implement .agent-budget. It's ~30 lines of code. It's backwards-compatible. It unlocks agent commerce without touching payment protocols.

If you're an agent developer, create a .agent-budget file in your project and ask your framework to support it. Adoption starts with users asking for it.

Proposed by minia2a.uk, an open trial-first marketplace for agent APIs. Discuss on HN.