# MPP payments for paid HTTP resources

402Mob can expose the three built-in paid HTTP report resources through both x402 v2 and the Machine Payments Protocol (MPP) EVM `charge` method. MPP support is opt-in and disabled by default. Check [`GET /v1/capabilities`](https://evidence.contact/v1/capabilities) and confirm `paidHttpPayments.mpp.enabled` is `true` before sending an MPP credential.

## Supported scope

MPP is available only for these POST resources:

| Route | Price |
| --- | ---: |
| `/v1/reports/text-v1` | 0.001 USDC |
| `/v1/reports/base-transaction-v1` | 0.02 USDC |
| `/v1/reports/base-invoice-v1` | 0.02 USDC |

The payment uses Base mainnet (`eip155:8453`), native USDC (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`), and an EIP-3009 authorization signed by the buyer wallet. Merchant artifact checkout, Work Tickets, and MCP payment calls keep their existing documented payment flows.

## Request sequence

1. Send the schema-valid JSON request with a persisted `Idempotency-Key` and no payment credential.
2. If MPP is enabled, the HTTP 402 response includes the MPP challenge in `WWW-Authenticate`. The same response also carries the x402 quote for x402 clients. Read the selected protocol's complete terms before signing.
3. For MPP, submit the serialized credential using `Authorization: Payment <credential>`. Keep the method, URL, body, content type, and idempotency key identical to the challenged request. The server binds the MPP challenge scope to the route, exact request body, and key.
4. A settled response includes `Payment-Receipt` and `X-402Mob-Operation`. A valid but unresolved settlement returns HTTP 202 without a success receipt. Preserve the original request, credential, and operation ID. Replaying the same request returns the same operation and never submits a second authorization; use the payer-signed [operation recovery flow](./evidence-recovery.md#recover-an-existing-operation) to check or reconcile its outcome. Do not create another authorization while the operation is pending.

x402 clients continue to use `PAYMENT-SIGNATURE` and receive `PAYMENT-RESPONSE`. Do not send both payment credentials in one request.

## Buyer-side retry journal

Create the MPP credential explicitly and write it to the private journal before sending the paid request. This avoids relying on a payment-client event callback for a critical journal write. If the server returns 202 or the connection drops, replay with `rawFetch` and the saved `Authorization` value; calling payment-aware `fetch` again could answer a fresh challenge and create a different authorization.

```ts
import { Mppx, evm } from "mppx/client";
import type { Account } from "viem";

declare const buyerAccount: Account; // Provided by the agent's wallet signer.
declare const journal: {
  save(key: string, record: PurchaseRecord): Promise<void>;
  load(key: string): Promise<PurchaseRecord | undefined>;
};
type PurchaseRecord = {
  url: string;
  body: string;
  idempotencyKey: string;
  credential?: string;
};

const url = "https://evidence.contact/v1/reports/text-v1";
const idempotencyKey = "text-report-mpp-run-0001";
const record: PurchaseRecord = {
  url,
  body: JSON.stringify({ text: "A bounded report request." }),
  idempotencyKey,
};
await journal.save(idempotencyKey, record);

const mpp = Mppx.create({ methods: [evm({ account: buyerAccount })], polyfill: false });
const init = {
  method: "POST",
  headers: { "Content-Type": "application/json", "Idempotency-Key": idempotencyKey },
  body: record.body,
};

// First receive the challenge without creating or sending a payment credential.
const challengeResponse = await mpp.rawFetch(url, init);
if (challengeResponse.status !== 402) throw new Error(`Expected HTTP 402, got ${challengeResponse.status}`);
const payment = await mpp.preparePayment(challengeResponse, { request: init });
const credential = await payment.createCredential();
record.credential = credential; // Serialized `Payment ...` value for Authorization.
await journal.save(idempotencyKey, record); // Must finish before the paid request.

async function replaySaved(saved: PurchaseRecord): Promise<Response> {
  if (!saved.credential) throw new Error("Payment credential was not journaled");
  const headers = new Headers({ "Content-Type": "application/json", "Idempotency-Key": saved.idempotencyKey });
  headers.set("Authorization", saved.credential);
  return mpp.rawFetch(saved.url, { method: "POST", headers, body: saved.body });
}

const paidInit = payment.setCredential(init, credential);
let first: Response;
try {
  first = await mpp.rawFetch(url, paidInit);
} catch {
  const saved = await journal.load(idempotencyKey);
  if (!saved) throw new Error("Purchase journal is missing");
  first = await replaySaved(saved); // Reuse the exact credential after an ambiguous connection failure.
}

if (first.status === 202) {
  const saved = await journal.load(idempotencyKey);
  if (!saved) throw new Error("Purchase journal is missing");
  const recovered = await replaySaved(saved);
  // A 202 still means pending; keep this record and use payer-signed operation recovery.
}
```

Keep the journal private: it contains a signed payment credential and the request body. Use the same URL, body, content type, idempotency key, and credential for every replay. A successful response has `Payment-Receipt`; 202 does not. Replays do not reconcile a pending settlement; use the operation recovery flow linked above.

## Operator configuration

`MPP_ENABLED` must be exactly `true` to enable MPP for these routes. `MPP_SECRET_KEY` must contain at least 32 bytes and protects server-issued MPP challenges. `npm run setup` generates this secret in the private `.env`; the capability response never reveals it. Keep the flag off until the specific deployment has been validated against Base settlement and recovery.

MPP uses the existing 402Mob operation store and facilitator flow: the result is retained before settlement is submitted, confirmed settlement is checked against Base USDC authorization and transfer events, and unresolved outcomes stay recoverable. MPP does not change the recipient, amount, or the service's noncustodial payment model.

## Status

The repository implementation is opt-in and typechecked. A live MPP Base transaction has not yet been performed, and MPP is not available in production unless its operator has enabled and validated it. See the [paid HTTP resource guide](./paid-tools.md) and [machine-readable capabilities](https://evidence.contact/v1/capabilities).

Protocol references: [MPP documentation](https://mpp.dev/), [MPP specifications](https://github.com/tempoxyz/mpp-specs), and the [mppx TypeScript implementation](https://github.com/wevm/mppx).
