Mpp Dev

MPP (Machine Payments Protocol) Development Guide

MPP is an open, IETF-draft-style HTTP payment standard, co-authored by Stripe and Tempo, that layers a Payment HTTP Authentication Scheme on top of 402 Payment Required so any HTTP client — especially an AI agent — can pay for a resource as part of the request itself, with no pre-provisioned account, API key, or billing relationship. Spec source: github.com/tempoxyz/mpp-specs (published at paymentauth.org). Docs/directory: mpp.dev. TypeScript SDK: mppx on npm (SDKs also exist for Python, Rust, Go, Ruby).

Quick Orientation

Payment Flow:

1. Client requests resource → server returns 402 with WWW-Authenticate: Payment ... (the Challenge)
2. Client fulfills the Challenge (signs, pays, mints) → retries with Authorization: Payment ... (the Credential)
3. Server verifies + settles → returns 200 + Payment-Receipt header (the Receipt)

Always capitalize Challenge, Credential, Receipt as protocol proper nouns in docs/UI copy.

Package Reference

npm i mppx              # TypeScript SDK — client, server, framework middlewares, CLI (package is `mppx`, NOT `mpp` or `@wevm/mppx`)
npm i -g mppx            # also installs the `mppx` CLI (account/session management, curl-like paid requests)

mppx/client       — payment-aware fetch wrapper, hooks, CLI internals
mppx/server       — Mppx.create({ secretKey, methods }), .charge(), .compose()
mppx/express | mppx/hono | mppx/nextjs | mppx/elysia   — framework middlewares + discovery()
mppx/tempo | mppx/evm | mppx/stripe | mppx/x402         — per-method exports

Other official SDKs: tempoxyz/pympp (Python), tempoxyz/mpp-rs (Rust). viem is a required peer dependency for TypeScript client/server code.

Implementation Paths

Choose your path and read the reference file — don't guess wire formats or signing schemes from memory, since this is a fast-moving, brand-new protocol; the reference files below are grounded in the actual spec/SDK source, not general payment-protocol intuition.

Minimal Working Examples

Client — TypeScript

import { Mppx, tempo } from 'mppx/client'
import { privateKeyToAccount } from 'viem/accounts'

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`)
const mppx = Mppx.create({ methods: [tempo({ account })] })

const res = await mppx.fetch('/api/photo')   // transparently handles 402 → sign → retry
const data = await res.json()

Server — Express

import express from 'express'
import { Mppx, tempo } from 'mppx/express'

const app = express()
const mppx = Mppx.create({ methods: [tempo()] })   // reads MPP_SECRET_KEY from env

app.get('/premium', mppx.charge({ amount: '1' }), (req, res) => {
  res.json({ data: 'paid content' })
})

MCP Server — Payment-Gated Tool

import { Mppx, tempo } from 'mppx/server'
import { Transport } from 'mppx'
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'

const mppx = Mppx.create({
  secretKey: process.env.MPP_SECRET_KEY!,
  methods: [tempo.charge({ /* ... */ })],
  transport: Transport.mcpSdk(),
})

const server = new McpServer({ name: 'paid-tools', version: '1.0.0' })

server.tool('get_premium_data', schema, async (params, extra) => {
  const result = await mppx.charge({ amount: '0.01' })(extra)
  if (result.status === 402) throw result.challenge   // -> McpError code -32042
  return result.withReceipt({ content: [{ type: 'text', text: 'premium data' }] })
})

Status Code Cheat Sheet

Cache-Control: no-store is mandatory on every 402; Cache-Control: private is mandatory whenever a Payment-Receipt is present. Full error-code table in [references/protocol-core.md].

Common Issues & Solutions

Environment Variables

# Server
MPP_SECRET_KEY=...             # >=32 bytes; HMAC root for Challenge-id binding — treat like a JWT signing key
WALLET_ADDRESS=0x...           # or Tempo account — recipient of settled funds

# Client
PRIVATE_KEY=0x...              # EVM/Tempo signer (viem Account)

# Stripe method (server-side only)
STRIPE_SECRET_KEY=sk_...
STRIPE_NETWORK_ID=...          # for Shared Payment Token issuance

Reference Files

• [references/protocol-core.md] — Wire protocol: Challenge/Credential/Receipt formats, HTTP status semantics, Challenge-id HMAC binding, error codes, versioning, intents (charge/session/subscription/zero-dollar)
• [references/methods.md] — Per-rail signing schemes: Tempo (TIP-20, gasless, sessions), EVM (Permit2/EIP-3009/tx/hash), Stripe (Shared Payment Tokens), plus pointers for Lightning/Solana/Hedera/Stellar
• [references/client.md] — mppx/client patterns: fetch wrapper, hooks, dual-protocol clients, agent spend limits (access keys), CLI
• [references/server.md] — mppx/server patterns: Express/Hono/Next.js/Elysia middlewares, compose(), discovery, refunds
• [references/mcp-and-discovery.md] — MCP transport binding (_meta fields, -32042/-32043), OpenAPI discovery, MPPScan/MPP Services directory, agent-permissions.json
• [references/security-testing.md] — MPP_SECRET_KEY handling, Challenge-binding review checklist, common protocol mistakes, test conventions and a concrete test checklist
• [references/x402-interop.md] — MPP vs. x402 positioning, dual-protocol evm.charge() pattern, when to use which