> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myproceeds.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# How it works

> The Proceeds payment lifecycle, from request to fulfillment, and where to observe each step.

When a client calls a Proceeds-protected URL, Proceeds returns a `402 Payment Required` with a challenge. The client pays using [x402](https://docs.x402.org/introduction), [MPP](https://mpp.dev/overview), or [Circle Nanopayments](https://developers.circle.com/gateway/nanopayments), retries with proof, and Proceeds verifies the payment before proxying the upstream response.

<Note>
  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.
</Note>

## The five steps

<Steps>
  <Step title="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.
  </Step>

  <Step title="Challenge">
    `402 Payment Required`

    The challenge advertises the price, supported networks, and accepted standards. Clients use the challenge to decide how to pay.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Retry">
    The client retries the request with proof of payment in the request headers. Proceeds verifies the payload before forwarding anything upstream.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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**](/dashboard/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**](/dashboard/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.

<Note>
  MPP clients may get a `Payment-Receipt` header. That is for the buyer. You reconcile from Transactions and Events, not from the receipt.
</Note>

<Card title="Troubleshooting" icon="wrench" href="/guides/troubleshooting">
  A short playbook for the most common challenge, payment, and fulfillment failures.
</Card>