Whitepaper

1. Abstract

x402 is an open, HTTP-native payment pattern: a server answers a request with status 402 Payment Required and a description of acceptable payment, and the client retries with a payment attached. This makes paid APIs reachable by software agents without accounts or API keys.

It also hands a spending decision to a program that reads untrusted input. PAY//AGENT proposes a separate layer that evaluates each payment request against an operator-written policy before any authorization exists, and records every decision as a receipt. The policy is deterministic: given the same challenge, policy and state, it always returns the same verdict, and no language model is consulted.

2. System architecture

The proposal has four parts, all running on infrastructure the operator controls.

Interceptor

Wraps the agent's HTTP client. It detects a 402 response, parses the payment requirements, and hands them to the policy engine. The agent never sees signing material.

Policy engine

A pure function from (challenge, policy, ledger state, clock) to a verdict: allow, deny with a reason code, or escalate.

Signer boundary

A separate process or service holding a spending key with its own on-chain or custodial limits. It signs only requests carrying an allow verdict from the engine.

Ledger and receipts

An append-only local store of challenges, verdicts, authorizations and results. It feeds the rolling budget and the observability views.

agent ──http──> interceptor ──402?──> policy engine
                    │                      │
                    │               allow / deny / escalate
                    │                      │
                    │<──authorization── signer boundary
                    │                      │
                    └──retry──> paid API   └──> ledger + receipts

3. Payment lifecycle

1. Request. The agent sends an ordinary HTTP request.
2. Challenge. The server returns 402 with a list of accepted payment requirements: scheme, network, asset, maximum amount, payee, resource and timeout.
3. Selection. The interceptor discards requirements that the policy can never accept, such as networks outside the allowlist, and picks the cheapest remaining option.
4. Policy check. The engine evaluates the selected requirement. The verdict and its inputs are written to the ledger before anything else happens.
5. Authorization. On allow, the signer produces a payment payload. On escalate, the request waits for a human decision or times out. On deny, the agent gets a structured error.
6. Retry. The client repeats the request with the payment header defined by the x402 specification.
7. Result. The server verifies and settles, usually through a facilitator, and returns the resource and a settlement response. The ledger records the outcome and links it to the verdict.

4. Deterministic policy engine

Rules are evaluated in a fixed order. All rules run, so a denial lists every failed rule, not only the first. The proposed order is:

1. Agent and policy are active (revocation).
2. Network is on the allowlist.
3. Asset is on the allowlist.
4. Payee is on the allowlist, when one is configured.
5. Amount is at or below the per-request cap.
6. Amount plus spend inside the rolling window is at or below the budget.
7. Quote age is within the maximum and the server's own timeout.
8. Nonce or payment identifier has not been seen.
9. Amount is below the escalation threshold, otherwise escalate.

Amounts are compared as integers in the asset's base units. Time comes from the engine's clock, never from the challenge. The engine has no network access and no randomness, which makes it testable with fixed vectors and safe to run in an audit replay.

Policy files are versioned. Every receipt stores the policy hash, so a past decision can be reproduced exactly.

5. Service discovery

Agents need to find paid endpoints and their terms before calling them. The concept treats discovery as untrusted input: a catalog entry can suggest a service, but only the policy decides whether it may be paid.

• Operators pin services by origin and expected payee in the policy, not by catalog listing.
• Advertised prices are informational. The amount in the live 402 challenge is what the engine checks.
• A service whose challenge differs from its pinned entry is denied and flagged for review.

Discovery mechanisms in the x402 ecosystem are still evolving. This draft does not depend on any particular catalog.

6. Threat model

Out of scope: compromise of the operator's own machine and signer together, flaws in the underlying chain or facilitator, and whether a paid service delivers what it promised.

7. Economic model

PAY//AGENT has no token, no fee and no revenue mechanism. It moves no funds and takes no cut. In the concept, payments go directly from the operator's spending wallet to the service's payee using the assets and networks that x402 supports.

The economic question the layer addresses is cost control: bounding the worst case of an autonomous spender. The operator chooses caps from their own tolerance for loss. If a future version were offered as a hosted service, its pricing would be published separately; no such service exists.

8. Reference implementation

Status: not released. The only working code today is the in-browser simulation on the playground, which implements the rule order above against example data. It does not sign, connect to wallets or send network requests.

A reference package would include the policy engine as a dependency-free library, an HTTP client interceptor, a signer adapter interface, and a test-vector suite. These are listed in the roadmap and do not exist yet.

9. Roadmap

Intentions, not commitments. No dates are promised.

1. Publish the policy schema and test vectors for comment.
2. Release the policy engine as an open-source library.
3. Build a client interceptor against the official x402 client libraries, on testnets only.
4. Add escalation through a pluggable approval channel.
5. Commission an independent security review before any mainnet guidance.

10. Limitations

• A policy only limits payments that pass through it. An agent with another path to funds is not constrained.
• Rules check the payment, not the value of what was bought. A within-budget payment to an allowlisted payee can still be wasteful.
• Rolling budgets depend on an accurate local ledger. Settlement that fails after an allow verdict must be reconciled.
• The x402 specification may change. Field names in this draft follow public documentation and may need updates.
• Nothing here has been audited or tested in production.

11. Revision history

12. Glossary

402 challenge

An HTTP response with status 402 listing the payment a server will accept.

Facilitator

In x402, a service that verifies and settles payments on behalf of a resource server.

Policy

An operator-written set of limits that the engine checks before any payment is authorized.

Verdict

The engine's output: allow, deny with reason codes, or escalate.

Receipt

A structured record tying a challenge, verdict and result together.

Rolling budget

A spending limit over a sliding time window, such as the last 24 hours.

Escalation

Holding a payment for a human decision because it exceeds a threshold.

Signer boundary

The separation between the agent process and the key that can authorize payments.

13. References

Official x402 materials. Consult them for the current protocol; this draft does not replace them.

• x402.org, the project site.
• github.com/coinbase/x402, specification and reference libraries.
• Coinbase Developer Platform x402 documentation.
• RFC 9110, section 15.5.3, the HTTP 402 status code.