# Use MPP with x402 \[Run both payment flows together] MPP plugs into your existing x402 server. Both protocols use HTTP `402` to gate API access behind payment, and x402's "exact" charge flow maps directly onto MPP's `charge` intent. Adding MPP gives you standard `WWW-Authenticate` / `Authorization` headers, multi-method support (stablecoins, cards, Lightning), sessions for streaming payments, and an [IETF standards track](https://paymentauth.org) foundation—all without changing your business logic. ## What MPP adds MPP builds on the same `402` pattern that x402 established, and extends it with standardized headers and new capabilities. | | x402 | MPP | |---|---|---| | **Challenge** | `PAYMENT-REQUIRED` header | `WWW-Authenticate: Payment` header | | **Credential** | `PAYMENT-SIGNATURE` header | `Authorization: Payment` header | | **Receipt** | `PAYMENT-RESPONSE` header | `Payment-Receipt` header | | **Payment methods** | Stablecoins only | Stablecoins, cards, digital wallets, and many other methods | | **Sessions** | No | Yes—off-chain vouchers for sub-cent streaming | | **Error format** | Custom | [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) Problem Details | | **Idempotency** | No | Built-in Challenge binding | :::info MPP is compatible with x402. The x402 "exact" charge flow maps directly onto MPP's `charge` intent. MPP extends beyond x402 with idempotency, Receipts, request binding, multiple payment methods, and efficient payment sessions. ::: ## Key concepts MPP uses three protocol objects in every payment flow—the same lifecycle x402 uses, with standardized names: * **Challenge** — The server's `402` response advertising what payment is required. Sent in the `WWW-Authenticate: Payment` header. Equivalent to x402's `PAYMENT-REQUIRED`. * **Credential** — The client's signed payment authorization. Sent in the `Authorization: Payment` header. Equivalent to x402's `PAYMENT-SIGNATURE`. * **Receipt** — The server's confirmation that payment settled. Sent in the `Payment-Receipt` header. Equivalent to x402's `PAYMENT-RESPONSE`. ## Add x402 to your MPP server with `mppx` Use `evm.charge` when you want to support both MPP "charge" intents and x402 "exact" intents with a single `mppx` import. :::info When x402 options are enabled, the server automatically handles MPP charge and x402 exact flows. ::: ### Run an x402-compatible endpoint Configure `evm.charge` with a known x402 asset and a facilitator. The route returns x402-compatible Challenges in addition to MPP Challenges, and accepts both MPP and x402 Credentials. ```ts twoslash [server.ts] import { evm, Mppx } from 'mppx/server' const mppx = Mppx.create({ methods: [ // [!code hl:start] evm.charge({ currency: evm.assets.baseSepolia.USDC, recipient: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', x402: { facilitator: 'https://x402.org/facilitator', }, }), // [!code hl:end] ], secretKey: process.env.MPP_SECRET_KEY ?? 'local-dev-secret', }) export async function GET(request: Request) { // [!code hl:start] const result = await mppx.evm.charge({ amount: '0.01', description: 'Premium data access', })(request) // [!code hl:end] if (result.status === 402) return result.challenge return result.withReceipt(Response.json({ ok: true })) } ``` ### Add MPP to the same endpoint Use `mppx.compose` when one endpoint should support x402 EVM charges and another MPP method. The same route verifies either wire format. ```ts twoslash [server.ts] import { evm, Mppx, tempo } from 'mppx/server' const mppx = Mppx.create({ methods: [ // [!code hl:start] evm.charge({ currency: evm.assets.baseSepolia.USDC, recipient: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', x402: { facilitator: 'https://x402.org/facilitator', }, }), // [!code hl:end] tempo.charge({ currency: '0x20c0000000000000000000000000000000000000', recipient: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', testnet: true, }), ], secretKey: process.env.MPP_SECRET_KEY ?? 'local-dev-secret', }) // [!code hl:start] const paid = mppx.compose( [mppx.evm.charge, { amount: '0.01', description: 'Premium data access' }], [mppx.tempo.charge, { amount: '0.01', description: 'Premium data access' }], ) // [!code hl:end] export async function GET(request: Request) { const result = await paid(request) if (result.status === 402) return result.challenge return result.withReceipt(Response.json({ ok: true })) } ``` ### Use Hono middleware ```ts twoslash [server.ts] import { Hono } from 'hono' import { evm, Mppx } from 'mppx/hono' const app = new Hono() const mppx = Mppx.create({ methods: [ // [!code hl:start] evm.charge({ currency: evm.assets.baseSepolia.USDC, recipient: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', x402: { facilitator: 'https://x402.org/facilitator', }, }), // [!code hl:end] ], secretKey: process.env.MPP_SECRET_KEY ?? 'local-dev-secret', }) // [!code hl:start] app.get('/paid', mppx.evm.charge({ amount: '0.01' }), (c) => c.json({ ok: true }), ) // [!code hl:end] ``` ### Call with the mppx client `evm.charge` on the client signs both native MPP EVM charge Challenges and x402 exact Challenges. ```ts twoslash [client.ts] import { Fetch, evm } from 'mppx/client' import { privateKeyToAccount } from 'viem/accounts' const fetch = Fetch.from({ methods: [ // [!code hl:start] evm.charge({ account: privateKeyToAccount( '0x0123456789012345678901234567890123456789012345678901234567890123', ), currencies: [evm.assets.baseSepolia.USDC], maxAmount: '1.00', }), // [!code hl:end] ], }) const response = await fetch('https://api.example.com/paid') console.log(response.status) // @log: 200 ``` :::tip Because MPP uses the standard `WWW-Authenticate` scheme, it works with HTTP intermediaries (proxies, CDNs, API gateways) that understand [RFC 7235](https://www.rfc-editor.org/rfc/rfc7235) authentication. ::: ## Prompt mode Paste this into your coding agent to add MPP in one prompt: {`Use https://mpp.dev/guides/use-mpp-with-x402.md#add-x402-to-your-mpp-server-with-mppx as reference. Add mppx to my existing x402 server. Use the Tempo payment method with USDC.e. Keep the same pricing and route structure. Add mppx.charge to each paid endpoint. Point out areas where I could benefit from adding sessions.`} ## Advanced: Add MPP to your existing x402 server ::::steps ### Install `mppx` :::code-group ```bash [npm] $ npm install mppx viem ``` ```bash [pnpm] $ pnpm add mppx viem ``` ```bash [bun] $ bun add mppx viem ``` ::: ### Add `mppx` alongside your existing routes Here's a typical x402 server with MPP applied. Your business logic stays the same—you swap the payment middleware. ```ts [server.ts] import express from 'express' import { Mppx, tempo } from 'mppx/express' // [!code hl] const app = express() const mppx = Mppx.create({ // [!code hl] methods: [ // [!code hl] tempo({ // [!code hl] currency: '0x20c0000000000000000000000000000000000000', // [!code hl] recipient: '0xYourAddress', // [!code hl] }), // [!code hl] ], // [!code hl] secretKey: process.env.MPP_SECRET_KEY ?? 'local-dev-secret', // [!code hl] }) // [!code hl] app.get( '/api/data', mppx.charge({ amount: '0.01', description: 'Premium data access' }), // [!code hl] (req, res) => { res.json({ data: 'premium content' }) }, ) ``` Key differences: * **Per-route pricing.** `mppx.charge` is route middleware instead of a global config map. * **Amount in dollars, not atomic units.** `'0.01'` instead of `'10000'`. * **No header parsing.** The SDK handles `WWW-Authenticate`, `Authorization`, and `Payment-Receipt` headers automatically. ### Simplify verification and settlement x402 servers typically call a facilitator service for `POST /verify` and `POST /settle`. The `mppx` SDK handles verification and settlement internally, so you don't need a separate facilitator client. ```ts [server.ts] // x402 — external facilitator import { createFacilitator } from '@x402/server' const facilitator = createFacilitator('https://facilitator.x402.org') // MPP — built into the SDK const mppx = Mppx.create({ methods: [tempo({ /* ... */ })], }) ``` ### Add more payment methods This is where MPP goes beyond x402. You can accept stablecoins, cards, and Lightning on the same endpoint by registering additional methods. The `402` response advertises all of them, and the client picks one. ```ts [server.ts] import express from 'express' import Stripe from 'stripe' import { Mppx, tempo, stripe } from 'mppx/express' const app = express() const stripeClient = new Stripe(process.env.STRIPE_SECRET_KEY!) const mppx = Mppx.create({ methods: [ tempo({ currency: '0x20c0000000000000000000000000000000000000', recipient: '0xYourAddress', testnet: true, }), stripe.charge({ // [!code hl] client: stripeClient, // [!code hl] networkId: 'internal', // [!code hl] paymentMethodTypes: ['card'], // [!code hl] }), // [!code hl] ], secretKey: process.env.MPP_SECRET_KEY ?? 'local-dev-secret', }) app.get( '/api/data', mppx.charge({ amount: '0.01', description: 'Premium data access' }), (req, res) => { res.json({ data: 'premium content' }) }, ) ``` No changes to the route handler—`mppx.charge` advertises both methods and verifies whichever Credential the client presents. ### Test via the `mppx` CLI ```bash [terminal] # Create account funded with testnet tokens $ npx mppx account create # Make a paid request $ npx mppx http://localhost:3000/api/data ``` :::: ## What you gain * **Multi-method payments.** Accept stablecoins, cards, and Lightning on the same endpoint—your x402 stablecoin flow continues to work, and new rails are additive. * **Sessions.** Stream sub-cent payments with off-chain vouchers instead of one on-chain transaction per request. * **IETF standards track.** MPP's [Payment HTTP Authentication Scheme](https://paymentauth.org) follows the IETF standards process—building on a standard that browsers, proxies, and CDNs already understand. * **Production primitives.** Idempotency, expiration, request-body binding, and RFC 9457 error responses are built into the protocol. * **Permissionless extensibility.** Anyone can author and publish a new payment method without approval from a foundation. ## Next steps