# Upgrade your x402 server to MPP MPP is easy to add to 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** | `X-PAYMENT-REQUIRED` header | `WWW-Authenticate: Payment` header | | **Credential** | `X-PAYMENT` header | `Authorization: Payment` header | | **Receipt** | `X-PAYMENT-RESPONSE` header | `Payment-Receipt` header | | **Payment methods** | Crypto 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. ::: ## Protocol flow The request lifecycle is the same—only the header names and encoding change. **x402** >Server: GET /resource Server-->>Client: 402 + X-PAYMENT-REQUIRED Client->>Server: GET /resource + X-PAYMENT Server-->>Client: 200 + X-PAYMENT-RESPONSE `} /> **MPP** >Server: GET /resource Server-->>Client: 402 + WWW-Authenticate: Payment Client->>Server: GET /resource + Authorization: Payment Server-->>Client: 200 + Payment-Receipt `} /> ## Prompt mode Paste this into your coding agent to add MPP in one prompt: {`Use https://mpp.dev/guides/upgrade-x402.md as reference. Add mppx to my existing x402 server. Use the Tempo payment method with USDC. Keep the same pricing and route structure. Add mppx.charge to each paid endpoint. Point out areas where I could benefit from adding sessions.`} ## Add MPP to your 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 crypto from 'crypto' import express from 'express' import { Mppx, tempo } from 'mppx/express' // [!code hl] const app = express() const mppx = Mppx.create({ // [!code hl] secretKey: process.env.MPP_SECRET_KEY || crypto.randomBytes(32).toString('base64'), // [!code hl] methods: [ // [!code hl] tempo({ // [!code hl] currency: '0x20c0000000000000000000000000000000000000', // [!code hl] recipient: '0xYourAddress', // [!code hl] }), // [!code hl] ], // [!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 crypto from 'crypto' 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({ secretKey: process.env.MPP_SECRET_KEY || crypto.randomBytes(32).toString('base64'), 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] ], }) 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 ``` :::: ## 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 `X-PAYMENT-REQUIRED`. * **Credential** — The client's signed payment authorization. Sent in the `Authorization: Payment` header. Equivalent to x402's `X-PAYMENT`. * **Receipt** — The server's confirmation that payment settled. Sent in the `Payment-Receipt` header. Equivalent to x402's `X-PAYMENT-RESPONSE`. ## 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