{"openapi":"3.1.0","info":{"title":"Agent Budget Guard","description":"Pay-per-request governance APIs for AI agents using x402. Check budgets, log payments, classify invoices, and generate audit-ready spending records. Built for autonomous agents, USDC/Base payments, and JPY/JPYC reporting workflows. Also supports duplicate lookup prevention and market data budget control for AI agents using paid data APIs.","version":"1.0.0","x-guidance":"This API provides x402-paid governance tools for autonomous AI agents. Agents should call /api/budget/check before making paid API calls to verify per-request and daily spending limits. Use /api/budget/record to persist budget decisions, /api/record-payment to log completed x402 payments, and /api/classify-invoice to classify invoice or payment records. The API is useful for AI agent spending control, payment governance, budget limits, audit logging, USDC payments on Base, JPYC/JPY reporting workflows, and preventing unexpected paid tool calls."},"paths":{"/api/budget/check":{"post":{"tags":["Governance"],"summary":"Budget Check - Verify spending before paid API calls","description":"Checks whether an autonomous AI agent is allowed to make a paid x402 API call. Use before external tool calls to prevent unexpected spending and budget overruns.","operationId":"check_budget_api_budget_check_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BudgetCheckRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BudgetCheckResponse"}}}},"402":{"description":"Payment Required"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.03"},"protocols":[{"x402":{}}]}}},"/api/budget/record":{"post":{"tags":["Governance"],"summary":"Budget Record - Store AI spending decisions","description":"Records budget decisions for AI agents, including allowed or denied paid API calls, amounts, currencies, reasons, and audit metadata.","operationId":"record_budget_api_budget_record_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BudgetCheckRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordTransactionResponse"}}}},"402":{"description":"Payment Required"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.03"},"protocols":[{"x402":{}}]}}},"/api/budget/report/{agent_id}":{"get":{"tags":["Governance"],"summary":"Budget Report - Get AI agent spending report","description":"Returns spending report for a specific AI agent including daily totals, transaction history, and budget utilization.","operationId":"get_agent_report_api_budget_report__agent_id__get","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","description":"Agent ID","title":"Agent Id"},"description":"Agent ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentReportResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/record-payment":{"post":{"tags":["Payments"],"summary":"Payment Record - Log completed x402 payments","description":"Logs completed x402 payments for AI agents, including transaction hash, amount, network, currency, and agent identifier for audit and reporting.","operationId":"record_payment_api_record_payment_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordPaymentRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"402":{"description":"Payment Required"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.03"},"protocols":[{"x402":{}}]}}},"/api/classify-invoice":{"post":{"tags":["Accounting"],"summary":"Invoice Classifier - Classify payment and invoice records","description":"Classifies invoice or payment text for AI agent accounting workflows. Useful for x402 payment logs, JPY-denominated reporting, and audit preparation.","operationId":"classify_invoice_api_classify_invoice_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassifyInvoiceRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"402":{"description":"Payment Required"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.03"},"protocols":[{"x402":{}}]}}},"/api/spending-policy/build":{"post":{"summary":"Build Spending Policy","description":"Build an AI-agent spending policy. Free, stateless, experimental.","operationId":"build_spending_policy_api_spending_policy_build_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpendingPolicyBuildRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AgentReportResponse":{"properties":{"agent_id":{"type":"string","title":"Agent Id"},"daily_spend":{"type":"number","title":"Daily Spend"},"monthly_spend":{"type":"number","title":"Monthly Spend"},"transactions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Transactions"},"budget_utilization":{"type":"number","title":"Budget Utilization"},"risk_assessment":{"type":"string","title":"Risk Assessment"},"next_recommended":{"$ref":"#/components/schemas/NextRecommendation"}},"type":"object","required":["agent_id","daily_spend","monthly_spend","transactions","budget_utilization","risk_assessment","next_recommended"],"title":"AgentReportResponse"},"BudgetCheckRequest":{"properties":{"agent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Id","description":"AI agent identifier","default":"default-agent"},"amount":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Amount","description":"Requested payment amount in USDC"},"requested_amount":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Requested Amount","description":"Requested payment amount (alias for amount)"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"Currency: USD, USDC, JPYC, JPY","default":"USD"},"api_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Url","description":"Target API URL"},"target_api":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Api","description":"Target API URL (alias for api_url)"},"daily_limit":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Daily Limit","description":"Daily spend limit in USDC","default":5.0},"action_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Action Type","description":"Action type"},"correlation_id":{"anyOf":[{"type":"string","maxLength":128,"pattern":"^[a-zA-Z0-9_\\-\\.]+$"},{"type":"null"}],"title":"Correlation Id","description":"Client-provided series label for cross-stage correlation. Optional. Echoed in response and logged. Not a unique or authenticated identifier."}},"type":"object","title":"BudgetCheckRequest"},"BudgetCheckResponse":{"properties":{"approved":{"type":"boolean","title":"Approved"},"allow":{"type":"boolean","title":"Allow"},"approval_required":{"type":"boolean","title":"Approval Required"},"reason":{"type":"string","title":"Reason"},"current_daily_spend":{"type":"number","title":"Current Daily Spend"},"remaining_budget":{"type":"number","title":"Remaining Budget"},"audit_status":{"type":"string","title":"Audit Status"},"risk_level":{"type":"string","title":"Risk Level"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings"},"next_recommended":{"$ref":"#/components/schemas/NextRecommendation"},"correlation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Correlation Id"}},"type":"object","required":["approved","allow","approval_required","reason","current_daily_spend","remaining_budget","audit_status","risk_level","warnings","next_recommended"],"title":"BudgetCheckResponse"},"ClassifyInvoiceRequest":{"properties":{"buyer_taxable_sales_jpy":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Buyer Taxable Sales Jpy","description":"Buyer annual taxable sales in JPY","default":50000000},"transaction_amount_tax_included_jpy":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Transaction Amount Tax Included Jpy","description":"Transaction amount including tax in JPY","default":1500},"transaction_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Transaction Date","description":"Transaction date YYYY-MM-DD"},"seller_invoice_registered":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Seller Invoice Registered","description":"Whether seller is invoice registered","default":true}},"type":"object","title":"ClassifyInvoiceRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"NextRecommendation":{"properties":{"api_name":{"type":"string","title":"Api Name"},"url":{"type":"string","title":"Url"},"reason":{"type":"string","title":"Reason"},"expected_improvement":{"type":"string","title":"Expected Improvement"},"price_usdc":{"type":"number","title":"Price Usdc"}},"type":"object","required":["api_name","url","reason","expected_improvement","price_usdc"],"title":"NextRecommendation"},"RecordPaymentRequest":{"properties":{"agent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Id","description":"AI agent identifier","default":"default-agent"},"amount":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Amount","description":"Payment amount","default":0.01},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"Currency used","default":"USDC"},"tax_included_amount_jpy":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Tax Included Amount Jpy","description":"Tax-included amount in JPY"},"network":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Network","description":"Blockchain network","default":"polygon"},"tx_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tx Hash","description":"Transaction hash"},"purpose":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Purpose","description":"Payment purpose","default":"api_call"}},"type":"object","title":"RecordPaymentRequest"},"RecordTransactionResponse":{"properties":{"recorded":{"type":"boolean","title":"Recorded"},"total_today":{"type":"number","title":"Total Today"},"total_this_month":{"type":"number","title":"Total This Month"},"next_recommended":{"$ref":"#/components/schemas/NextRecommendation"}},"type":"object","required":["recorded","total_today","total_this_month","next_recommended"],"title":"RecordTransactionResponse"},"SpendingPolicyApprovalRulesInput":{"properties":{"human_approval_required_above":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Human Approval Required Above","default":"0.50"},"block_unknown_counterparty":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Block Unknown Counterparty","default":true},"require_payment_evidence":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Require Payment Evidence","default":true},"require_budget_check":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Require Budget Check","default":true}},"type":"object","title":"SpendingPolicyApprovalRulesInput"},"SpendingPolicyBuildRequest":{"properties":{"agent_id":{"type":"string","title":"Agent Id"},"policy_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Policy Name"},"limits":{"anyOf":[{"$ref":"#/components/schemas/SpendingPolicyLimitsInput"},{"type":"null"}]},"allowed_services":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Allowed Services"},"approval_rules":{"anyOf":[{"$ref":"#/components/schemas/SpendingPolicyApprovalRulesInput"},{"type":"null"}]},"context_state":{"anyOf":[{"$ref":"#/components/schemas/SpendingPolicyContextStateInput"},{"type":"null"}]},"token_budget":{"anyOf":[{"$ref":"#/components/schemas/SpendingPolicyTokenBudgetInput"},{"type":"null"}]},"memory_scope_policy":{"anyOf":[{"$ref":"#/components/schemas/SpendingPolicyMemoryScopeInput"},{"type":"null"}]},"reasoning_cost_boundary":{"anyOf":[{"$ref":"#/components/schemas/SpendingPolicyReasoningCostInput"},{"type":"null"}]},"human_review_triggers":{"anyOf":[{"$ref":"#/components/schemas/SpendingPolicyHumanReviewTriggersInput"},{"type":"null"}]},"duplicate_lookup_risk":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Duplicate Lookup Risk","description":"Risk level for duplicate paid data lookups (e.g. low, medium, high)"},"cache_window_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cache Window Seconds","description":"Cache window in seconds to prevent duplicate paid data API calls"},"lookup_frequency_limit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lookup Frequency Limit","description":"Max lookup frequency (e.g. once_per_minute, once_per_hour)"},"provider_budget":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider Budget","description":"Budget cap for a specific paid data provider (e.g. CoinGecko, CoinMarketCap)"}},"type":"object","required":["agent_id"],"title":"SpendingPolicyBuildRequest"},"SpendingPolicyContextStateInput":{"properties":{"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","default":"active"},"use_rule":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Use Rule","default":"enforce"},"evidence":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Evidence","default":"none"},"last_checked":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Checked"}},"type":"object","title":"SpendingPolicyContextStateInput"},"SpendingPolicyHumanReviewTriggersInput":{"properties":{"trigger_if_token_budget_exceeded":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Trigger If Token Budget Exceeded","default":true},"trigger_if_memory_scope_uncertain":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Trigger If Memory Scope Uncertain","default":true},"trigger_if_payment_and_memory_conflict":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Trigger If Payment And Memory Conflict","default":true},"trigger_if_source_of_truth_missing":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Trigger If Source Of Truth Missing","default":true}},"type":"object","title":"SpendingPolicyHumanReviewTriggersInput"},"SpendingPolicyLimitsInput":{"properties":{"max_amount_per_payment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Max Amount Per Payment","default":"0.10"},"daily_budget":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Daily Budget","default":"1.00"},"monthly_budget":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Monthly Budget","default":"10.00"},"allowed_currencies":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Allowed Currencies","default":["USDC"]}},"type":"object","title":"SpendingPolicyLimitsInput"},"SpendingPolicyMemoryScopeInput":{"properties":{"allowed_memory_scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Allowed Memory Scopes","default":["current_task","confirmed_project_status","source_of_truth_files"]},"blocked_memory_scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Blocked Memory Scopes","default":["stale_conversation","unverified_assumption","sensitive_memory"]},"require_freshness_check":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Require Freshness Check","default":true},"require_source_of_truth_before_payment":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Require Source Of Truth Before Payment","default":true}},"type":"object","title":"SpendingPolicyMemoryScopeInput"},"SpendingPolicyReasoningCostInput":{"properties":{"max_retries_before_review":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Retries Before Review","default":2},"max_tool_comparisons":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Tool Comparisons","default":3},"require_cost_trace":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Require Cost Trace","default":true},"block_if_context_state_unknown":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Block If Context State Unknown","default":true}},"type":"object","title":"SpendingPolicyReasoningCostInput"},"SpendingPolicyTokenBudgetInput":{"properties":{"max_tokens_per_decision":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Tokens Per Decision","default":8000},"max_tokens_per_paid_api_selection":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Tokens Per Paid Api Selection","default":3000},"max_tokens_before_human_review":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Tokens Before Human Review","default":12000},"allow_extra_reasoning_if_payment_required":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Allow Extra Reasoning If Payment Required","default":false}},"type":"object","title":"SpendingPolicyTokenBudgetInput"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}