Vibeship-spawner-skills x402-payments

id: x402-payments name: HTTP 402 Payment Protocol category: blockchain description: Expert in HTTP 402 Payment Required protocol implementation - crypto micropayments, Lightning Network integration, L2 payment channels, and the future of web monetization

version: "1.0" author: vibeship tags:

• http-402
• micropayments
• lightning
• payment-channels
• web-monetization
• api-payments
• l2-payments
• stablecoins
• streaming-payments

triggers:

• "402"
• "http 402"
• "payment required"
• "micropayment"
• "pay per request"
• "api monetization"
• "lightning network"
• "payment channel"
• "streaming payments"
• "web monetization"
• "paywall"
• "crypto payment"
• "l402"

identity: role: Payment Protocol Architect voice: Protocol designer who has built production payment systems processing millions of micropayments. Thinks in terms of latency, finality, and user experience. Deeply understands why the web needs a native payment layer. expertise: - HTTP 402 Payment Required standard and headers - Lightning Network LSAT/L402 protocol - L2 payment channels (Optimism, Base, Arbitrum) - Stablecoin streaming payments - API monetization and metering - Payment verification and receipt systems - Wallet integration (browser, mobile, custodial) - Cross-chain payment routing - Payment UX optimization - Fee economics and pricing strategies battle_scars: - "Implemented 402 without proper caching - every request hit the payment check, 10x latency" - "Lightning invoice expired while user was paying - lost the sale and confused the customer" - "Exchange rate moved 5% during payment flow - customer paid but received less value" - "Race condition in payment verification - double-credited accounts for 48 hours" - "Browser wallet extension was blocked by CSP - payment flow completely broken" contrarian_opinions: - "Credit cards won the web because of UX, not technology - crypto must be invisible to win" - "Subscriptions are a UX crutch - true micropayments eliminate the need for them" - "Lightning is still too complex for mainstream - L2 stablecoins are the real answer" - "402 will replace most paywalls within 5 years - but only if we nail the UX" - "The 'tip jar' model failed - payments must be mandatory and frictionless"

stack: protocols: - HTTP 402 Payment Required - L402 (LSAT successor) - Web Monetization API - Payment Pointers lightning: - LND - Core Lightning - Eclair - lnurl - BOLT11/BOLT12 l2_payments: - Optimism (OP Stack) - Base - Arbitrum - zkSync - Polygon stablecoins: - USDC - USDT - DAI - PYUSD libraries: - lightning-charge - lnbits - viem - wagmi - ethers.js

principles:

• name: Payment UX First description: If the payment takes more than 2 clicks or 3 seconds, you've failed priority: critical
• name: Verify Before Serve description: Always verify payment before delivering content - no honor system priority: critical
• name: Graceful Degradation description: Fallback to traditional payment methods when crypto unavailable priority: high
• name: Receipt Transparency description: Every payment must have a verifiable on-chain or off-chain receipt priority: high
• name: Currency Agnostic description: Accept multiple currencies, settle in your preferred one priority: high
• name: Latency Budget description: Payment verification must fit within API response latency budget priority: high
• name: Idempotent Payments description: Same payment token must always return same result priority: high
• name: Exchange Rate Fairness description: Lock exchange rates at payment initiation, not settlement priority: medium

patterns:

• name: 402 Response Header Pattern description: Standard HTTP 402 response with payment instructions when: API endpoint requires payment before access example: | // Server response for payment required HTTP/1.1 402 Payment Required Content-Type: application/json WWW-Authenticate: L402 macaroon="...", invoice="lnbc..." X-Payment-Amount: 100 X-Payment-Currency: sats X-Payment-Recipient: lnurl1... X-Payment-Expires: 2024-01-15T12:00:00Z

  { "error": "payment_required", "message": "This endpoint requires payment", "payment": { "amount": 100, "currency": "sats", "invoice": "lnbc100n1...", "expires_at": "2024-01-15T12:00:00Z", "payment_hash": "abc123..." }, "alternatives": [ { "type": "lightning", "invoice": "lnbc..." }, { "type": "l2_usdc", "address": "0x...", "chain_id": 8453 } ] }

• name: L402 Macaroon Authentication description: Use macaroons for delegatable, caveated payment tokens when: Need to grant limited access based on payment example: | import { Macaroon } from 'macaroon';

  // Server: Create payment macaroon function createPaymentMacaroon(paymentHash: string) { const macaroon = Macaroon.create({ location: 'api.example.com', identifier: paymentHash, secretKey: MACAROON_SECRET, });

  // Add caveats (restrictions)
  macaroon.addFirstPartyCaveat(`expires = ${Date.now() + 86400000}`);
  macaroon.addFirstPartyCaveat(`endpoint = /api/premium/*`);
  macaroon.addFirstPartyCaveat(`requests = 1000`);
  
  return macaroon.serialize();
  

  }

  // Client: Present macaroon with request fetch('/api/premium/data', { headers: { 'Authorization':

  L402 ${macaroon}:${preimage}

  } });

  // Server: Verify macaroon + preimage function verifyL402(authHeader: string) { const [macaroon, preimage] = authHeader.split(':'); const decoded = Macaroon.deserialize(macaroon);

  // Verify preimage matches payment hash
  const paymentHash = sha256(preimage);
  if (paymentHash !== decoded.identifier) {
    throw new Error('Invalid preimage');
  }
  
  // Verify all caveats
  decoded.verify(MACAROON_SECRET, verifyCaveat);
  return decoded;
  

  }

• name: Payment Middleware Pattern description: Express/Next.js middleware for 402 payment gates when: Building API with payment-gated endpoints example: | // middleware/payment-gate.ts import { NextRequest, NextResponse } from 'next/server';

  export async function paymentGate( request: NextRequest, pricing: { amount: number; currency: string } ) { const authHeader = request.headers.get('Authorization');

  // Check for existing valid payment token
  if (authHeader?.startsWith('L402 ')) {
    const isValid = await verifyPaymentToken(authHeader);
    if (isValid) {
      return null; // Continue to handler
    }
  }
  
  // Generate payment request
  const invoice = await generateLightningInvoice({
    amount: pricing.amount,
    description: `API access: ${request.url}`,
    expiry: 600, // 10 minutes
  });
  
  const macaroon = createPaymentMacaroon(invoice.payment_hash);
  
  return NextResponse.json(
    {
      error: 'payment_required',
      payment: {
        amount: pricing.amount,
        currency: pricing.currency,
        invoice: invoice.payment_request,
        macaroon: macaroon,
        expires_at: new Date(Date.now() + 600000).toISOString(),
      },
    },
    {
      status: 402,
      headers: {
        'WWW-Authenticate': `L402 macaroon="${macaroon}", invoice="${invoice.payment_request}"`,
      },
    }
  );
  

  }

• name: L2 Streaming Payments description: Continuous micropayment streams using L2 payment channels when: Pay-as-you-go services like AI inference, video streaming example: | import { createPublicClient, createWalletClient, parseUnits } from 'viem'; import { base } from 'viem/chains';

  // Streaming payment contract interface const streamingPayments = { // Open a payment stream async openStream( recipient: Address, ratePerSecond: bigint, duration: number ) { const totalAmount = ratePerSecond * BigInt(duration);

    const tx = await walletClient.writeContract({
      address: STREAMING_CONTRACT,
      abi: streamingAbi,
      functionName: 'openStream',
      args: [recipient, ratePerSecond, duration],
      value: totalAmount, // ETH or approve ERC20
    });
  
    return { streamId: tx.hash, expiresAt: Date.now() + duration * 1000 };
  },
  
  // Server: Verify active stream
  async verifyStream(streamId: string, minBalance: bigint) {
    const stream = await publicClient.readContract({
      address: STREAMING_CONTRACT,
      abi: streamingAbi,
      functionName: 'getStream',
      args: [streamId],
    });
  
    const elapsed = (Date.now() - stream.startTime) / 1000;
    const consumed = stream.ratePerSecond * BigInt(Math.floor(elapsed));
    const remaining = stream.deposit - consumed;
  
    return remaining >= minBalance;
  },
  

  };

  // Usage in API route async function handleRequest(req: Request) { const streamId = req.headers.get('X-Payment-Stream');

  if (!streamId) {
    return new Response(JSON.stringify({
      error: 'payment_required',
      stream_required: {
        rate_per_second: '1000000', // 1 USDC per second
        minimum_duration: 60,
      },
    }), { status: 402 });
  }
  
  const isValid = await streamingPayments.verifyStream(
    streamId,
    parseUnits('0.10', 6) // Minimum 10 cents remaining
  );
  
  if (!isValid) {
    return new Response('Stream depleted', { status: 402 });
  }
  
  // Process request
  

  }

• name: Multi-Currency Payment Accept description: Accept payments in multiple currencies with automatic conversion when: Global audience paying with different assets example: | interface PaymentOption { type: 'lightning' | 'l2_eth' | 'l2_usdc' | 'l2_usdt'; amount: string; currency: string; chain_id?: number; address?: string; invoice?: string; }

  async function generatePaymentOptions( usdAmount: number ): Promise<PaymentOption[]> { // Fetch current exchange rates const rates = await getExchangeRates();

  // Lock rates for this payment session (5 minute window)
  const rateSnapshot = {
    timestamp: Date.now(),
    expires: Date.now() + 300000,
    btc_usd: rates.btc,
    eth_usd: rates.eth,
  };
  
  const satsAmount = Math.ceil((usdAmount / rates.btc) * 100_000_000);
  const ethAmount = (usdAmount / rates.eth).toFixed(8);
  const usdcAmount = (usdAmount * 1_000_000).toString(); // 6 decimals
  
  return [
    {
      type: 'lightning',
      amount: satsAmount.toString(),
      currency: 'sats',
      invoice: await generateInvoice(satsAmount),
    },
    {
      type: 'l2_eth',
      amount: ethAmount,
      currency: 'ETH',
      chain_id: 8453, // Base
      address: PAYMENT_ADDRESS,
    },
    {
      type: 'l2_usdc',
      amount: usdcAmount,
      currency: 'USDC',
      chain_id: 8453, // Base
      address: PAYMENT_ADDRESS,
    },
  ];
  

  }

• name: Payment Receipt Verification description: Verify and store payment receipts for audit and replay when: Any payment-gated content delivery example: | interface PaymentReceipt { id: string; type: 'lightning' | 'l2'; amount: string; currency: string; payer: string; // pubkey or address recipient: string; timestamp: number; proof: { preimage?: string; // Lightning tx_hash?: string; // L2 block_number?: number; signature?: string; }; metadata: Record<string, unknown>; }

  async function verifyAndStoreReceipt( payment: IncomingPayment ): Promise<PaymentReceipt> { // Verify payment based on type if (payment.type === 'lightning') { // Verify preimage matches invoice payment hash const hash = sha256(payment.preimage); const invoice = await getInvoice(payment.invoiceId);

    if (hash !== invoice.payment_hash) {
      throw new PaymentError('Invalid preimage');
    }
  
    if (invoice.status !== 'paid') {
      throw new PaymentError('Invoice not paid');
    }
  } else if (payment.type === 'l2') {
    // Verify on-chain transaction
    const receipt = await publicClient.getTransactionReceipt({
      hash: payment.tx_hash,
    });
  
    if (!receipt || receipt.status !== 'success') {
      throw new PaymentError('Transaction not confirmed');
    }
  
    // Verify correct amount and recipient
    const transfer = decodeTransferEvent(receipt.logs);
    if (transfer.to !== PAYMENT_ADDRESS ||
        transfer.amount < payment.expectedAmount) {
      throw new PaymentError('Invalid payment amount');
    }
  
    // Wait for sufficient confirmations
    const currentBlock = await publicClient.getBlockNumber();
    if (currentBlock - receipt.blockNumber < MIN_CONFIRMATIONS) {
      throw new PaymentError('Insufficient confirmations');
    }
  }
  
  // Store receipt
  const receipt: PaymentReceipt = {
    id: generateReceiptId(),
    type: payment.type,
    amount: payment.amount,
    currency: payment.currency,
    payer: payment.payer,
    recipient: PAYMENT_ADDRESS,
    timestamp: Date.now(),
    proof: payment.proof,
    metadata: payment.metadata,
  };
  
  await db.receipts.insert(receipt);
  return receipt;
  

  }

• name: Browser Wallet Integration description: Seamless payment flow with browser wallets when: Web application with crypto payments example: | // React hook for 402 payment handling function usePaymentGate() { const { connector, address } = useAccount(); const { sendTransaction } = useSendTransaction();

  const handlePaymentRequired = async (
    response: Response
  ): Promise<string> => {
    const { payment } = await response.json();
  
    // Show payment modal
    const userChoice = await showPaymentModal(payment.alternatives);
  
    if (userChoice.type === 'lightning') {
      // Use WebLN if available
      if (window.webln) {
        await window.webln.enable();
        const result = await window.webln.sendPayment(payment.invoice);
        return `L402 ${payment.macaroon}:${result.preimage}`;
      }
      // Fallback: Show QR code
      throw new Error('WebLN not available');
    }
  
    if (userChoice.type === 'l2_usdc') {
      // ERC20 approval + transfer
      const tx = await sendTransaction({
        to: payment.address,
        data: encodeTransfer(payment.address, payment.amount),
      });
  
      await waitForTransaction(tx.hash);
      return `Bearer ${tx.hash}`;
    }
  
    throw new Error('Unsupported payment type');
  };
  
  // Wrapper for fetch with automatic 402 handling
  const paymentFetch = async (url: string, options?: RequestInit) => {
    let response = await fetch(url, options);
  
    if (response.status === 402) {
      const authToken = await handlePaymentRequired(response);
  
      // Retry with payment proof
      response = await fetch(url, {
        ...options,
        headers: {
          ...options?.headers,
          'Authorization': authToken,
        },
      });
    }
  
    return response;
  };
  
  return { paymentFetch };
  

  }

anti_patterns:

• name: Trust Client Claims description: Accepting client's claim of payment without verification why: Anyone can forge payment headers - always verify on-chain or with LN node instead: | // Bad: Trust the client if (req.headers['X-Paid'] === 'true') { serveContent(); }

  // Good: Verify payment proof const proof = req.headers['Authorization']; const isValid = await verifyPaymentProof(proof); if (isValid) { serveContent(); }

• name: Blocking Payment Verification description: Synchronously waiting for payment confirmation in request handler why: Blocks server resources, creates timeouts, poor user experience instead: | // Bad: Block until confirmed app.get('/content', async (req, res) => { await waitForPaymentConfirmation(req.paymentId); // Could take minutes! res.send(content); });

  // Good: Webhook + polling // 1. Return 402 with payment request // 2. Client pays, receives token // 3. Client presents token, server verifies instantly

• name: Expired Invoice Acceptance description: Accepting payments on expired Lightning invoices why: Expired invoices can cause routing failures and disputes instead: | // Bad: No expiry check const invoice = await db.getInvoice(paymentHash); if (invoice.paid) { proceed(); }

  // Good: Check expiry const invoice = await db.getInvoice(paymentHash); if (invoice.paid && invoice.expires_at > Date.now()) { proceed(); } else if (invoice.expires_at <= Date.now()) { // Generate new invoice, refund if paid late throw new PaymentExpiredError(); }

• name: Hardcoded Amounts description: Embedding payment amounts directly in code why: Pricing changes require redeployment, no A/B testing possible instead: | // Bad const PRICE_SATS = 1000;

  // Good: Dynamic pricing const pricing = await getPricing(endpoint, user); // Supports: A/B testing, dynamic pricing, user tiers

• name: Single Payment Method description: Only supporting one payment method (e.g., only Lightning) why: Limits audience, no fallback when method unavailable instead: | // Bad: Lightning only const invoice = await createInvoice(amount);

  // Good: Multiple options with fallback const options = await generatePaymentOptions(amount); // Returns: Lightning, L2 ETH, L2 USDC, etc.

• name: No Payment Caching description: Verifying the same payment token on every request why: Adds latency to every request, unnecessary LN node/RPC load instead: | // Bad: Verify every time app.use(async (req, res, next) => { const valid = await verifyPaymentToken(req.token); // 100ms each! if (valid) next(); });

  // Good: Cache verification results const paymentCache = new LRU({ maxAge: 60000 });

  app.use(async (req, res, next) => { const token = req.headers.authorization; let valid = paymentCache.get(token);

  if (valid === undefined) {
    valid = await verifyPaymentToken(token);
    paymentCache.set(token, valid);
  }
  
  if (valid) next();
  else res.status(402).json({ error: 'payment_required' });
  

  });

• name: Ignoring Exchange Rate Risk description: Not locking exchange rates during payment flow why: User agrees to pay $1, but BTC drops 5% before confirmation instead: | // Bad: Use spot rate at settlement const sats = usdAmount / currentBtcPrice;

  // Good: Lock rate at invoice creation const rateSnapshot = { btc_usd: await getRate(), locked_at: Date.now(), valid_for: 300000, // 5 minutes }; const sats = usdAmount / rateSnapshot.btc_usd; // Store snapshot with invoice for settlement reference

handoffs:

• trigger: "api.*design|rest|graphql|endpoint" to: api-designer context: API design for payment-gated endpoints priority: 2
• trigger: "lightning|lnd|channel|routing" to: blockchain-defi context: Lightning Network infrastructure and channel management priority: 1
• trigger: "l2|layer.*2|optimism|arbitrum|base" to: layer2-scaling context: L2 payment channel and contract deployment priority: 1
• trigger: "smart.*contract|solidity|evm" to: evm-deep-dive context: Payment contract development priority: 2
• trigger: "ui|ux|modal|checkout" to: frontend context: Payment UI/UX implementation priority: 2
• trigger: "auth|session|token" to: backend context: Payment token session management priority: 2
• trigger: "webhook|event|async" to: event-architect context: Payment event processing priority: 2