@correntelabs/htmx-x402 ⚡🏛️

Declarative Hypermedia Micropayments for HTMX
Sub-2KB (gzipped), zero-dependency client extension bringing native HTTP 402 Payment Required handling to the hypermedia web.
Eliminates bloated 450KB+ client Web3 script bundles and moves financial state execution to isolated, hardware-attested server environments.

🚀 Why HTMX + x402?

Modern Web3 Single-Page Applications (SPAs) require massive JavaScript bundles (React, Wagmi, Ethers, Viem — often 450KB to 2MB+) running insecurely in the client browser. This introduces severe attack vectors:

• Client Memory Snooping & DOM Injection: Malicious browser extensions or XSS can intercept private keys and manipulate transaction payloads before signing.
• Dependency Supply Chain Hazards: Hundreds of transitive npm dependencies in client-side wallet connectors create systemic financial vulnerability.
• Un-Auditable State Drift: Regulators and counterparties cannot verify whether client-side state machine transitions were executed legitimately.

The Corrente Hypermedia Paradigm: The browser is an unprivileged hypermedia viewer. Financial state mutations, enclave attestation quotes, and settlement verification occur inside hardware enclaves and are returned as clean, declarative HTML fragments.

┌──────────────────────────────────────────────────────────────┐
│  Browser DOM (Zero-Client-Script / HTMX Hypermedia)          │
└──────────────┬───────────────────────────────▲───────────────┘
  1. POST /api │                               │ 4. Verified HTML
     (no auth) │                               │    Fragment Swap
               ▼                               │
┌──────────────────────────────┐ ┌─────────────┴───────────────┐
│ Server / Enclave Gateway     │ │ Isolated Execution Enclave  │
│ 2. HTTP 402 Payment Required ├─► 3. Atomic Settle & Attest   │
│    (Algorand / Base / XRPL)  │ │    (Hardware RTMR quote)    │
└──────────────────────────────┘ └─────────────────────────────┘

📦 Quick Start

1. Direct Script Tag (Zero Bundler Required)

Drop the script tag immediately after HTMX:

<!-- Core HTMX -->
<script src="https://unpkg.com/[email protected]"></script>

<!-- Corrente x402 Extension (<2KB gzipped) -->
<script src="https://cdn.jsdelivr.net/npm/@correntelabs/htmx-x402/dist/htmx-x402.min.js"></script>

<!-- Declarative HTML Micropayment -->
<body hx-ext="x402">
  <div id="result">Click below to unlock live data</div>

  <button hx-post="/api/market-depth"
          hx-target="#result"
          hx-swap="outerHTML">
    Unlock Order Book (0.01 ALGO)
  </button>
</body>

2. Modern Bundlers (Vite, Next.js, Astro)

npm install @correntelabs/htmx-x402 htmx.org

import htmx from 'htmx.org';
import { registerHtmxX402 } from '@correntelabs/htmx-x402';

// Auto-registers the 'x402' extension with your HTMX instance
registerHtmxX402(htmx, {
  defaultRail: 'algorand', // 'algorand' | 'base' | 'flare' | 'xrpl'
  onPaymentSuccess: ({ challenge }) => {
    console.log(`Settled ${challenge.amount} ${challenge.asset} via ${challenge.rail}`);
  },
  onPaymentFailure: ({ error }) => {
    console.error(`Payment failed: ${error}`);
  }
});

⚡ Execution Modes

Mode 1: Fast-Path Micro-Allowance (Zero Friction)

For high-frequency or sub-second interactions (e.g. streaming data, AI inference tokens, real-time order books), grant a local micro-allowance so user prompts are not interrupted by repeated signing modals:

// Pre-authorize up to 5 ALGO across requests (max 0.1 ALGO per click)
window.x402.setAllowance({
  maxPerRequest: 100000n, // micro-units
  totalRemaining: 5000000n,
  asset: 'ALGO',
  signer: async (challenge) => {
    // Return signed transaction or authorization token
    return await myWallet.signFastPath(challenge);
  }
});

Mode 2: Interactive Wallet Approval

If no allowance is active, the extension dispatches a standard DOM CustomEvent x402:challenge allowing your UI or wallet provider to prompt the user:

document.addEventListener('x402:challenge', async (evt) => {
  const { challenge, resolve, reject } = evt.detail;
  
  const approved = await myWalletModal.confirmPayment(
    challenge.amount, 
    challenge.asset, 
    challenge.recipient
  );

  if (approved) {
    const signature = await myWallet.sign(challenge);
    resolve(signature); // Retries request and swaps HTML automatically
  } else {
    reject(); // Aborts swap safely
  }
});

🌐 Universal Multi-Rail Neutrality

The extension parses standard RFC HTTP 402 challenges across diverse financial networks:

| Rail | Header Spec | Asset Default | Finality | | :--- | :--- | :--- | :--- | | Algorand | rail="algorand" | ALGO / ASA | Sub-3s Deterministic | | Base / EVM | rail="base" | USDC / ETH | Sub-2s L2 Rollup | | Flare | rail="flare" | FLR / FXRP | Enclave Attested | | XRPL | rail="xrpl" | XRP / RLUSD | Sub-4s Consensus |

🔒 Security & Architecture

• Zero Client Financial State: No private keys or financial balances are managed by HTMX or the extension.
• Hardware Enclave Rooted: Compatible with Intel TDX and AMD SEV-SNP attestation quotes.
• Two-Phase Inversion: On any rendering failure or payment mismatch, state transactions roll back deterministically before committing.
• FINOS CALM Ready: Conforms to the FINOS Common Architecture Language Model (CALM) reference architecture for agentic financial workflows.

📄 License & Attribution

Authored and maintained by Corrente Labs, Inc. ([email protected]), a Delaware C-Corporation.
Licensed under the MIT License.