Skip to main content
When a client calls a Proceeds-protected URL, Proceeds returns a 402 Payment Required with a challenge. The client pays using x402, MPP, or Circle Nanopayments, retries with proof, and Proceeds verifies the payment before proxying the upstream response.
You do not run mppx or x402 middleware. Proceeds issues the challenge, verifies the credential, and proxies upstream. Your origin never sees Authorization: Payment or x402 payment headers.

​
The five steps

1

Request

GET https://myproceeds.xyz/api/x402/pay/{serviceId}/{slug}Proceeds matches the URL to a paywall, applies HTTP method restrictions, and returns a challenge.
2

Challenge

402 Payment RequiredThe challenge advertises the price, supported networks, and accepted standards. Clients use the challenge to decide how to pay.
3

Pay

The client signs a payment authorization. Proceeds is neutral to the underlying mechanism:
  • x402: an EIP-3009 USDC authorization. Facilitator verifies and settles. Simpler seller path, more buyers today.
  • MPP: a Payment credential from an MPP-aware wallet (Tempo Wallet, AgentCash). Peer-to-peer, no facilitator, better buyer DX.
  • Circle Nanopayments: an offchain Gateway authorization, settled in batch. The Proceeds path for sub-cent volume — not an MPP session.
4

Retry

The client retries the request with proof of payment in the request headers. Proceeds verifies the payload before forwarding anything upstream.
5

Deliver

Proceeds proxies the request to your Target URL — with custom headers, query parameters, and upstream auth attached — and streams the response back to the client.

​
What Proceeds does at each step

​
Observability

Proceeds writes two complementary records for every protected request.
  • Transactions track payment state. Standard x402 and MPP typically land as Completed or Failed. Circle Nanopayments go Pending → Completed while Gateway settles the batch onchain.
  • Events track lifecycle steps. Proceeds emits REQUEST, SUCCESS, and ERROR events.
When a paid request behaves unexpectedly, start in Events to find the step that failed, then cross-check the matching record in Transactions.
MPP clients may get a Payment-Receipt header. That is for the buyer. You reconcile from Transactions and Events, not from the receipt.

Troubleshooting

A short playbook for the most common challenge, payment, and fulfillment failures.