Paying for an API Request: A Local Agent Payment Simulation

Hands-on simulation · Run October 28, 2026. Local memory only; no network, wallet or real funds.

When an agent buys data, it needs to know not just how to pay but whether it is authorized, whether it has paid twice and whether the data arrived. This small local, in-memory experiment illustrates those states.

The hypothetical rules are a $10 budget, approval for purchases over $3, and one allowed merchant, data.example. Amounts are stored in cents. This teaching simulation implements neither x402, an on-chain transaction nor a vendor API.

sequenceDiagram participant A as Simulated agent participant L as Local policy and payment simulator participant D as Delivery record A->>L: Buy order-1 for $1 L->>L: Check budget, merchant and threshold L-->>A: Simulated payment succeeds A->>D: Record simulated delivery D-->>A: Delivered or delivery failed

Reproduce it

Place payment_lab.py and test_payment_lab.py in one directory and run:

python3 -m unittest -v test_payment_lab

On October 28, 2026, five tests passed locally. Tests use Python’s standard library, no account or external network, and create no real wallet.

Scenario	Simulation result
Simulated payment succeeds, delivery fails	Payment remains successful; delivery is recorded separately as failed
Total budget exceeded	Returns insufficient budget
Per-purchase threshold exceeded	Requires approval; may proceed after approval
Authorization expired or merchant disallowed	Rejected separately
Retry same order after simulated timeout	Returns unknown status without creating a second simulated payment

Merchants, approvals and outcomes are predefined simulation conditions. The run establishes how example code behaved under those conditions, not that a real product provides the same safeguards.

Why separate payment and delivery?

The simulation permits successful payment and failed delivery simultaneously. Real systems can also have different states; orders, payments and delivery records need to be linked. When something fails, check status first, then apply the service terms to decide on retry, refund or human handling.

The sample returns an existing status for the same order to illustrate avoiding blind repetition. It does not guarantee global idempotency or query real payments. Stripe’s payment and fulfillment documentation also distinguishes states and asynchronous events; consult the actual provider for behavior.

What remains before a real x402 test?

Real x402 requires a provider’s payment requirements, a client-created credential, verification and settlement, plus checks of network, asset, test environment and service capability. The official specification is a starting point.

A real follow-up test should separately record tool version, test network, steps, transaction status and results. This simulation cannot substitute for it.