Skip to content

0xGizmolab/mpp-starter

BranchesTags

Repository files navigation

MPP Examples — Machine Payments Protocol Starter Kit

License: MIT MPP Tempo Stripe

Production-ready examples for integrating payment-gated APIs using the Machine Payments Protocol (MPP) across 11 JavaScript frameworks.

MPP is the open standard for machine-to-machine payments via HTTP 402 — co-developed by Tempo Labs and Stripe.

🌐 What is MPP?

The Machine Payments Protocol enables APIs to charge for access in the same HTTP request — no API keys, no subscriptions, no billing accounts. When a client requests a protected resource:

  1. Server returns 402 Payment Required with payment options
  2. Client pays (stablecoins, cards, or Bitcoin)
  3. Client retries with payment proof
  4. Server delivers the resource with a receipt
Client ──GET /resource──▶ Server
       ◀──402 + Challenge──
       ──pays via Tempo/Stripe──
       ──GET + Credential──▶
       ◀──200 + Receipt──

Why MPP?

Problem MPP Solution
API keys leak and get abused Pay per request — no keys needed
Subscriptions waste money on unused quota Pay only for what you use
Billing disputes and chargebacks Cryptographic receipts prove delivery
Agent onboarding friction Zero signup — just pay and go

⚡ Who Built This?

MPP was co-developed by:

  • Tempo Labs — Built the Tempo blockchain for stablecoin payments at scale. Incubated by Paradigm and Stripe.
  • Stripe — Card payments integration via Shared Payment Tokens.
  • Wevm — Maintains the official mppx SDK.

The protocol is submitted to the IETF for standardization: paymentauth.org

💳 Payment Methods

MPP supports multiple payment rails:

Method Description Use Case
Tempo Stablecoin payments (USDC, pathUSD) on Tempo blockchain High-frequency API calls, AI agents
Stripe Cards, Apple Pay, Google Pay via Shared Payment Tokens Traditional payments, web apps
Lightning Bitcoin over Lightning Network (BOLT11) Crypto-native apps
Custom Build your own payment method Any payment rail

Payment Intents

Intent Description Latency Cost
Charge One-time payment per request ~600ms (on-chain) Per-tx fees
Session Pay-as-you-go via payment channels ~10ms (off-chain) Near-zero

Sessions enable streaming payments for LLM APIs — pay per token with microsecond verification.

🔗 The Tempo Blockchain

Tempo is a purpose-built blockchain for stablecoin payments:

  • ~0.6s finality — Deterministic settlement, no re-orgs
  • Stablecoin-native gas — Pay fees in USD, not volatile tokens
  • Payment lanes — Guaranteed blockspace for payments
  • Payment channels — Off-chain sessions for high-throughput billing
  • Smart accounts — Passkey auth, batch transactions, gas sponsorship

Supported Currencies

Token Address Description
pathUSD 0x20c0...0000 Tempo's native USD stablecoin
USDC Bridge address Circle's USDC (bridged)

🛠 Framework Examples

Server Frameworks (7)

Framework Version Port Integration Middleware
Next.js 16.2 3000 Official mppx/nextjs
Hono 4.12.8 3001 Official mppx/hono
Elysia 1.4.28 3002 Official mppx/elysia
Express 5.2.1 3003 Official mppx/express
Fastify 5.8.2 3004 Manual Custom preHandler
Koa 3.1.2 3005 Manual Custom middleware
NestJS 11.1.17 3006 Manual Guard

Session Example (Pay-as-you-go)

Framework Version Port Description
Hono Session 4.12.8 3008 Payment channels for high-throughput billing

Serverless / Edge (4)

Platform Description Deployment
Cloudflare Workers Edge compute wrangler deploy
Vercel Edge Edge functions vercel --prod
AWS Lambda Classic serverless SAM/CDK
Deno Deploy Deno runtime deployctl

🚀 Quick Start

1. Get a Tempo Wallet (for paying)

Option A: No-code (Browser)

  1. Go to wallet.tempo.xyz
  2. Create wallet with passkey (Face ID / fingerprint)
  3. Fund with testnet tokens
  4. Done — use the web wallet to pay for APIs

Option B: CLI (for developers/agents)

# Install the Tempo CLI
curl -L https://tempo.xyz/install | bash

# Create a wallet (opens browser for passkey auth)
tempo wallet login

# Fund your wallet with testnet tokens
tempo wallet fund

# Check your balance
tempo wallet balance

2. Clone & Run Examples

# Clone the repo
git clone https://github.com/0xGizmolab/mpp-starter.git
cd mpp-starter

# Install dependencies
pnpm install

# Run all tests
pnpm test

# Start a specific example
pnpm dev:nextjs   # or dev:hono, dev:elysia, etc.

3. Test Payment Flow

# Without payment — returns 402
curl http://localhost:3000/api/paid
# → 402 Payment Required + WWW-Authenticate header

# With Tempo CLI — handles payment automatically
tempo request http://localhost:3000/api/paid
# → { "message": "Premium content unlocked!" }

# Preview cost without paying
tempo request --dry-run http://localhost:3000/api/paid

Alternative: Use npx (no install)

# Create account and make paid request
npx mppx account create
npx mppx http://localhost:3000/api/paid

📡 API Endpoints

Every example exposes the same three endpoints:

Endpoint Auth Response
GET /health None { status: "ok", framework: "...", version: "..." }
GET /free None { message: "This is free!", timestamp: ... }
GET /paid MPP { message: "Premium content unlocked!", timestamp: ... }

🔧 Configuration

Each package has its own mpp-config.ts and .env.example:

// packages/*/src/mpp-config.ts
export const mppConfig = {
  recipient: process.env.MPP_RECIPIENT || '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
  currency: process.env.MPP_CURRENCY || '0x20c0000000000000000000000000000000000000',
  amount: process.env.MPP_AMOUNT || '0.01',
  waitForConfirmation: process.env.MPP_WAIT_FOR_CONFIRMATION !== 'false',
}
Variable Description Default
MPP_RECIPIENT Your wallet address Test wallet
MPP_CURRENCY Token contract (pathUSD) Tempo pathUSD
MPP_AMOUNT Charge per request 0.01
MPP_WAIT_FOR_CONFIRMATION Wait for on-chain finality true

📦 Integration Examples

Official Middleware (Next.js, Hono, Elysia, Express)

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

const mppx = Mppx.create({
  methods: [
    tempo({
      recipient: '0xYourWallet...',
      currency: '0x20c0000000000000000000000000000000000000',
      decimals: 6,
    }),
  ],
})

// Protect any route with a single wrapper
export const GET = mppx.charge({ amount: '0.01' })(() =>
  Response.json({ message: 'Premium content!' })
)

Manual Integration (Fastify, Koa, NestJS)

// Fastify preHandler example
app.get('/paid', {
  preHandler: async (request, reply) => {
    const auth = request.headers.authorization
    if (!auth?.startsWith('MPP ')) {
      reply.code(402).header(
        'WWW-Authenticate',
        `MPP realm="api", method="tempo", params="recipient=${config.recipient},..."`
      ).send({ error: 'Payment required' })
    }
  },
}, async () => ({ message: 'Premium content!' }))

Stripe Integration

import Stripe from 'stripe'
import { Mppx, stripe } from 'mppx/server'

const mppx = Mppx.create({
  methods: [
    stripe.charge({
      client: new Stripe(process.env.STRIPE_SECRET_KEY!),
      paymentMethodTypes: ['card'],
    }),
  ],
})

Session-Based Billing (Pay-as-you-go)

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

const mppx = Mppx.create({
  methods: [
    tempo.session({
      recipient: '0xYourWallet...',
      currency: '0x20c0...',
    }),
  ],
})

// Client opens a payment channel, signs vouchers per request
// Server verifies in microseconds — no on-chain calls

🌍 MPP Services Ecosystem

30+ services already accept MPP payments:

Service Category Description
OpenAI AI GPT-4, embeddings, DALL-E
Anthropic AI Claude Sonnet, Opus, Haiku
Google Gemini AI Gemini, Veo video, image gen
fal.ai Media 600+ image/video models
Firecrawl Web Web scraping for LLMs
Exa Search AI-powered web search
Browserbase Web Headless browser sessions
Alchemy Blockchain 100+ chain data APIs
Dune Blockchain SQL queries on-chain data
Allium Blockchain Real-time blockchain data

Full list: mpp.dev/services

🧪 Testing

# Run all 49 tests across 11 packages
pnpm test

# Watch mode
pnpm test:watch

# Single package
cd packages/nextjs && pnpm test

📂 Project Structure

mpp-starter/
├── packages/
│   ├── nextjs/          # Next.js 16.2 (App Router)
│   ├── hono/            # Hono 4.12.8 (charge)
│   ├── hono-session/    # Hono 4.12.8 (sessions)
│   ├── elysia/          # Elysia 1.4.28 (Bun)
│   ├── express/         # Express 5.2.1
│   ├── fastify/         # Fastify 5.8.2
│   ├── koa/             # Koa 3.1.2
│   ├── nestjs/          # NestJS 11.1.17
│   ├── cloudflare-workers/
│   ├── vercel-edge/
│   ├── aws-lambda/
│   └── deno-deploy/
├── package.json
├── pnpm-workspace.yaml
└── vitest.workspace.ts

📚 Learn More

Resource Link
MPP Documentation mpp.dev/docs
Protocol Specification paymentauth.org
Tempo Blockchain tempo.xyz
Tempo Web Wallet wallet.tempo.xyz
Tempo CLI tempo.xyz/install
Services Directory mpp.dev/services
LLM Context mpp.dev/llms-full.txt

🤝 Contributing

  1. Fork the repo
  2. Create a feature branch
  3. Make your changes
  4. Run tests: pnpm test
  5. Submit a PR

🚀 Need Help Enabling Agentic Payments?

Want to integrate MPP into your API or product? We can help.

→ Contact GizmoLab

We'll get you set up with payment-gated endpoints, sessions, and everything you need to monetize your API for AI agents.

📄 License

MIT © GizmoLab

🏷 Keywords

mpp machine-payments-protocol http-402 payment-gated-api tempo stripe stablecoin usdc api-monetization micropayments pay-per-request ai-agents llm-payments web3 blockchain nextjs hono express fastify elysia nestjs serverless edge-functions

About

Next.js • Hono • Express • Fastify • Elysia • NestJS • Cloudflare Workers • Vercel Edge • AWS Lambda • Deno + Session examples for pay-as-you-go billing

gizmolab.io

Topics

ai mpp agents agentic-payments

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages