Design an Agent Payment Gateway — the walkthrough in full
A written version of the interactive walkthrough above — the same steps, decisions and trade-offs, laid out for reading, reference and search.
The big idea
A gateway, not a corporate card
An autonomous agent will eventually hit a paywall mid-task — an API that costs a cent a call, a dataset behind a charge. Stopping to ask a human defeats the point of autonomy; handing the agent a shared API key or card defeats your bank balance. How do you let an agent pay without letting it — or whatever hijacks it — spend without limit?
We'll build the agent-rails layer: a gateway every payment flows through, a signed mandate that scopes what the agent may spend, spend caps enforced before any money moves, machine-native x402 settlement, and an immutable audit trail. This is not the human card-rails system — see Payment System and Digital Wallet for those; this is the layer built for an autonomous spender.
How to read this: Each step opens with a real design decision — make the call before I show you what ships. Watch the diagram grow, hover the boxes, and at the end let a runaway agent blow its budget and present a forged mandate to see the gateway refuse. Hit Begin.
Step 1 · The baseline
The agent pays the merchant directly
The naive starting point: give the agent an API key or card credential and let it call the merchant's pay endpoint itself. It works in the demo. What's the actual risk the moment this agent is autonomous and reads untrusted content?
Design decision: An autonomous agent holds a payment credential and pays merchants directly. What's the core risk?
The call: The agent holds unlimited spending power with no enforced ceiling, so a bug, an infinite loop, or a prompt injection can spend arbitrarily — and nobody can stop it without revoking the credential everywhere. — Exactly the problem: authority is ambient and unbounded. A runaway loop or a hijacked agent can drain the account, and the only blunt fix is killing a shared credential that other legitimate agents also depend on. There's no per-agent scope, no cap, and no record of why any payment happened.
A direct credential gives the agent unlimited, unscoped spending power. A looping bug or a prompt-injected instruction can spend arbitrarily, and there's no per-agent limit, no record of why a payment happened, and no way to stop one agent without revoking a credential others share.
Ambient authority is the bug: The root problem is that spending power is ambient — the agent can pay simply because it holds a credential. Everything below replaces "can pay because it has the key" with "can pay only this much, here, because a signed mandate says so."
Step 2 · The front door
Route every payment through a gateway
First move: the agent never touches a raw credential. Every payment request goes to a Payment Gateway API instead of the merchant. Why is a mediating front door the prerequisite for everything else?
Design decision: Why route all agent payments through a gateway instead of letting the agent pay merchants directly?
The call: A single mediated choke point is where you can verify the mandate, enforce caps, settle safely, and log every decision — none of which is possible if the agent pays merchants directly with its own credential. — The gateway is the enforcement point. By making every payment flow through one mediated API, you get one place to check "is this allowed?" before anything happens — and the agent holds no spendable credential of its own, so there's nothing to steal or misuse directly.
All payments flow through the gateway, and the agent holds no spendable credential of its own. This single mediated choke point is what makes every downstream control — mandate checks, spend caps, safe settlement, audit — possible; without it, there's nowhere to enforce policy before money moves.
One choke point to govern: Every real control that follows lives at the gateway. Centralizing payment through one mediated API is the architectural move that turns "hope the agent behaves" into "the platform decides, per payment."
Step 3 · Delegated authority
Verify a signed mandate
The gateway needs to know what THIS agent is actually allowed to spend. The answer is a mandate: a signed authorization scoping the agent's spending — a per-transaction ceiling, a total budget, allowed merchants, an expiry. What must the gateway do with it, and why can't it just trust the agent's request?
Design decision: The agent presents a mandate describing what it may spend. How should the gateway treat it?
The call: Verify the mandate's signature, scope, and expiry against the issuer's key before honoring it — authority comes from a signed artifact, not from the agent's claim. — Right: the mandate is like an OAuth token for money. The gateway checks it was validly signed by the issuer, hasn't expired, and actually covers this merchant — so a hijacked agent can't just assert broad spending power, because it can't forge a valid signature.
The Mandate Verifier checks the presented mandate's signature, scope, and expiry against the issuer's key before the gateway honors it. Authority is delegated by a signed artifact — an OAuth-scopes-for-money token — so a prompt-injected agent can't simply claim broad spending power it was never granted.
Signed, not asserted: This is the difference between "the agent says it may spend $10,000" (a claim) and "here is a mandate, signed by the treasury, capping this agent at $50 at these two vendors until Friday" (a verifiable grant). Only the second survives a hijacked agent.
Step 4 · The hard limit
Enforce spend caps before settlement
A valid mandate says the agent may spend up to a cap. Now the gateway has to actually enforce it on each payment. When should the cap be checked — and against what?
Design decision: The mandate allows up to $50 total, $20 per transaction. When and how should the cap be enforced?
The call: Before every settlement: check the amount against the per-transaction ceiling AND the running cumulative spend against the total — refuse if either would be breached. — Correct: the check must run before money moves, on every payment, against both the single-payment limit and the accumulated total. A looping agent that tries ten $20 payments is refused the moment cumulative spend would cross $50 — the cap bounds the damage no matter how many times it loops.
Before every settlement, the Spend-Cap Enforcer checks the amount against the per-transaction ceiling and the running cumulative spend against the mandate total, refusing anything that would breach either. Enforcement runs in the payment layer, before money moves — not as an after-the-fact report — so a runaway loop is bounded to the cap you chose.
Least privilege for money: This is the spending equivalent of a sandbox: the agent's effective power is the narrowest set of payments that still lets it do its job. Everything else is denied by default, checked continuously, enforced by the platform rather than trusted to the model.
Step 5 · Settlement
Pay via x402 and return proof
The mandate is valid and the payment is within cap. Now actually pay the merchant. The merchant speaks x402 — it responds to a request with HTTP 402 and payment terms. How does settlement work, and why is this a clean fit for an agent?
Design decision: The merchant returns HTTP 402 with a price. How does x402 settlement complete the payment?
The call: The gateway performs the payment (typically a small stablecoin transfer), retries the request carrying proof of payment, receives 200 + the resource, and hands it back to the agent. — Right: x402 revives the dormant HTTP 402 status as a machine-native checkout. Server says "402, here's the price," the gateway pays and retries with proof, gets the resource. Payment becomes just another part of the protocol — which is exactly what an autonomous agent needs.
On the merchant's 402 + price, the x402 Settlement service performs the payment, retries with proof, receives the resource, and returns it to the agent — all inside the request/response cycle, no human checkout. The agent never holds a credential; the gateway settles on its behalf, only after mandate and cap checks have passed.
Payment as protocol: x402 turns paying into a normal step of an HTTP exchange — 402, pay, retry with proof, 200. That machine-native flow is what makes autonomous payment possible at all; the gateway wraps it in the verification and caps that make it safe.
Step 6 · Accountability
Log every decision, immutably
Money moved. Whether a payment was allowed or refused, the platform needs a record of why. What has to be captured, and why is an append-only audit trail non-negotiable for a spending system?
Design decision: What should the audit trail record, and why does it matter for a payment gateway?
The call: Every payment decision — mandate checked, cap state, amount, merchant, allow or deny — appended immutably, so any incident can be reconstructed and no record can be quietly altered. — Right: a spending system you can't reconstruct after the fact is one you can't trust. An append-only log of every decision (including refusals) is what lets you audit spend, prove compliance, and investigate a compromised agent — and immutability means a hijacked agent can't erase its own tracks.
The Audit Trail appends every payment decision immutably — mandate checked, cap state, amount, merchant, allow or deny — including refusals. A spending system you can't reconstruct is one you can't trust; the immutable log is what makes spend auditable, incidents investigable, and a compromised agent's tracks impossible to erase.
If it moved money, it's on the record: Every decision the gateway makes is logged, allow or deny. That record is both the compliance artifact and the incident-response tool — and because it's append-only, it survives exactly the compromise it's meant to help investigate.
The payoff
A spender you can actually trust
Put it together: an agent can pay for what its task needs, autonomously — and a runaway loop, a bug, or a full hijack is bounded to a number you chose in advance, with a complete record of every decision.
That's the agent-payment gateway. Delegated, bounded, revocable authority, verified and capped before money moves, settled machine-natively, and logged immutably — the same least-privilege discipline that governs an agent's tools, applied to its wallet.
- The agent holds no spendable credential — every payment flows through one mediated gateway.
- A signed mandate scopes spending (per-txn, total, merchants, expiry); the gateway verifies signature/scope/expiry, never trusting the agent's claim.
- Spend caps are enforced BEFORE every settlement, against both the per-transaction and cumulative limits — a runaway loop is bounded to the cap.
- Settlement uses the x402 (HTTP 402) machine-native flow: pay, retry with proof, deliver — no human checkout, no credential in the agent's hands.
- Every decision, allow or deny, is appended to an immutable audit trail so incidents can be reconstructed and a compromised agent can't erase its tracks.