@x402-iota/server-express

Express middleware for x402 payment gateway on IOTA blockchain.

Overview

Add payment requirements to Express routes with simple configuration.

Installation

npm install @x402-iota/server-express @x402-iota/core

Quick Start

import express from "express";
import { x402Middleware } from "@x402-iota/server-express";

const app = express();

app.use(
  x402Middleware({
    facilitatorUrl: "http://localhost:3001",
    payToAddress: "0x1234567890123456789012345678901234567890",
    network: "iota-evm-testnet",
    asset: "0xFbDa5F676cB37624f28265A144A48B0d6e87d3b6", // USDC
    routes: {
      "/api/protected": {
        amount: "1000000", // 1 USDC
        description: "Access protected API",
      },
      "/api/premium/*": {
        amount: "5000000", // 5 USDC
        description: "Premium content",
      },
    },
  })
);

// Routes
app.get("/api/public", (req, res) => {
  res.json({ message: "Public data" });
});

app.get("/api/protected", (req, res) => {
  // Payment verified automatically by middleware
  const paymentInfo = req.x402;
  console.log("Payment verified:", paymentInfo);
  res.json({ message: "Protected data" });
});

app.listen(3000, () => {
  console.log("Server running on :3000");
});

Configuration

interface X402ExpressOptions {
  facilitatorUrl: string; // Facilitator service URL
  payToAddress: string; // Recipient wallet
  network: Network; // IOTA network
  asset: string; // Token contract address
  routes: Record<string, RouteConfig>; // Protected routes
  onChainVerification?: boolean; // Verify on-chain (default: false)
}

interface RouteConfig {
  amount: string; // Payment amount (atomic units)
  description?: string; // Human-readable description
}

Middleware Flow

Request
   ↓
Check route matches config
   ↓
If matches:
  - Check X-PAYMENT header
  - If missing → Return 402
  - If present → Verify payment
  - If valid → Continue
  - If invalid → Return 402
If doesn't match:
  - Continue (no payment required)

Response Format

Success (200)

{
  data: { ... },
  timestamp: "2025-11-15T..."
}

Payment Required (402)

{
  x402Version: 1,
  accepts: [{
    scheme: 'exact',
    network: 'iota-evm-testnet',
    maxAmountRequired: '1000000',
    resource: '/api/protected',
    description: 'Access protected API',
    mimeType: 'application/json',
    payTo: '0x...',
    maxTimeoutSeconds: 3600,
    asset: '0x...',
    extra: { name: 'USD Coin', version: '2' }
  }]
}

Related Packages

• @x402-iota/core - Core types
• @x402-iota/client - Client SDK
• @x402-iota/server-nextjs - Next.js middleware

License

MIT