mpp-server-middleware
/mpp-server-middleware
Implement MPP server-side middleware for Hono, Express, Next.js, and Elysia. Use when protecting API routes with HTTP 402 payment gates, configuring payment methods, or setting up the Mppx server instance.
- Author
- OrcaQubits ↗
- Repository
- agentic-commerce-skills-plugins ↗
- Licence
- MIT
- Last repository change
- 14.09.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 2
No signals detected. Repository changed on 14.09.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Implement MPP server-side middleware for Hono, Express, Next.js, and Elysia. Use when protecting API routes with HTTP 402 payment gates, configuring payment methods, or setting up the Mppx server instance.
Original author description
Implement MPP server-side middleware for Hono, Express, Next.js, and Elysia. Use when protecting API routes with HTTP 402 payment gates, configuring payment methods, or setting up the Mppx server instance.
How it works
- Before writing code
- Conceptual Architecture
SKILL.md preview
---
name: mpp-server-middleware
description: Implement MPP server-side middleware for Hono, Express, Next.js, and Elysia. Use when protecting API routes with HTTP 402 payment gates, configuring payment methods, or setting up the Mppx server instance.
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch
---
# MPP Server Middleware
## Before writing code
**Fetch live docs**:
1. Fetch `https://www.npmjs.com/package/mppx` for the current server middleware API and configuration options
2. Web-search `mppx server middleware hono express next.js elysia` for framework-specific integration patterns
3. Web-search `site:github.com stripe-samples machine-payments server` for official server sample code
4. Fetch `https://docs.stripe.com/payments/machine/mpp` for Stripe-side server configuration
## Conceptual Architecture
### What the Server Middleware Does
The `mppx` server middleware intercepts requests to protected routes and implements the full HTTP 402 challenge-response flow:
1. **Intercept** — Middleware runs before your route handler
2. **Challenge** — If no `Authorization: Payment` header, returns `402` with `WWW-Authenticate: Payment` challenge
3. **Verify** — If credential present, validates proof of payment (on-chain verification, SPT validation, etc.)
4. **Pass-through** — On successful verification, calls the next handler
5. **Receipt** — Adds `Payment-Receipt` header to the response
### Mppx.create() Configuration
The central factory creates the server instance:
```typescript
const mppx = Mppx.create({
secretKey: process.env.MPP_SECRET_KEY, // 32-byte hex for HMAC challenge binding
methods: [/* payment method configurations */],
});
```
The `secretKey` is critical — it binds challenges to prevent forgery and replay attacks.
### Supported Frameworks
| Framework | Middleware Pattern | Notes |
|-----------|-------------------|-------|
| **Hono** | `app.get('/path', mppx.charge(...), handler)` | Native middleware chaining |
| **Express** | `app.get('/path', mppx.charge(...), handler)` | Standard Express middleware |
| **Next.js** | Route handler wrapping | App Router and Pages Router |
| **Elysia** | Plugin-style integration | Bun-native framework |
### Route Protection
Two middleware functions match the two payment intents:
- **`mppx.charge({ amount })`** — Per-request payment gate (charge intent)
- **`mppx.session({ maxAmount })`** — Session-based streaming payment gate (session intent)
### Amount Specification
- Amounts are strings representing the smallest currency unit
- For USDC: `'100'` = $0.01 (USDC has 6 decimals, so 100 = 0.000100, but convention varies by method)
- For Stripe: follows Stripe's minor-unit convention (cents)
- Always verify exact amount semantics in the SDK docs for your payment method
### Multiple Payment Methods
A single server can accept multiple payment methods simultaneously:
```typescript
const mppx = Mppx.create({
secretKey: process.env.MPP_SECRET_KEY,
methods: [
tempo.charge({ /* Tempo config */ }),
stripe.charge({ /* Stripe config */ }),
],
});
```
The client selects which method to use when fulfilling the challenge.
### Dynamic Pricing
For routes where the price depends on the request:
- Use a pricing function that receives the request and returns the amount
- Implement custom middleware that computes the price and passes it to `mppx.charge()`
### Error Responses
The middleware returns RFC 9457 Problem Details on payment errors:
| Status | Type | When |
|--------|------|------|
| 402 | `payment-required` | No credential provided |
| 402 | `verification-failed` | Invalid proof of payment |
| 402 | `payment-expired` | Challenge or credential expired |
| 402 | `malformed-credential` | Unparseable credential |
### Best Practices
- Always use environment variables for `secretKey`, never hardcode
- Set appropriate challenge expiration times (not too short for UX, not too long for security)
- Log payment verification results (without sensitive data) for debugging
- Implement health check endpoints outside the payment middleware
- Use HTTPS in production (TLS 1.2+ required by spec)
- Add CORS headers if the API is consumed from browsers
Fetch the latest mppx package README for exact middleware API signatures, configuration options, and framework-specific examples before implementing.
Versions
The database has no other skills named mpp-server-middleware.
Database snapshot: 13.11.2026 · package version 25215e942d8a (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100mpp-setup
Scaffold an MPP project — install mppx SDK, configure payment methods, set up server middleware, and create a basic paid API endpoint. Use when starting a new MPP machine payments project from scratch. - 100mpp-client-fetch
Implement MPP client-side payment handling with mppx.fetch(). Use when building AI agents or automated clients that consume 402-protected APIs, handling the transparent challenge-response payment flow. - 100mpp
Build with MPP (Machine Payments Protocol), open machine-to-machine payments over HTTP 402. Use for paid APIs, payment-gated endpoints, agent payment flows, MCP tool payments, or metered billing. Covers mppx (TS), pympp, and mpp Rust SDKs. - 100mppx
TypeScript SDK for the Payment HTTP Authentication Scheme. Handles 402 Payment Required flows with Tempo, Stripe, and other payment methods. Use when integrating payments or mppx into a client or server application. - 100x402-payments
Build applications using the x402 protocol — Coinbase's open standard for HTTP-native stablecoin payments using the HTTP 402 status code. Use this skill when: - Creating APIs that require USDC payments per request (seller/server side) - Building clients or AI agents that pay for… - 100hono-guide
Use when editing or scaffolding Hono 4.0+ API servers in TypeScript. Triggers on `.ts` files with `hono` or `@hono/*` imports, route handlers, middleware, and prompts about validation, error handling, WebSockets, CORS, or building an HTTP API in Hono, even when the user doesn't say 'Hono'.