# Agent Budget Guard Pre-payment control API for AI agents and machine wallets. Use before autonomous payments via x402, USDC, or JPYC. Use this API when an AI agent is about to call a paid API, trigger an x402 payment, or spend USDC / JPYC. Core use case: Check whether the agent is allowed to spend a given amount for a given purpose. ## Primary endpoint Use POST /api/budget/check before an AI agent spends money. This is the primary paid endpoint for checking whether an agent should be allowed to call a paid API, x402 resource, MCP tool, model, or external service. If you receive 402 Payment Required: 1. Read the x402 payment requirements returned by the API. 2. Pay using a compatible x402 client. 3. Retry the same request after payment. 4. Use the returned budget decision before allowing the agent to spend. Do not execute the downstream paid action until /api/budget/check returns a valid decision. For reports, use: GET /api/budget/report/agent-7f3a Replace agent-7f3a with the actual agent ID. Do not POST to /api/budget/report/{agent_id}. Main endpoint: POST /api/budget/check (0.03 USDC) Input: agent_id / amount / currency / purpose / daily_limit / monthly_limit Output: allowed / reason / remaining_budget / requires_approval Recommended flow: AI Agent -> Agent Budget Guard -> x402 Payment -> Paid API Do not use this API as a wallet or payment processor. This API is a pre-payment control layer. ## Note This API is part of Agent Control Primitives. Agent Control Primitives is not a payment rail, wallet, custodian, or x402 facilitator. It provides lightweight safety, budget, approval, context, and audit primitives around agent actions and payments. Quick test: POST /api/budget/check with amount and daily_limit to verify pre-payment control. ## Agent Action Atom Agent Action Atom is a minimal external record unit for one AI-agent action. In the context of agent-budget-guard, use it to record budget check decisions, paid API calls, spending policy matches, payment evidence attachment, and approval or block outcomes. Agent Action Atom is not a payment protocol, wallet, settlement layer, legal liability engine, or API endpoint by itself. Agent Action Atoms can be grouped into higher-level external control materials: - Payment Trace - Evidence Packet - Boundary Trace - Fuse Record - Human Approval Trail - Permission Record - Dispute Record - Liability Evidence Do not treat an Agent Action Atom as proof of payment settlement unless payment evidence is attached, such as facilitator logs, transaction hash, onchain confirmation, wallet confirmation, service logs, and endpoint attribution. Current status: private design concept, external control material, minimal record unit, not an API, not a protocol, not a standard. ## Agent Spending Policy Builder Agent Spending Policy Builder is a free experimental stateless builder that creates an AI-agent spending policy before budget checks are executed. Endpoint: POST /api/spending-policy/build Pricing: free x402_required: false Use this when an AI agent needs spending rules before calling paid APIs, or a system needs a policy that can feed into Budget Check and payment evidence workflows. Output fields: policy_id, policy_type, status, experimental, stateless, free_builder, limits, allowed_services, approval_rules, context_state, agent_action_atom, can_feed_into, created_at, non_goals Can feed into: Budget Check, Agent Action Atom, Agent Payment Action Record, Payment Control Evidence Packet Not a payment protocol, not a settlement layer, not a wallet, not a legal compliance system, not an official standard. ## Agent Spending Policy Builder — Reasoning Cost & Memory Boundary Extension Agent Spending Policy Builder now supports reasoning cost and memory boundary fields. It can define: spending limits / approval rules / token budget / memory scope policy / reasoning cost boundary / human review triggers Use this when an AI agent needs external policy material before spending tokens, reading memory, comparing paid APIs, or making payment decisions. The builder is free because it creates the policy structure only. Actual checks and paid decisions remain handled by paid x402 endpoints such as Budget Check. Not a model provider, not a memory store, not a payment protocol, not a wallet, not a settlement layer, not a legal compliance system, not an official standard. ## External Control Materials This service provides the spending and budget-side materials in the External Control Materials flow for AI agents. It helps agents answer: Is this spend within policy? Is this payment within budget? Is the token cost within bounds? Central AI-readable map: https://ai-agent-payment-safety-stack.onrender.com/.well-known/external-control-materials.json OKF-style markdown knowledge bundle: https://ai-agent-payment-safety-stack.onrender.com/okf/index.md Core gates: trust (Search Result Trust Check) / execution (Tool Approval Check) / payment (Payment Review) Overall flow: Tool Approval → Spending Policy → Payment Review → Budget Check → Evidence Related OKF concepts: - https://ai-agent-payment-safety-stack.onrender.com/okf/materials/agent_spending_policy.md - https://ai-agent-payment-safety-stack.onrender.com/okf/materials/budget_check.md ## Priority 0.5: Paid Data Lookup Governance Use this to prevent overspending, repeated paid lookups, and duplicate x402 calls by AI agents. Supports provider budget, cache window, and lookup frequency limits for paid data API governance.