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

# Payment Flow

> The x402 and MPP 402 challenge, headers, and pricing semantics.

Paid routes return HTTP `402` with a **dual challenge** so a single request works
with either supported protocol. Use any x402- or MPP-aware client.

## The 402 handshake

1. A plain request to a paid route returns `402` with two headers:
   * `WWW-Authenticate: Payment ...` — the MPP challenge
   * `PAYMENT-REQUIRED` — the x402 v2 challenge
2. Retry the **same request** through a payment-aware client, or manually with:
   * `Authorization: Payment <credential>` for MPP, or
   * a `PAYMENT-SIGNATURE` header for x402 v2.
3. On success (`200`), the response includes `synthesizedSummary` and
   `paymentInfo`.

<Warning>
  Treat a `402` as a "pay and retry" signal, not a failure. If a plain HTTP
  request returns `402`, retry it through the payment-aware client rather than
  surfacing an error.
</Warning>

## Pricing: advisory vs authoritative

The OpenAPI discovery document exposes `x-payment-info.offers[]` on paid routes.
These offers are **advisory** — they may list Base USDC (x402), Tempo, and
Stripe charges, or catalog floor prices.

The **runtime `402` challenge is authoritative**. Per-post pricing comes from the
live challenge, and the price may scale with content — for example, stock-picks
are priced by the number of distinct attributed source articles in the response.
Always trust the live `402` over discovery offers.

## Status codes

| Status | Meaning                                   | Action                                                |
| ------ | ----------------------------------------- | ----------------------------------------------------- |
| `200`  | Success                                   | Read `synthesizedSummary` and `paymentInfo`           |
| `402`  | Payment required                          | Retry the same request through a payment-aware client |
| `403`  | Insufficient purchased credits (API keys) | Top up purchased balance                              |
| `404`  | Content not found                         | Do not pay; verify the publication / post slugs       |
| `429`  | Rate limited                              | Back off and retry                                    |
| `503`  | Summary not ready (`summary_not_ready`)   | Retry later; no payment challenge is issued           |

<Note>
  A `404` and a `503` never carry a payment challenge — do not pay on either.
  `503` means the summary is still being generated; retry shortly.
</Note>

## Discovery

Prefer `GET /openapi.json` (OpenAPI 3.1) for route shapes, JSON schemas, and
paid-route `x-payment-info.offers[]` metadata. If OpenAPI is unavailable, use
`GET /.well-known/x402` for the paid resource list in `METHOD /path` form. The
root `x-discovery.ownershipProofs` field is a Drip vendor extension, not part of
core MPP discovery.