The whole design, in writing
Every step of the build above, written out: the problem each piece solves, the option that was taken and the ones that were not, the numbers, and how it fails in production.
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.
What the new pieces do
- Agentclient
- An autonomous agent that hits a paywall mid-task — an API that charges per call, a dataset behind a fee, a compute job to rent. It needs to pay without a human checkout, and without holding unlimited spending power.
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?
An autonomous agent holds a payment credential and pays merchants directly. What's the core risk?
"Only when it legitimately needs to" assumes the agent always behaves. An agent reads untrusted web content and tool output; one prompt injection, or one looping bug, turns a credential with no spending limit into an unbounded liability.
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.
Latency is a secondary concern. The immediate danger is that an autonomous process holds unlimited, unscoped spending authority — a correctness and security problem, not a performance one.
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.
Why this piece earns its place
Worth naming when this baseline is genuinely fine, because sometimes it is: one internal agent, one merchant, a prepaid card with a hard balance the issuer enforces. A ceiling exists there too — it just lives at the card issuer, resets on the issuer's calendar rather than your task's, and moves only when a human calls the bank. The invoice is then your only record, and it is the wrong shape. Spend arrives aggregated by credential, so a charge cannot be tied back to a run, a tenant or a job: you can't pass it through to the customer who caused it, can't dispute the single line that was wrong, and can't say what the money bought. The operational sting is how you discover the ceiling at all. The issuer announces it with a decline, and a decline reaches the agent as an ordinary HTTP error — which an agent written to retry on errors will cheerfully treat as something to try again. That same credential is usually sitting in a test harness as well, spending real money on runs nobody meant to pay for.
What the new pieces do
- Merchant / APIcontrol
- The external service the agent is paying — an API, a data provider, a compute host. Speaks the x402 flow: responds with a price, accepts proof of payment, then delivers the resource.
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?
Why route all agent payments through a gateway instead of letting the agent pay merchants directly?
Caching isn't the point. The gateway exists to be a control point — a single place where every payment can be verified, capped, recorded, and refused before money moves.
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.
Convenience isn't the driver — and in fact the gateway deliberately restricts which merchants are in scope. The reason for the front door is control: a single point to enforce policy and record decisions.
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.
Why this piece earns its place
The front door earns its keep the moment you notice how often an agent retries. A planner that times out on a tool call re-issues it, and a re-issued payment is not a re-issued read — it moves money twice. So a payment request carries an idempotency key, and that key has to be minted by the caller as part of the payment intent rather than generated at the gateway, because a gateway-minted key is fresh on every retry and therefore never matches the attempt it was meant to deduplicate. That is the general rule for this API. Anything only the caller can know — which intent this is, which mandate it is acting under, what the spend is for — belongs in the request. Anything policy decides — which merchants are reachable, what the ceilings are, how long a held payment waits before it is abandoned — belongs in configuration the agent cannot set. The other half of that contract is the response. A policy refusal and a transport failure must not look alike to the caller: a denial is final, and a planner that retries it burns its entire loop arguing with a decision that will never change, while a timeout is the one case where retrying under the same key is exactly right. Give them different shapes and the agent can tell them apart.
What the new pieces do
- Payment Gateway APIgateway
- The single front door for every agent payment — mandate verification, spend-cap enforcement, settlement, and audit all flow through here. The agent never touches a raw credential.
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?
The agent presents a mandate describing what it may spend. How should the gateway treat it?
An agent that's been prompt-injected will happily send a mandate claiming it can spend anything. A mandate is only meaningful if the gateway can prove it wasn't fabricated by the agent presenting it.
A single global limit can't express per-agent scope — this agent may buy data, that one may rent compute, each with different caps and merchants. The mandate is what carries that per-agent authority.
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.
Why this piece earns its place
A signature proves a mandate was issued. It cannot prove anyone still wants it honored, and that gap is the whole operational story. Expiry is the only revocation the artifact carries by itself, which makes picking it a scheduling decision as much as a security one. Set it short and the issuer becomes a runtime dependency: agents reissue mid-task, the signing service lands on the payment path, and its availability becomes yours. Short expiries also strand work — a mandate that lapses partway through a long task leaves spend already made with nothing delivered for it, and the agent cannot finish or refund its way out. Anything faster than expiry means a revocation check, a lookup on every payment, and because the gateway refuses what it cannot check, an outage in that lookup is an outage in paying at all. Then there is key handling, which is the part that gets skipped in a design round. The gateway verifies against the issuer's key, so the mandate has to name which key signed it — a kid — and rotation means publishing the new key, honoring both through an overlap, then retiring the old one. Rotate without that overlap and every unexpired mandate fails verification at once — an incident that looks like an attack and is really a deploy.
What the new pieces do
- Mandate Verifierservice
- Checks the signed mandate the agent presents — is the signature valid, is the merchant in scope, is it unexpired? Authority is a signed artifact, not a claim in the request.
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?
The mandate allows up to $50 total, $20 per transaction. When and how should the cap be enforced?
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.
A cap checked only after the fact doesn't bound anything — the money has already left. By the time you total it up, a runaway agent has already overspent. Enforcement has to run alongside consumption, before each payment.
Then an agent making a hundred small in-limit payments blows far past its total budget while never tripping the per-transaction check. You need BOTH ceilings — the single-payment limit and the running total.
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.
Why this piece earns its place
Check-then-settle is two operations over shared mutable state, so the interesting failure here is a race rather than a breach. Two payments under the same mandate can both read a cumulative total that is under the cap and both proceed, and the mandate ends up overspent by exactly the amount you were enforcing. The fix is to treat the budget as something you reserve rather than something you read: hold the amount atomically before settlement, release the hold if the payment fails, convert it to a spend when proof comes back. That also covers the uglier case where settlement succeeds and the counter write does not, which a record-afterwards design turns into money that left without ever being counted. Be careful what the counter is keyed on, too. The obvious key is the mandate id, because the total belongs to the mandate — but then a reissue starts the count from zero, and a looping agent only has to obtain a fresh mandate to have its budget back. Carry a budget identity for the agent across reissues and count against that as well. Units, last: a $20 ceiling has to mean the amount that actually leaves, network fees included, and when the mandate is denominated in dollars while settlement moves a stablecoin, that conversion belongs inside the cap check. A cap enforced on the pre-fee number is not the cap you promised.
What the new pieces do
- Spend-Cap Enforcerservice
- Before any settlement, checks the amount against the per-transaction ceiling and the running cumulative spend against the mandate total. Refuses anything that would breach either.
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?
The merchant returns HTTP 402 with a price. How does x402 settlement complete the payment?
That reintroduces a human in the loop and defeats the point of an autonomous agent paying mid-task. x402 is designed to settle inside the request/response cycle, no human checkout.
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.
Handing the agent a credential at settlement time recreates the original ambient-authority problem. The gateway settles on the agent's behalf; the agent never holds a spendable credential.
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.
Why this piece earns its place
Two things about this flow only show up once you have run it. First, the price belongs to the merchant and arrives in the 402, so the number the enforcer judges does not exist until the merchant has been asked. That does not move the cap check after settlement — the 402 exchange is a quote and moves no money, and the decision still completes before any transfer — but it does mean the merchant is contacted before the gateway knows whether it will pay at all. So the opening request has to be safe to repeat and free to abandon. The gateway will routinely fetch a price, refuse it on the cap, and never come back; if a merchant treats that first call as a reservation, your refusals quietly consume its stock. Second, there is a window between paying and holding the resource. The transfer lands, the retry carrying proof goes out, and the merchant times out. Money has moved, nothing has been delivered, and a gateway that simply starts over pays twice. So the proof is persisted against the payment intent the moment it exists, and a retry re-presents the stored proof instead of settling again — the proof is the receipt. Finality is not yours to set either: the merchant decides how much confirmation counts as proof, so settlement latency is a merchant policy you inherit.
What the new pieces do
- x402 Settlementservice
- Executes the HTTP 402 flow: on the merchant's 402 + price, performs the payment (typically a small stablecoin transfer) and retries with proof, then hands the resource back to the agent.
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?
What should the audit trail record, and why does it matter for a payment gateway?
Refusals are often the most important events: a spike in denied payments is how you detect a runaway or hijacked agent. An audit trail that drops refusals is blind to exactly the incidents it exists to catch.
A daily total can't answer "why did this agent pay this merchant?" or reconstruct an incident. You need the per-decision detail — mandate, cap state, amount, merchant, allow/deny — not just an aggregate.
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.
Why this piece earns its place
The trail earns its keep after the incident rather than during it, and that changes what you build it for. Every check upstream asks a single-payment question: is this one inside this mandate? Nothing in that path can see a crowd of unrelated agents converging on a merchant none of them had ever paid, or one mandate consuming its whole budget in a single burst while every individual payment sits comfortably under its ceiling. Those are shapes in the record, which makes the trail where detection actually lives — so it has to be queryable, not merely durable, and written where you can join across agents instead of one file per service. Immutability then costs you something, and it is better to pay that deliberately. Nothing can be edited, so a mistake is corrected by appending a compensating entry, and anything you write you have agreed to keep for the life of the log — a good reason to record identifiers and decisions rather than payloads someone may later be entitled to have erased. And append-only is a property you buy, not a word you write. On ordinary storage it is an access-control claim that anyone who can deploy the gateway can undo, so revoke UPDATE and DELETE at the database role, or chain each entry to a hash of its predecessor so a removal is at least detectable.
What the new pieces do
- Audit Traildata
- An append-only record of every payment decision — mandate checked, cap state, amount, merchant, allow/deny — because a spending system you can't reconstruct after the fact is a spending system you can't trust.
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.
Everything you assembled, in order
- 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.