@profullstack/coinpay 0.6.8 → 0.6.10

package/bin/coinpay.js

@@ -2615,6 +2615,10 @@ async function main() {
       case 'reputation':
         await handleReputation(subcommand, args, flags);
         break;
+
+      case 'x402':
+        await handleX402(subcommand, args, flags);
+        break;
         
       default:
         print.error(`Unknown command: ${command}`);
@@ -2630,4 +2634,119 @@ async function main() {
   }
 }
 
+/**
+ * Handle x402 commands
+ */
+async function handleX402(subcommand, args, flags) {
+  const config = loadConfig();
+
+  if (!subcommand) {
+    console.log(`
+${colors.bright}x402 Payment Protocol${colors.reset}
+
+Usage: coinpay x402 <command> [options]
+
+Commands:
+  status          Check x402 facilitator status
+  test            Test x402 flow against an endpoint
+
+Options:
+  --url <url>     Endpoint URL for testing
+  --network <net> Network: base, ethereum, polygon (default: base)
+  --amount <amt>  Amount in USDC smallest unit (default: 1000000 = 1 USDC)
+`);
+    return;
+  }
+
+  switch (subcommand) {
+    case 'status': {
+      const apiKey = flags['api-key'] || config.apiKey;
+      const baseUrl = flags['base-url'] || config.baseUrl || 'https://coinpayportal.com';
+
+      print.info('Checking x402 facilitator status...');
+
+      try {
+        const response = await fetch(`${baseUrl}/api/x402/verify`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            ...(apiKey ? { 'X-API-Key': apiKey } : {}),
+          },
+          body: JSON.stringify({ payment: { test: true } }),
+        });
+
+        if (response.status === 401) {
+          print.error('API key required or invalid. Set with: coinpay config set apiKey <key>');
+        } else if (response.status === 400) {
+          print.success('x402 facilitator is reachable and responding');
+          print.info(`Facilitator URL: ${baseUrl}/api/x402`);
+          print.info('Networks: Base, Ethereum, Polygon (Solana coming soon)');
+        } else {
+          print.warn(`Unexpected response: HTTP ${response.status}`);
+        }
+      } catch (err) {
+        print.error(`Cannot reach facilitator at ${baseUrl}: ${err.message}`);
+      }
+      break;
+    }
+
+    case 'test': {
+      const url = flags.url || args[0];
+      if (!url) {
+        print.error('URL required: coinpay x402 test --url http://localhost:3000/api/premium');
+        return;
+      }
+
+      const network = flags.network || 'base';
+      const amount = flags.amount || '1000000';
+
+      print.info(`Testing x402 flow against ${url}`);
+
+      // Step 1: Request without payment
+      try {
+        print.info('Step 1: Requesting resource without payment...');
+        const response = await fetch(url);
+
+        if (response.status === 402) {
+          const body = await response.json();
+          print.success('Received HTTP 402 Payment Required');
+
+          if (body.x402Version) {
+            print.success(`x402 version: ${body.x402Version}`);
+          }
+
+          if (body.accepts && body.accepts.length > 0) {
+            print.success(`${body.accepts.length} payment method(s) offered:`);
+            for (const accept of body.accepts) {
+              const label = accept.extra?.label || `${accept.asset} on ${accept.network}`;
+              const symbol = accept.extra?.assetSymbol || accept.asset || '';
+              print.info(`  • ${label}`);
+              print.info(`    Amount: ${accept.maxAmountRequired} ${symbol}`);
+              print.info(`    Pay to: ${accept.payTo || 'not specified'}`);
+            }
+            const facilitator = body.accepts[0]?.extra?.facilitator;
+            if (facilitator) {
+              print.info(`  Facilitator: ${facilitator}`);
+            }
+          }
+
+          print.success('x402 endpoint is correctly configured!');
+          print.warn('Note: Full payment test requires a funded wallet. Use the dashboard for end-to-end testing.');
+        } else if (response.status === 200) {
+          print.warn('Endpoint returned 200 OK — no payment required (is x402 middleware active?)');
+        } else {
+          print.warn(`Unexpected status: HTTP ${response.status}`);
+        }
+      } catch (err) {
+        print.error(`Failed to reach ${url}: ${err.message}`);
+      }
+      break;
+    }
+
+    default:
+      print.error(`Unknown x402 command: ${subcommand}`);
+      print.info('Available: status, test');
+  }
+}
+
 main().then(() => process.exit(0));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/coinpay",
-  "version": "0.6.8",
+  "version": "0.6.10",
   "description": "CoinPay SDK & CLI — Accept cryptocurrency payments (BTC, ETH, SOL, POL, BCH, USDC) with wallet and swap support",
   "type": "module",
   "main": "./src/index.js",

package/src/client.js

@@ -3,6 +3,8 @@
  * Main client class for interacting with the CoinPay API
  */
 
+import { LightningClient } from './lightning.js';
+
 const DEFAULT_BASE_URL = 'https://coinpayportal.com/api';
 
 /**
@@ -24,6 +26,9 @@ export class CoinPayClient {
     this.#apiKey = apiKey;
     this.#baseUrl = baseUrl.replace(/\/$/, ''); // Remove trailing slash
     this.#timeout = timeout;
+
+    /** @type {LightningClient} Lightning/BOLT12 operations */
+    this.lightning = new LightningClient(this);
   }
 
   /**

package/src/index.js

@@ -147,6 +147,21 @@ import {
   SubscriptionStatus,
 } from './subscriptions.js';
 
+// Lightning
+import { LightningClient } from './lightning.js';
+
+// x402 Protocol
+import {
+  createX402Middleware,
+  verifyX402Payment,
+  settleX402Payment,
+  buildPaymentRequired,
+  convertUsdToAssetAmount,
+  PAYMENT_METHODS,
+  USDC_CONTRACTS,
+  CHAIN_IDS,
+} from './x402.js';
+
 export {
   // Client
   CoinPayClient,
@@ -235,11 +250,24 @@ export {
   linkDid,
   getMyDid,
   
+  // Lightning
+  LightningClient,
+  
   // Auth
   registerMerchant,
   loginMerchant,
   getMe,
   
+  // x402 Protocol
+  createX402Middleware,
+  verifyX402Payment,
+  settleX402Payment,
+  buildPaymentRequired,
+  convertUsdToAssetAmount,
+  PAYMENT_METHODS,
+  USDC_CONTRACTS,
+  CHAIN_IDS,
+  
   // Webhook utilities
   verifyWebhookSignature,
   generateWebhookSignature,

package/src/lightning.js

@@ -0,0 +1,156 @@
+/**
+ * Lightning Module for CoinPay SDK
+ *
+ * Manages BOLT12 Lightning Network operations: node provisioning,
+ * offer creation, and payment tracking.
+ */
+
+const DEFAULT_BASE_URL = 'https://coinpayportal.com/api';
+
+/**
+ * Lightning client for BOLT12 operations
+ */
+export class LightningClient {
+  #client;
+
+  /**
+   * @param {import('./client.js').CoinPayClient} client - Parent CoinPay client
+   */
+  constructor(client) {
+    this.#client = client;
+  }
+
+  // ──────────────────────────────────────────────
+  // Nodes
+  // ──────────────────────────────────────────────
+
+  /**
+   * Provision a Greenlight CLN node for a wallet.
+   * @param {Object} params
+   * @param {string} params.wallet_id - Wallet UUID
+   * @param {string} params.mnemonic - BIP39 mnemonic (used server-side to derive LN keys)
+   * @param {string} [params.business_id] - Optional business UUID
+   * @returns {Promise<Object>} The provisioned node
+   */
+  async provisionNode({ wallet_id, mnemonic, business_id }) {
+    return this.#client.request('/lightning/nodes', {
+      method: 'POST',
+      body: JSON.stringify({ wallet_id, mnemonic, business_id }),
+    });
+  }
+
+  /**
+   * Get node status by ID.
+   * @param {string} nodeId
+   * @returns {Promise<Object>}
+   */
+  async getNode(nodeId) {
+    return this.#client.request(`/lightning/nodes/${nodeId}`);
+  }
+
+  /**
+   * Get node by wallet ID.
+   * @param {string} walletId - Wallet UUID
+   * @returns {Promise<Object>}
+   */
+  async getNodeByWallet(walletId) {
+    return this.#client.request(`/lightning/nodes?wallet_id=${walletId}`);
+  }
+
+  // ──────────────────────────────────────────────
+  // Offers
+  // ──────────────────────────────────────────────
+
+  /**
+   * Create a BOLT12 offer.
+   * @param {Object} params
+   * @param {string} params.node_id - Node UUID
+   * @param {string} params.description - Human-readable description
+   * @param {number} [params.amount_msat] - Fixed amount in millisatoshis (omit for any-amount)
+   * @param {string} [params.currency] - Currency code (default: "BTC")
+   * @param {string} [params.business_id] - Optional business UUID
+   * @returns {Promise<Object>}
+   */
+  async createOffer({ node_id, description, amount_msat, currency, business_id }) {
+    return this.#client.request('/lightning/offers', {
+      method: 'POST',
+      body: JSON.stringify({ node_id, description, amount_msat, currency, business_id }),
+    });
+  }
+
+  /**
+   * Get offer by ID.
+   * @param {string} offerId
+   * @returns {Promise<Object>} Includes offer and qr_uri
+   */
+  async getOffer(offerId) {
+    return this.#client.request(`/lightning/offers/${offerId}`);
+  }
+
+  /**
+   * List offers with optional filters.
+   * @param {Object} [params]
+   * @param {string} [params.business_id]
+   * @param {string} [params.node_id]
+   * @param {string} [params.status] - "active" | "disabled" | "archived"
+   * @param {number} [params.limit] - Default 20
+   * @param {number} [params.offset] - Default 0
+   * @returns {Promise<Object>} { offers, total, limit, offset }
+   */
+  async listOffers(params = {}) {
+    const qs = new URLSearchParams();
+    for (const [k, v] of Object.entries(params)) {
+      if (v !== undefined && v !== null) qs.set(k, String(v));
+    }
+    return this.#client.request(`/lightning/offers?${qs}`);
+  }
+
+  // ──────────────────────────────────────────────
+  // Payments
+  // ──────────────────────────────────────────────
+
+  /**
+   * List Lightning payments.
+   * @param {Object} [params]
+   * @param {string} [params.business_id]
+   * @param {string} [params.node_id]
+   * @param {string} [params.offer_id]
+   * @param {string} [params.status] - "pending" | "settled" | "failed"
+   * @param {number} [params.limit] - Default 50
+   * @param {number} [params.offset] - Default 0
+   * @returns {Promise<Object>} { payments, total, limit, offset }
+   */
+  async listPayments(params = {}) {
+    const qs = new URLSearchParams();
+    for (const [k, v] of Object.entries(params)) {
+      if (v !== undefined && v !== null) qs.set(k, String(v));
+    }
+    return this.#client.request(`/lightning/payments?${qs}`);
+  }
+
+  /**
+   * Send a payment to a BOLT12 offer or invoice.
+   * @param {Object} params
+   * @param {string} params.node_id - Node UUID
+   * @param {string} params.bolt12 - BOLT12 offer or invoice string
+   * @param {number} params.amount_sats - Amount in satoshis
+   * @returns {Promise<Object>}
+   */
+  async sendPayment({ node_id, bolt12, amount_sats }) {
+    return this.#client.request('/lightning/payments', {
+      method: 'POST',
+      body: JSON.stringify({ node_id, bolt12, amount_sats }),
+    });
+  }
+
+  /**
+   * Get payment status by payment hash.
+   * @param {string} paymentHash
+   * @returns {Promise<Object>}
+   */
+  async getPayment(paymentHash) {
+    return this.#client.request(`/lightning/payments/${paymentHash}`);
+  }
+}
+
+export default LightningClient;

package/src/x402.js

@@ -0,0 +1,585 @@
+/**
+ * x402 Payment Protocol Support
+ * 
+ * CoinPayPortal as the first multi-chain, multi-asset x402 facilitator.
+ * Supports native crypto (BTC, ETH, SOL, POL, BCH), USDC stablecoins,
+ * Lightning (BOLT12), and Stripe fiat — all via HTTP 402.
+ * 
+ * @module x402
+ */
+
+/**
+ * All supported payment methods with their network/asset metadata.
+ * 
+ * Each entry defines a scheme the facilitator can advertise in the
+ * 402 `accepts` array, letting the buyer choose their preferred method.
+ */
+export const PAYMENT_METHODS = {
+  // ── Native crypto ──────────────────────────────────────────────
+  btc: {
+    network: 'bitcoin',
+    asset: 'BTC',
+    scheme: 'exact',
+    decimals: 8,
+    label: 'Bitcoin',
+  },
+  bch: {
+    network: 'bitcoin-cash',
+    asset: 'BCH',
+    scheme: 'exact',
+    decimals: 8,
+    label: 'Bitcoin Cash',
+  },
+  eth: {
+    network: 'ethereum',
+    asset: 'ETH',
+    scheme: 'exact',
+    decimals: 18,
+    chainId: 1,
+    label: 'Ethereum',
+  },
+  pol: {
+    network: 'polygon',
+    asset: 'POL',
+    scheme: 'exact',
+    decimals: 18,
+    chainId: 137,
+    label: 'Polygon',
+  },
+  sol: {
+    network: 'solana',
+    asset: 'SOL',
+    scheme: 'exact',
+    decimals: 9,
+    label: 'Solana',
+  },
+
+  // ── USDC stablecoins ──────────────────────────────────────────
+  usdc_eth: {
+    network: 'ethereum',
+    asset: 'USDC',
+    scheme: 'exact',
+    decimals: 6,
+    chainId: 1,
+    contractAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+    label: 'USDC on Ethereum',
+  },
+  usdc_polygon: {
+    network: 'polygon',
+    asset: 'USDC',
+    scheme: 'exact',
+    decimals: 6,
+    chainId: 137,
+    contractAddress: '0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359',
+    label: 'USDC on Polygon',
+  },
+  usdc_solana: {
+    network: 'solana',
+    asset: 'USDC',
+    scheme: 'exact',
+    decimals: 6,
+    contractAddress: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+    label: 'USDC on Solana',
+  },
+  usdc_base: {
+    network: 'base',
+    asset: 'USDC',
+    scheme: 'exact',
+    decimals: 6,
+    chainId: 8453,
+    contractAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+    label: 'USDC on Base',
+  },
+
+  // ── Lightning ──────────────────────────────────────────────────
+  lightning: {
+    network: 'lightning',
+    asset: 'BTC',
+    scheme: 'bolt12',
+    decimals: 0, // sats
+    label: 'Lightning (BOLT12)',
+  },
+
+  // ── Fiat via Stripe ────────────────────────────────────────────
+  stripe: {
+    network: 'stripe',
+    asset: 'USD',
+    scheme: 'stripe-checkout',
+    decimals: 2,
+    label: 'Card (Stripe)',
+  },
+};
+
+/**
+ * USDC contract addresses by network (convenience re-export)
+ */
+export const USDC_CONTRACTS = {
+  base: PAYMENT_METHODS.usdc_base.contractAddress,
+  ethereum: PAYMENT_METHODS.usdc_eth.contractAddress,
+  polygon: PAYMENT_METHODS.usdc_polygon.contractAddress,
+  solana: PAYMENT_METHODS.usdc_solana.contractAddress,
+};
+
+/**
+ * Chain IDs for EVM networks
+ */
+export const CHAIN_IDS = {
+  base: 8453,
+  ethereum: 1,
+  polygon: 137,
+};
+
+/**
+ * Default facilitator URL
+ */
+const DEFAULT_FACILITATOR_URL = 'https://coinpayportal.com/api/x402';
+
+/**
+ * x402 protocol version
+ */
+const X402_VERSION = 1;
+
+/**
+ * All payment method keys
+ */
+const ALL_METHOD_KEYS = Object.keys(PAYMENT_METHODS);
+
+/**
+ * Convert a fiat amount (USD cents or dollars) to the smallest unit for a
+ * given payment method, using a rates lookup.
+ * 
+ * @param {number} amountUsd - Amount in USD (e.g. 1.00)
+ * @param {string} methodKey - Key from PAYMENT_METHODS
+ * @param {Object} rates - Map of asset→USD rate (e.g. { BTC: 65000, ETH: 3500 })
+ * @returns {string} Amount in the asset's smallest unit
+ */
+export function convertUsdToAssetAmount(amountUsd, methodKey, rates = {}) {
+  const method = PAYMENT_METHODS[methodKey];
+  if (!method) throw new Error(`Unknown payment method: ${methodKey}`);
+
+  if (method.asset === 'USD') {
+    // Stripe: amount in cents
+    return String(Math.round(amountUsd * 100));
+  }
+  if (method.asset === 'USDC') {
+    // USDC: 6 decimals, 1:1 with USD
+    return String(Math.round(amountUsd * 1e6));
+  }
+
+  const rate = rates[method.asset];
+  if (!rate) throw new Error(`No exchange rate for ${method.asset}`);
+
+  const assetAmount = amountUsd / rate;
+  const smallest = Math.round(assetAmount * Math.pow(10, method.decimals));
+  return String(smallest);
+}
+
+/**
+ * Build a single `accepts` entry for a payment method.
+ */
+function buildAcceptEntry(methodKey, { payTo, amount, resource, description, mimeType, maxTimeoutSeconds, facilitatorUrl }) {
+  const method = PAYMENT_METHODS[methodKey];
+  if (!method) throw new Error(`Unknown payment method: ${methodKey}`);
+
+  const entry = {
+    scheme: method.scheme,
+    network: method.network,
+    asset: method.contractAddress || method.asset,
+    maxAmountRequired: String(amount),
+    resource: resource || '',
+    description: description || 'Payment required',
+    mimeType: mimeType || 'application/json',
+    payTo,
+    maxTimeoutSeconds: maxTimeoutSeconds || 300,
+    extra: {
+      facilitator: facilitatorUrl || DEFAULT_FACILITATOR_URL,
+      methodKey,
+      assetSymbol: method.asset,
+      label: method.label,
+    },
+  };
+
+  if (method.chainId) {
+    entry.extra.chainId = method.chainId;
+  }
+
+  return entry;
+}
+
+/**
+ * Build a 402 response payload advertising multiple payment options.
+ * 
+ * This is CoinPayPortal's key differentiator: the `accepts` array includes
+ * every supported chain and asset, letting the buyer choose.
+ * 
+ * @param {Object} options
+ * @param {string} options.payTo - Merchant wallet address (or object mapping network→address)
+ * @param {number} options.amountUsd - Price in USD
+ * @param {Object} [options.rates] - Exchange rates { BTC: 65000, ETH: 3500, ... }
+ * @param {string[]} [options.methods] - Payment method keys to include (default: all)
+ * @param {string} [options.resource] - Resource URL
+ * @param {string} [options.description] - Human-readable description
+ * @param {string} [options.mimeType='application/json'] - Response MIME type
+ * @param {number} [options.maxTimeoutSeconds=300] - Payment timeout
+ * @param {string} [options.facilitatorUrl] - Custom facilitator URL
+ * @returns {Object} x402 payment required response body
+ * 
+ * @example
+ * // Advertise all methods
+ * const body = buildPaymentRequired({
+ *   payTo: { ethereum: '0x...', bitcoin: 'bc1...', solana: 'So1...' },
+ *   amountUsd: 5.00,
+ *   rates: { BTC: 65000, ETH: 3500, SOL: 150, POL: 0.50, BCH: 350 },
+ * });
+ * 
+ * @example
+ * // Only accept USDC and Lightning
+ * const body = buildPaymentRequired({
+ *   payTo: '0xMyWallet',
+ *   amountUsd: 1.00,
+ *   methods: ['usdc_eth', 'usdc_polygon', 'usdc_base', 'lightning'],
+ * });
+ */
+export function buildPaymentRequired(options) {
+  const {
+    payTo,
+    amountUsd,
+    amount,        // legacy: raw amount for a single method
+    network,       // legacy: single network
+    rates = {},
+    methods,
+    resource,
+    description = 'Payment required',
+    mimeType = 'application/json',
+    maxTimeoutSeconds = 300,
+    facilitatorUrl = DEFAULT_FACILITATOR_URL,
+  } = options;
+
+  // Legacy single-method mode (backwards compatible)
+  if (network && amount && !methods) {
+    const methodKey = _networkToMethodKey(network);
+    const addr = typeof payTo === 'object' ? (payTo[network] || Object.values(payTo)[0]) : payTo;
+    return {
+      x402Version: X402_VERSION,
+      accepts: [buildAcceptEntry(methodKey, {
+        payTo: addr, amount, resource, description, mimeType, maxTimeoutSeconds, facilitatorUrl,
+      })],
+    };
+  }
+
+  // Multi-method mode
+  const methodKeys = methods || ALL_METHOD_KEYS;
+  const accepts = [];
+
+  for (const key of methodKeys) {
+    const method = PAYMENT_METHODS[key];
+    if (!method) continue;
+
+    // Resolve pay-to address for this network
+    let addr;
+    if (typeof payTo === 'object') {
+      addr = payTo[method.network] || payTo[key];
+    } else {
+      addr = payTo;
+    }
+    if (!addr) continue; // skip methods where merchant has no address
+
+    // Convert USD to asset amount
+    let assetAmount;
+    try {
+      if (amountUsd != null) {
+        assetAmount = convertUsdToAssetAmount(amountUsd, key, rates);
+      } else if (amount) {
+        assetAmount = String(amount);
+      } else {
+        continue;
+      }
+    } catch {
+      // No rate available for this asset — skip it
+      continue;
+    }
+
+    accepts.push(buildAcceptEntry(key, {
+      payTo: addr, amount: assetAmount, resource, description, mimeType, maxTimeoutSeconds, facilitatorUrl,
+    }));
+  }
+
+  if (accepts.length === 0) {
+    throw new Error('No payment methods could be built. Check payTo addresses and rates.');
+  }
+
+  return {
+    x402Version: X402_VERSION,
+    accepts,
+  };
+}
+
+/**
+ * Map a simple network name to the best-guess method key (legacy compat).
+ */
+function _networkToMethodKey(network) {
+  const map = {
+    base: 'usdc_base',
+    ethereum: 'eth',
+    polygon: 'pol',
+    solana: 'sol',
+    bitcoin: 'btc',
+    'bitcoin-cash': 'bch',
+    lightning: 'lightning',
+    stripe: 'stripe',
+  };
+  return map[network] || network;
+}
+
+/**
+ * Create Express/Next.js middleware that gates routes behind x402 payments.
+ * 
+ * Returns a function that accepts per-route options and returns middleware.
+ * The 402 response advertises ALL supported payment methods by default.
+ * 
+ * @param {Object} globalOptions
+ * @param {string} globalOptions.apiKey - CoinPayPortal API key
+ * @param {string|Object} globalOptions.payTo - Wallet address(es): string or { network: address }
+ * @param {string[]} [globalOptions.methods] - Payment methods to accept (default: all with addresses)
+ * @param {Object} [globalOptions.rates] - Exchange rates { BTC: 65000, ... }
+ * @param {string} [globalOptions.ratesEndpoint] - URL to fetch live rates (polled periodically)
+ * @param {string} [globalOptions.description='Payment required'] - Default description
+ * @param {string} [globalOptions.facilitatorUrl] - Custom facilitator URL
+ * @param {string} [globalOptions.apiBaseUrl='https://coinpayportal.com'] - CoinPayPortal API base
+ * @returns {Function} Middleware factory: (routeOptions) => middleware
+ * 
+ * @example
+ * const x402 = createX402Middleware({
+ *   apiKey: 'cp_live_xxxxx',
+ *   payTo: {
+ *     ethereum: '0xAbC...',
+ *     bitcoin: 'bc1q...',
+ *     solana: 'So1...',
+ *     lightning: 'lno1...',
+ *     stripe: 'acct_xxx',
+ *   },
+ *   rates: { BTC: 65000, ETH: 3500, SOL: 150, POL: 0.50, BCH: 350 },
+ * });
+ * 
+ * // Charge $5 for premium access — buyer picks their chain
+ * app.get('/premium', x402({ amountUsd: 5.00 }), handler);
+ */
+export function createX402Middleware(globalOptions) {
+  const {
+    apiKey,
+    payTo,
+    methods,
+    rates = {},
+    description = 'Payment required',
+    facilitatorUrl = DEFAULT_FACILITATOR_URL,
+    apiBaseUrl = 'https://coinpayportal.com',
+  } = globalOptions;
+
+  if (!apiKey) throw new Error('x402 middleware requires an apiKey');
+  if (!payTo) throw new Error('x402 middleware requires a payTo address');
+
+  // Mutable rates cache — can be updated externally or via ratesEndpoint
+  let currentRates = { ...rates };
+
+  // If ratesEndpoint provided, poll for fresh rates
+  if (globalOptions.ratesEndpoint) {
+    const fetchRates = async () => {
+      try {
+        const res = await fetch(globalOptions.ratesEndpoint);
+        if (res.ok) currentRates = await res.json();
+      } catch { /* ignore */ }
+    };
+    fetchRates();
+    setInterval(fetchRates, 60_000); // refresh every 60s
+  }
+
+  /**
+   * Route-level middleware factory.
+   * 
+   * @param {Object} routeOptions
+   * @param {number} [routeOptions.amountUsd] - Price in USD (preferred)
+   * @param {string} [routeOptions.amount] - Raw amount (legacy, single-method)
+   * @param {string} [routeOptions.network] - Single network (legacy)
+   * @param {string[]} [routeOptions.methods] - Override accepted methods for this route
+   * @param {string} [routeOptions.description] - Route-specific description
+   */
+  return function x402Route(routeOptions = {}) {
+    const routeAmountUsd = routeOptions.amountUsd;
+    const routeAmount = routeOptions.amount;
+    const routeDescription = routeOptions.description || description;
+    const routeMethods = routeOptions.methods || methods;
+
+    if (!routeAmountUsd && !routeAmount) {
+      throw new Error('x402 route requires amountUsd or amount');
+    }
+
+    return async function x402Middleware(req, res, next) {
+      const paymentHeader = req.headers['x-payment'] || req.headers['X-Payment'];
+
+      if (!paymentHeader) {
+        const resource = `${req.protocol}://${req.get('host')}${req.originalUrl}`;
+        try {
+          const body = buildPaymentRequired({
+            payTo,
+            amountUsd: routeAmountUsd,
+            amount: routeAmount,
+            network: routeOptions.network,
+            rates: currentRates,
+            methods: routeMethods,
+            resource,
+            description: routeDescription,
+            facilitatorUrl,
+          });
+          return res.status(402).json(body);
+        } catch (err) {
+          return res.status(500).json({ error: 'Failed to build payment options', details: err.message });
+        }
+      }
+
+      // Verify the payment
+      try {
+        const result = await verifyX402Payment(paymentHeader, {
+          apiKey,
+          apiBaseUrl,
+        });
+
+        if (!result.valid) {
+          return res.status(402).json({
+            error: 'Invalid payment proof',
+            details: result.reason,
+          });
+        }
+
+        // Attach payment info to request for downstream use
+        req.x402Payment = result.payment;
+        next();
+      } catch (err) {
+        return res.status(500).json({ error: 'Payment verification failed', details: err.message });
+      }
+    };
+  };
+}
+
+/**
+ * Verify an x402 payment proof.
+ * 
+ * Calls CoinPayPortal's facilitator API to validate the cryptographic
+ * signature and payment details in the X-PAYMENT header.
+ * Supports all payment schemes: EVM signatures, BTC/BCH tx proofs,
+ * Solana tx proofs, Lightning preimages, and Stripe payment intents.
+ * 
+ * @param {string} paymentHeader - The X-PAYMENT header value (base64-encoded JSON)
+ * @param {Object} options
+ * @param {string} options.apiKey - CoinPayPortal API key
+ * @param {string} [options.apiBaseUrl='https://coinpayportal.com'] - API base URL
+ * @returns {Promise<{valid: boolean, payment?: Object, reason?: string}>}
+ */
+export async function verifyX402Payment(paymentHeader, options = {}) {
+  const { apiKey, apiBaseUrl = 'https://coinpayportal.com' } = options;
+
+  if (!paymentHeader) {
+    return { valid: false, reason: 'Missing payment header' };
+  }
+
+  // Decode the payment header
+  let payment;
+  try {
+    const decoded = Buffer.from(paymentHeader, 'base64').toString('utf-8');
+    payment = JSON.parse(decoded);
+  } catch {
+    return { valid: false, reason: 'Invalid payment header encoding' };
+  }
+
+  // Validate required fields
+  if (!payment.scheme && !payment.signature && !payment.payload) {
+    return { valid: false, reason: 'Missing scheme, signature, or payload in payment proof' };
+  }
+
+  // Check expiry if present
+  if (payment.payload?.expiresAt) {
+    const expiresAt = typeof payment.payload.expiresAt === 'number'
+      ? new Date(payment.payload.expiresAt * 1000)
+      : new Date(payment.payload.expiresAt);
+    if (expiresAt < new Date()) {
+      return { valid: false, reason: 'Payment proof has expired' };
+    }
+  }
+
+  // Call CoinPayPortal facilitator to verify
+  try {
+    const response = await fetch(`${apiBaseUrl}/api/x402/verify`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        ...(apiKey ? { 'X-API-Key': apiKey } : {}),
+      },
+      body: JSON.stringify({ payment }),
+    });
+
+    const data = await response.json();
+
+    if (!response.ok) {
+      return { valid: false, reason: data.error || 'Verification failed' };
+    }
+
+    return { valid: true, payment: data.payment };
+  } catch (err) {
+    return { valid: false, reason: `Facilitator error: ${err.message}` };
+  }
+}
+
+/**
+ * Settle an x402 payment on-chain (or via the appropriate payment rail).
+ * 
+ * For crypto: claims the payment on-chain.
+ * For Lightning: confirms the preimage.
+ * For Stripe: captures the payment intent.
+ * 
+ * @param {string} paymentHeader - The X-PAYMENT header value (base64-encoded JSON)
+ * @param {Object} options
+ * @param {string} options.apiKey - CoinPayPortal API key
+ * @param {string} [options.apiBaseUrl='https://coinpayportal.com'] - API base URL
+ * @returns {Promise<{settled: boolean, txHash?: string, network?: string, error?: string}>}
+ */
+export async function settleX402Payment(paymentHeader, options = {}) {
+  const { apiKey, apiBaseUrl = 'https://coinpayportal.com' } = options;
+
+  if (!paymentHeader) {
+    return { settled: false, error: 'Missing payment header' };
+  }
+
+  let payment;
+  try {
+    const decoded = Buffer.from(paymentHeader, 'base64').toString('utf-8');
+    payment = JSON.parse(decoded);
+  } catch {
+    return { settled: false, error: 'Invalid payment header encoding' };
+  }
+
+  try {
+    const response = await fetch(`${apiBaseUrl}/api/x402/settle`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        ...(apiKey ? { 'X-API-Key': apiKey } : {}),
+      },
+      body: JSON.stringify({ payment }),
+    });
+
+    const data = await response.json();
+
+    if (!response.ok) {
+      return { settled: false, error: data.error || 'Settlement failed' };
+    }
+
+    return {
+      settled: true,
+      txHash: data.txHash,
+      network: data.network,
+      asset: data.asset,
+      method: data.method,
+    };
+  } catch (err) {
+    return { settled: false, error: `Settlement error: ${err.message}` };
+  }
+}