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

# x402 Agentic Payments

> Let an AI agent pay for a resource autonomously over HTTP 402 — no human, no card. Macropay is the facilitator; settlement draws down a prepaid wallet.

[x402](https://www.x402.org/) revives the long-dormant **HTTP `402 Payment Required`**
status code as a real payment rail for agents. An agent requests a paid resource,
gets a machine-readable price, pays, and retries — with no human in the loop and no
pre-provisioned API key. Macropay acts as the **facilitator**: it quotes, verifies,
and settles payments by drawing down a payer's **prepaid wallet**.

<Note>
  x402 settlement is **off by default** and enabled per organization (it moves
  money). The payer must be a Macropay **customer of the merchant with a funded
  prepaid wallet**. Turn it on under **Settings → Integrations → MCP / x402**.
</Note>

## The flow

```
agent ──GET /resource──────────────▶ merchant
agent ◀──402 + accepts[] (a quote)── merchant      (Macropay POST /v1/x402/quote)
agent ──GET /resource, X-PAYMENT───▶ merchant
                                     merchant ──POST /v1/x402/verify──▶ Macropay
                                     merchant ──POST /v1/x402/settle──▶ Macropay
                                       │  debits the payer's wallet, returns a signed proof
agent ◀──200 + content────────────── merchant
```

1. **Quote** — the merchant asks Macropay for a signed payment requirement and
   returns it in a `402` body.
2. **Pay** — the agent retries with an `X-PAYMENT` header referencing the quote and
   its customer id.
3. **Verify / settle** — the merchant asks Macropay to verify the payment, then
   settle it. Settlement draws down the customer's prepaid wallet and returns a
   signed proof the merchant keeps.

## Wire format

Macropay follows the x402 shape, so x402-aware tooling interoperates. The scheme is
`macropay-wallet` on network `macropay`; `asset` is the ISO currency (e.g. `usd`)
and amounts are strings of minor units (cents).

**`402` response body** (from `POST /v1/x402/quote`):

```json theme={null}
{
  "x402Version": 1,
  "error": "payment required",
  "accepts": [
    {
      "scheme": "macropay-wallet",
      "network": "macropay",
      "maxAmountRequired": "500",
      "resource": "https://api.acme/report",
      "payTo": "<merchant_org_id>",
      "asset": "usd",
      "maxTimeoutSeconds": 300,
      "extra": { "quote_id": "x402q_…", "expires_at": 1796745600, "signature": "…" }
    }
  ]
}
```

**`X-PAYMENT` header** — base64 of:

```json theme={null}
{ "x402Version": 1, "scheme": "macropay-wallet", "network": "macropay",
  "payload": { "quote_id": "x402q_…", "customer_id": "<customer_id>" } }
```

The quote is **stateless and HMAC-signed**: verify/settle trust it without a
lookup, and any tampering (amount, payTo, resource) or expiry is rejected. Each
quote settles **at most once** (idempotent + replay-safe on `quote_id`).

## Endpoints

| Endpoint                   | Purpose                                             | Scope        |
| -------------------------- | --------------------------------------------------- | ------------ |
| `POST /v1/x402/quote`      | Mint a signed `402` payment requirement             | `x402:write` |
| `POST /v1/x402/verify`     | Validate an `X-PAYMENT` without moving money        | `x402:read`  |
| `POST /v1/x402/settle`     | Draw down the payer's wallet, return a signed proof | `x402:write` |
| `GET /v1/x402/settlements` | Recent settlements for your org                     | `x402:read`  |

`verify` and `settle` take the same body: `{ paymentPayload, paymentRequirements }`.
`settle` returns `{ success, error?, proof? }`, where `proof` is a signed receipt
(`id`, `quote_id`, `amount`, `currency`, `payer_customer_id`, `signature`, …).

## Pay from an MCP agent

An agent connected to the [Macropay MCP server](/features/integrations/mcp) can
build the `X-PAYMENT` header with the `pay_402` tool:

> *"I got a 402 with quote `x402q_abc` — pay it as customer `cus_123`."*

`pay_402(quote_id="x402q_abc", customer_id="cus_123")` → `{ x_payment: "…" }`. The
agent re-requests the resource with `X-PAYMENT: <x_payment>`; the merchant settles
it. (The tool only builds the header — the merchant's `settle` call moves the money.)

## Safety model

* **Off by default, opt-in per org.** Settlement is refused unless the merchant has
  `x402_enabled` on — and the funds come from a wallet the customer pre-funded.
* **Signed, expiring quotes.** Tampered or expired quotes are rejected; replays are
  blocked by the unique `quote_id`.
* **Real authorization.** Settlement runs through the existing wallet ledger with
  its `InsufficientBalance` guard — there is no separate money-movement path.
* **Funded-balance only.** v0 draws down a prepaid wallet; an agent can never spend
  more than its balance.

## Roadmap

v0 settles against a prepaid wallet held with the merchant. Future work: a
Macropay-level wallet usable across merchants, on-chain settlement schemes, and a
drop-in `@paywall(price=…)` middleware that emits the `402` and verifies proofs in a
few lines. The [MCP agentic-commerce tools](/features/integrations/mcp-agentic-commerce)
(`create_checkout`, `record_usage`) and `pay_402` are the human-supervised steps
toward fully autonomous agent-to-agent payments.