@profullstack/coinpay 0.6.7 → 0.6.10

package/bin/coinpay.js

@@ -119,6 +119,13 @@ function createClient() {
   return new CoinPayClient({ apiKey, baseUrl: getBaseUrl() });
 }
 
+/**
+ * Create unauthenticated client for auth operations
+ */
+function createUnauthenticatedClient() {
+  return new CoinPayClient({ baseUrl: getBaseUrl() });
+}
+
 /**
  * Parse command line arguments
  */
@@ -171,6 +178,11 @@ ${colors.cyan}Commands:${colors.reset}
     set-url <base-url>    Set custom API URL
     show                  Show current configuration
 
+  ${colors.bright}auth${colors.reset}
+    register              Register new merchant account
+    login                 Login to merchant account
+    me                    Show current merchant info
+
   ${colors.bright}payment${colors.reset}
     create                Create a new payment
     get <id>              Get payment details
@@ -241,6 +253,8 @@ ${colors.cyan}Commands:${colors.reset}
     badge [did]           Get embeddable reputation badge URL
     verify <id>           Verify a credential
     revocations           List revoked credentials
+    did claim             Claim (auto-generate) a new DID
+    did me                Show your current DID
     issuer register       Register platform issuer (--name, --domain)
     issuer list           List your platform issuers
     issuer rotate         Rotate issuer API key (--id)
@@ -1715,6 +1729,136 @@ async function handleEscrow(subcommand, args, flags) {
   }
 }
 
+/**
+ * Auth commands
+ */
+async function handleAuth(subcommand, args, flags) {
+  const config = loadConfig();
+  
+  switch (subcommand) {
+    case 'register': {
+      const email = flags.email;
+      const password = flags.password;
+      const name = flags.name;
+      
+      if (!email || !password) {
+        print.error('Required: --email <email> --password <password>');
+        print.info('Example: coinpay auth register --email user@example.com --password mysecret --name "My Company"');
+        return;
+      }
+      
+      try {
+        const client = createUnauthenticatedClient();
+        const { registerMerchant } = await import('../src/auth.js');
+        const result = await registerMerchant(client, { email, password, name });
+        
+        if (result.success) {
+          // Store the JWT token in config
+          config.jwtToken = result.token;
+          saveConfig(config);
+          
+          print.success('Registration successful!');
+          print.info(`Merchant ID: ${result.merchant.id}`);
+          print.info(`Email: ${result.merchant.email}`);
+          if (result.merchant.name) {
+            print.info(`Name: ${result.merchant.name}`);
+          }
+          print.success('JWT token saved to config');
+        } else {
+          print.error(result.error || 'Registration failed');
+        }
+        
+        if (flags.json) {
+          print.json(result);
+        }
+      } catch (error) {
+        print.error(error.message);
+      }
+      break;
+    }
+    
+    case 'login': {
+      const email = flags.email;
+      const password = flags.password;
+      
+      if (!email || !password) {
+        print.error('Required: --email <email> --password <password>');
+        print.info('Example: coinpay auth login --email user@example.com --password mysecret');
+        return;
+      }
+      
+      try {
+        const client = createUnauthenticatedClient();
+        const { loginMerchant } = await import('../src/auth.js');
+        const result = await loginMerchant(client, { email, password });
+        
+        if (result.success) {
+          // Store the JWT token in config
+          config.jwtToken = result.token;
+          saveConfig(config);
+          
+          print.success('Login successful!');
+          print.info(`Merchant ID: ${result.merchant.id}`);
+          print.info(`Email: ${result.merchant.email}`);
+          if (result.merchant.name) {
+            print.info(`Name: ${result.merchant.name}`);
+          }
+          print.success('JWT token saved to config');
+        } else {
+          print.error(result.error || 'Login failed');
+        }
+        
+        if (flags.json) {
+          print.json(result);
+        }
+      } catch (error) {
+        print.error(error.message);
+      }
+      break;
+    }
+    
+    case 'me': {
+      try {
+        // Check if we have a JWT token
+        const jwtToken = config.jwtToken;
+        if (!jwtToken) {
+          print.error('Not authenticated. Run: coinpay auth login');
+          return;
+        }
+        
+        // Create client with JWT token instead of API key
+        const client = new CoinPayClient({ apiKey: jwtToken, baseUrl: getBaseUrl() });
+        const { getMe } = await import('../src/auth.js');
+        const result = await getMe(client);
+        
+        print.success('Current merchant:');
+        print.info(`ID: ${result.id}`);
+        print.info(`Email: ${result.email}`);
+        if (result.name) {
+          print.info(`Name: ${result.name}`);
+        }
+        print.info(`Created: ${result.created_at}`);
+        
+        if (flags.json) {
+          print.json(result);
+        }
+      } catch (error) {
+        if (error.message.includes('401') || error.message.includes('403')) {
+          print.error('Authentication failed. Please run: coinpay auth login');
+        } else {
+          print.error(error.message);
+        }
+      }
+      break;
+    }
+    
+    default:
+      print.error(`Unknown auth command: ${subcommand}`);
+      print.info('Available: register, login, me');
+      process.exit(1);
+  }
+}
+
 /**
  * Reputation commands
  */
@@ -1896,6 +2040,21 @@ async function handleReputation(subcommand, args, flags) {
           print.error(result.error || 'Failed to link DID');
         }
 
+        if (flags.json) print.json(result);
+      } else if (didSubcommand === 'me') {
+        // Show current DID
+        const { getMyDid } = await import('../src/reputation.js');
+        const result = await getMyDid(client);
+
+        if (result.did) {
+          print.success(`Your DID: ${result.did}`);
+          console.log(`  Public Key: ${result.public_key}`);
+          console.log(`  Verified: ${result.verified}`);
+          console.log(`  Created: ${result.created_at}`);
+        } else {
+          print.info('No DID found. Run: coinpay reputation did claim');
+        }
+
         if (flags.json) print.json(result);
       } else {
         // Default: show current DID
@@ -2449,9 +2608,17 @@ async function main() {
         await handleCard(subcommand, args, flags);
         break;
 
+      case 'auth':
+        await handleAuth(subcommand, args, flags);
+        break;
+        
       case 'reputation':
         await handleReputation(subcommand, args, flags);
         break;
+
+      case 'x402':
+        await handleX402(subcommand, args, flags);
+        break;
         
       default:
         print.error(`Unknown command: ${command}`);
@@ -2467,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.7",
+  "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/auth.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Auth SDK Module Types
+ */
+
+import { CoinPayClient } from './client.js';
+
+/**
+ * Merchant object returned from auth operations
+ */
+export interface Merchant {
+  id: string;
+  email: string;
+  name?: string;
+  created_at: string;
+  updated_at?: string;
+  [key: string]: any;
+}
+
+/**
+ * Auth response for register/login
+ */
+export interface AuthResponse {
+  success: boolean;
+  merchant: Merchant;
+  token: string;
+}
+
+/**
+ * Register params
+ */
+export interface RegisterParams {
+  email: string;
+  password: string;
+  name?: string;
+}
+
+/**
+ * Login params
+ */
+export interface LoginParams {
+  email: string;
+  password: string;
+}
+
+/**
+ * Register a new merchant account
+ * @param client - CoinPay client (can be unauthenticated)
+ * @param params - Registration parameters
+ * @returns Promise with registration response
+ */
+export function registerMerchant(
+  client: CoinPayClient,
+  params: RegisterParams
+): Promise<AuthResponse>;
+
+/**
+ * Login to merchant account
+ * @param client - CoinPay client (can be unauthenticated)
+ * @param params - Login parameters
+ * @returns Promise with login response
+ */
+export function loginMerchant(
+  client: CoinPayClient,
+  params: LoginParams
+): Promise<AuthResponse>;
+
+/**
+ * Get current authenticated merchant info
+ * @param client - Authenticated CoinPay client
+ * @returns Promise with merchant information
+ */
+export function getMe(client: CoinPayClient): Promise<Merchant>;

package/src/auth.js

@@ -0,0 +1,58 @@
+/**
+ * Auth SDK Module
+ *
+ * Authentication functions for registration, login, and merchant management.
+ *
+ * @example
+ * import { CoinPayClient } from '@profullstack/coinpay';
+ * import { registerMerchant, loginMerchant, getMe } from '@profullstack/coinpay/auth';
+ */
+
+/**
+ * Register a new merchant account
+ * @param {import('./client.js').CoinPayClient} client - CoinPay client (can be unauthenticated)
+ * @param {Object} params
+ * @param {string} params.email - Merchant email
+ * @param {string} params.password - Account password
+ * @param {string} [params.name] - Optional merchant name
+ * @returns {Promise<Object>} { success: boolean, merchant: Object, token: string }
+ */
+export async function registerMerchant(client, { email, password, name }) {
+  return client.requestUnauthenticated('/auth/register', {
+    method: 'POST',
+    body: JSON.stringify({
+      email,
+      password,
+      name,
+    }),
+  });
+}
+
+/**
+ * Login to merchant account
+ * @param {import('./client.js').CoinPayClient} client - CoinPay client (can be unauthenticated)
+ * @param {Object} params
+ * @param {string} params.email - Merchant email
+ * @param {string} params.password - Account password
+ * @returns {Promise<Object>} { success: boolean, merchant: Object, token: string }
+ */
+export async function loginMerchant(client, { email, password }) {
+  return client.requestUnauthenticated('/auth/login', {
+    method: 'POST',
+    body: JSON.stringify({
+      email,
+      password,
+    }),
+  });
+}
+
+/**
+ * Get current authenticated merchant info
+ * @param {import('./client.js').CoinPayClient} client - Authenticated CoinPay client
+ * @returns {Promise<Object>} Merchant information
+ */
+export async function getMe(client) {
+  return client.request('/auth/me', {
+    method: 'POST',
+  });
+}

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';
 
 /**
@@ -16,18 +18,17 @@ export class CoinPayClient {
   /**
    * Create a new CoinPay client
    * @param {Object} options - Client options
-   * @param {string} options.apiKey - Your CoinPay API key
+   * @param {string} [options.apiKey] - Your CoinPay API key (optional for auth operations)
    * @param {string} [options.baseUrl] - API base URL (default: https://coinpayportal.com/api)
    * @param {number} [options.timeout] - Request timeout in ms (default: 30000)
    */
-  constructor({ apiKey, baseUrl = DEFAULT_BASE_URL, timeout = 30000 }) {
-    if (!apiKey) {
-      throw new Error('API key is required');
-    }
-
+  constructor({ apiKey, baseUrl = DEFAULT_BASE_URL, timeout = 30000 } = {}) {
     this.#apiKey = apiKey;
     this.#baseUrl = baseUrl.replace(/\/$/, ''); // Remove trailing slash
     this.#timeout = timeout;
+
+    /** @type {LightningClient} Lightning/BOLT12 operations */
+    this.lightning = new LightningClient(this);
   }
 
   /**
@@ -37,6 +38,10 @@ export class CoinPayClient {
    * @returns {Promise<Object>} API response
    */
   async request(endpoint, options = {}) {
+    if (!this.#apiKey) {
+      throw new Error('API key is required for authenticated requests. Use requestUnauthenticated() for registration/login.');
+    }
+
     const url = `${this.#baseUrl}${endpoint}`;
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.#timeout);
@@ -72,6 +77,47 @@ export class CoinPayClient {
     }
   }
 
+  /**
+   * Make an unauthenticated API request (for registration/login)
+   * @param {string} endpoint - API endpoint
+   * @param {Object} [options] - Fetch options
+   * @returns {Promise<Object>} API response
+   */
+  async requestUnauthenticated(endpoint, options = {}) {
+    const url = `${this.#baseUrl}${endpoint}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.#timeout);
+
+    try {
+      const response = await fetch(url, {
+        ...options,
+        signal: controller.signal,
+        headers: {
+          'Content-Type': 'application/json',
+          ...options.headers,
+        },
+      });
+
+      const data = await response.json();
+
+      if (!response.ok) {
+        const error = new Error(data.error || `HTTP ${response.status}`);
+        error.status = response.status;
+        error.response = data;
+        throw error;
+      }
+
+      return data;
+    } catch (error) {
+      if (error.name === 'AbortError') {
+        throw new Error(`Request timeout after ${this.#timeout}ms`);
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
   /**
    * Create a new payment
    *

package/src/index.js

@@ -88,8 +88,18 @@ import {
   getBadgeUrl,
   verifyCredential,
   getRevocationList,
+  claimDid,
+  linkDid,
+  getMyDid,
 } from './reputation.js';
 
+// Auth exports
+import {
+  registerMerchant,
+  loginMerchant,
+  getMe,
+} from './auth.js';
+
 import {
   SwapClient,
   SwapCoins,
@@ -137,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,
@@ -216,8 +241,32 @@ export {
   submitReceipt,
   getReputation,
   getCredential,
+  getCredentials,
+  getReceipts,
+  getBadgeUrl,
   verifyCredential,
   getRevocationList,
+  claimDid,
+  linkDid,
+  getMyDid,
+  
+  // Lightning
+  LightningClient,
+  
+  // Auth
+  registerMerchant,
+  loginMerchant,
+  getMe,
+  
+  // x402 Protocol
+  createX402Middleware,
+  verifyX402Payment,
+  settleX402Payment,
+  buildPaymentRequired,
+  convertUsdToAssetAmount,
+  PAYMENT_METHODS,
+  USDC_CONTRACTS,
+  CHAIN_IDS,
   
   // Webhook utilities
   verifyWebhookSignature,

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}` };
+  }
+}