x402-miden-middleware

Express and Hono middleware for x402 payment walls on Miden. One line to paywall any route with private ZK payments.

Install

npm install x402-miden-middleware

Quick Start

Express

import express from "express";
import { midenPaywall } from "x402-miden-middleware/express";

const app = express();

// One line — paywall any route
app.use("/api/premium", midenPaywall({
  price: "1000",
  asset: "0xfaucetAccountId",
  recipient: "0xYourMidenAccountId",
  network: "miden:testnet",
  facilitatorUrl: "http://localhost:4402",
}));

app.get("/api/premium/data", (req, res) => {
  // Only reachable after valid payment
  const payment = req.paymentInfo;
  res.json({
    data: "premium content",
    paidBy: payment?.from,
    txId: payment?.transactionId,
  });
});

app.listen(3000);

Hono

import { Hono } from "hono";
import { midenPaywall } from "x402-miden-middleware/hono";

const app = new Hono();

app.use("/api/premium/*", midenPaywall({
  price: "1000",
  asset: "0xfaucetAccountId",
  recipient: "0xYourMidenAccountId",
  network: "miden:testnet",
  facilitatorUrl: "http://localhost:4402",
}));

app.get("/api/premium/data", (c) => {
  const payment = c.get("paymentInfo");
  return c.json({ data: "premium content", paidBy: payment?.from });
});

export default app;

How It Works

Client (AI Agent)              Your Server                  Facilitator
     │                            │                            │
     │─── GET /api/premium ──────▶│                            │
     │                            │                            │
     │◀── 402 Payment Required ──│                            │
     │    { accepts: [{           │                            │
     │      scheme: "exact",      │                            │
     │      network: "miden:testnet",                          │
     │      amount: "1000",       │                            │
     │      asset: "0xfaucet",    │                            │
     │      payTo: "0xrecipient"  │                            │
     │    }] }                    │                            │
     │                            │                            │
     │── Create P2ID payment ────────────────────────────────▶│
     │   (STARK proof, no network submission)                  │
     │                            │                            │
     │─── GET /api/premium ──────▶│                            │
     │    Payment: <base64>       │─── POST /verify ─────────▶│
     │                            │◀── { valid: true } ───────│
     │◀── 200 + Data ───────────│                            │

1. Request without Payment header → middleware returns 402 with payment requirements
2. Client creates a Miden P2ID payment (using x402-miden-agent-sdk)
3. Request with Payment header → middleware verifies via facilitator → passes through

Configuration

Payment Verification

Three modes (in priority order):

1. Custom function — verifyPayment: async (payload) => ({ valid: true })
2. Remote facilitator — facilitatorUrl: "http://localhost:4402" → sends POST to /verify
3. No config — No config → rejects all payments (secure by default). Set facilitatorUrl or verifyPayment to enable verification.

Accessing Payment Info

After successful verification, payment info is available in downstream handlers:

// Express: req.paymentInfo
// Hono: c.get("paymentInfo")

interface PaymentInfo {
  transactionId: string;  // Miden transaction ID
  from: string;           // Sender's account ID
  amount: string;         // Amount paid
  asset: string;          // Token faucet ID
}

Wire Format

The Payment header is a base64-encoded JSON payload compatible with x402-miden-agent-sdk:

{
  "x402Version": 2,
  "accepted": {
    "scheme": "exact",
    "network": "miden:testnet",
    "amount": "1000",
    "payTo": "0xrecipient",
    "asset": "0xfaucet",
    "maxTimeoutSeconds": 300
  },
  "payload": {
    "from": "0xsender",
    "provenTransaction": "hex-encoded-stark-proven-tx",
    "transactionId": "hex-tx-id"
  }
}

Related Packages

• x402-miden-agent-sdk — Client-side: agent wallets + automatic 402 payment
• x402-chain-miden — Rust: Miden settlement layer for x402

License

Apache-2.0