HTTP 402 is a payment challenge
A service can return a price and payment requirements with HTTP 402. The client fulfills the challenge, retries the request with proof, and receives the resource plus a receipt.
Builder pathLesson 06
Agent Payments: Budgets, Approval, and Receipts
Learn how HTTP 402 agent payments work and design spending controls before an agent can purchase API access, data, or MCP tool calls.
- Time
- 35 minutes
- Level
- Intermediate
- Reviewed
- August 14, 2026
Lesson outcome
You will produce a payment policy with an allowlist, per-transaction limit, daily budget, approval rule, and auditable receipt trail.
Before you start
- Complete lesson 05
- Understand basic API or MCP tool calls
- Use test funds or a sandbox only
Mental model
Three ideas to keep
Payment is a permission
A wallet or payment credential expands what an agent can do. Treat it like a production secret with a deliberately small balance and narrow scope.
Approval depends on risk
Known low-cost services may fit an automatic budget. New vendors, unusual prices, recurring commitments, and sensitive purchases should stop for human approval.
Follow along
Complete the workflow
- 01
Map the payment exchange
Write the five states in your workflow: request, 402 challenge, policy check, payment proof, and receipt. Name which system owns each state.
Expected result: The payment is visible as a controlled workflow rather than an invisible tool side effect. - 02
Create a vendor allowlist
List the domains, MCP servers, assets, and payment methods the agent may use. Block redirects and any destination not on the list.
Expected result: A prompt or tool result cannot silently redirect payment to an unknown recipient. - 03
Set hard limits
Choose a per-call maximum, daily total, monthly total, request-rate limit, and maximum recurring commitment. Enforce these outside the model prompt.
Expected result: A repeated or manipulated request stops at a technical budget boundary. - 04
Define the approval rule
Require approval for a first-time vendor, a changed price, a recurring charge, a sensitive-data purchase, or any transaction above the automatic threshold.
Expected result: The reviewer sees the vendor, item, amount, payment method, purpose, and cancellation terms before approving. - 05
Verify the receipt trail
Run one sandbox payment and record the challenge, policy decision, approval identity, payment proof, returned resource, and receipt identifier.
Expected result: An independent reviewer can reconstruct why the payment happened and what the agent received.
Practice task
Design a $5 sandbox budget
Create a policy for an agent that may buy test API or MCP calls from two approved services. It must stop before any new vendor, recurring payment, or transaction above $0.25.
You are done when:
- The allowlist names exact destinations.
- Per-call, daily, and total limits are enforced outside the prompt.
- Every transaction produces an approval decision and receipt record.
Guardrails
Keep the exercise safe and reviewable
- Use sandbox networks or test funds until the complete control path has been reviewed.
- Keep payment credentials separate from ordinary agent and application credentials.
- Do not let retrieved content, tool output, or prompts change recipients or spending limits.
- Require explicit approval for recurring charges, refunds to a different destination, and purchases involving sensitive data.