{"uid":"cap_Ba0nmc8jZjI4-kl_JRAga","slug":"agentpay-gateway-budget-capped-x402-spending-session-44595350","name":"AgentPay Gateway — Budget-Capped x402 Spending Session","description":"A stateful, multi-chain spending session for AI agents. One session enforces a hard USDC budget cap across every tool call, with a verifiable receipt and running ledger for each payment — not a one-shot budget check, but persistent spend governance with a full audit trail. USDC on Base (standard x402) or Stellar (via the AgentPay SDK).","url":"https://agentpay.tools/v1/session/create","method":"POST","headers":{},"bodySchema":{"type":"object","properties":{"label":{"type":"string","description":"Optional human-readable session label"},"max_spend":{"type":"string","description":"Hard budget cap in USDC, e.g. '0.10'"},"agent_address":{"type":"string","description":"Paying agent's EVM wallet address"}}},"responseSchema":{"receipt":{"network":"base","tx_hash":"0x...","amount_usdc":"0.01"},"max_spend":"0.10","created_at":"2026-05-27T00:00:00Z","session_id":"uuid","gateway_url":"https://agentpay.tools","agent_address":"G...","tools_endpoint":"https://agentpay.tools/tools"},"example":{"request":{"label":"QA Test Session","max_spend":"0.10","agent_address":"0x742d35Cc6634C0532925a3b844Bc9e7595f42bE5"},"response":{"label":"QA Test Session","receipt":{"network":"eip155:8453","tx_hash":"0xff73178cfe8c285859ca218e7f026be5149ec01060aeb20c3097e7115b5ede04","amount_usdc":"0.01"},"sdk_hint":"Use `from agentpay import Session` to enforce the max_spend cap client-side.","max_spend":"0.10","created_at":"2026-06-12T05:06:36Z","session_id":"abef2072-64f9-4935-b246-d96f60ad58f5","gateway_url":"https://agentpay.tools","agent_address":"0x742d35Cc6634C0532925a3b844Bc9e7595f42bE5","tools_endpoint":"https://agentpay.tools/tools"}},"exampleRequest":{"label":"QA Test Session","max_spend":"0.10","agent_address":"0x742d35Cc6634C0532925a3b844Bc9e7595f42bE5"},"tags":["x402"],"displayCostAmount":"0.01","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"settled","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.01/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_TzwS9O_H0LYTuZxcl_i1o","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.01","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Creates a budget-capped USDC spending session for an AI agent, returning a session ID, verifiable on-chain receipt, and gateway URL for subsequent tool calls.","exampleAgentPrompt":"Start a budget-capped AgentPay spending session for my agent wallet 0xABC123...def with a hard cap of 0.10 USDC and label it 'research-run-1', then give me the session ID and receipt.","exampleUseCases":[{"title":"Autonomous research agent spending cap","prompt":"Open a new AgentPay session for my agent wallet 0x123...abc with a hard cap of 0.50 USDC so it can call paid research APIs overnight without any risk of cost overruns — give me the session ID and on-chain receipt when it's ready."},{"title":"Batch tool calls under budget","prompt":"Set up a budget-capped AgentPay session for wallet 0xDEF...456 with a 0.25 USDC limit and label it 'data-pipeline-run', then return the session token and gateway URL so my agent can start making paid tool calls within that budget."},{"title":"Verifiable on-chain agent payment","prompt":"Create an AgentPay spending session on Base for my agent wallet 0x789...GHI, cap it at 0.10 USDC, and send me the transaction hash and confirmed receipt so I can audit exactly what was charged before the agent runs its next autonomous workflow."}],"resultDescription":"Returns a JSON object containing a unique session_id (UUID), the hard budget max_spend in USDC, the gateway_url and tools_endpoint for subsequent calls, a created_at ISO timestamp, and a receipt object with the Base network identifier, the on-chain transaction hash, and the confirmed USDC amount charged to open the session.","failureModes":["Insufficient USDC balance in agent wallet — payment cannot be processed","Invalid or malformed EVM agent_address — returns 400 bad request","max_spend value is not a valid decimal string — returns validation error","x402 payment header missing or rejected — returns 402 Payment Required","Network congestion on Base causing transaction confirmation delay","Session creation idempotency not guaranteed — duplicate calls create duplicate sessions and charges"],"whenToPreferThis":"Choose this endpoint when an AI agent needs a hard budget cap enforced at the protocol level before making multiple downstream paid API calls — especially in autonomous or unattended workflows where cost overruns are a risk. Prefer this over ad-hoc per-call x402 payments when you need a verifiable on-chain receipt and a single session token to govern a batch of tool calls. Best suited for Base (EVM) wallets paying in USDC.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-14T18:40:00.853Z","isFirstParty":false}