When a client calls a Proceeds-protected URL, Proceeds returns aDocumentation Index
Fetch the complete documentation index at: https://docs.myproceeds.xyz/llms.txt
Use this file to discover all available pages before exploring further.
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.
The five steps
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.Challenge
402 Payment RequiredThe challenge advertises the price, supported networks, and accepted standards. Clients use the challenge to decide how to pay.Pay
The client signs a payment authorization. Proceeds is neutral to the underlying mechanism:
- x402: an EIP-3009 USDC authorization, attached as a header.
- MPP: a
Paymentcredential negotiated through an MPP-aware client likemppx. - Circle Nanopayments: an offchain Gateway authorization, settled in batch.
Retry
The client retries the request with proof of payment in the request headers. Proceeds verifies the payload before forwarding anything upstream.
What Proceeds does at each step
| Step | What Proceeds does |
|---|---|
| Request | Resolves serviceId and slug, checks the HTTP method, returns a 402 challenge. |
| Pay | Nothing — the client holds the keys and signs the payment. |
| Retry | Validates the payment payload against the configured network and standard. |
| Deliver | Forwards the request to the upstream API, attaches upstream auth, and proxies the response. |
Observability
Proceeds writes two complementary records for every protected request.- Transactions track payment state. Each transaction moves through
Pending → Completed, or terminates inFailed. - Events track lifecycle steps. Proceeds emits
Request,Payment,Fulfillment, andErrorevents.
Troubleshooting
A short playbook for the most common challenge, payment, and fulfillment failures.