x402 Paywall Reference

x402 Paywall Reference

Detailed API reference for @x402-avm/paywall and framework middleware packages.

Package: @x402-avm/paywall

Installation

npm install @x402-avm/paywall @x402-avm/avm @x402-avm/core

Exports from @x402-avm/paywall

Exports from @x402-avm/paywall/avm

PaywallBuilder

createPaywall()

Factory function that creates a new PaywallBuilder instance.

function createPaywall(): PaywallBuilder;

PaywallBuilder Methods

PaywallProvider

interface PaywallProvider {
  /**
   * Generate an HTML paywall page for the given payment requirements.
   * @param paymentRequired - The full 402 response from the server
   * @param config - Optional runtime config override
   * @returns Full HTML page as a string
   */
  generateHtml(paymentRequired: PaymentRequired, config?: PaywallConfig): string;
}

PaywallConfig

interface PaywallConfig {
  /** App name shown in wallet connection modal title */
  appName?: string;
  /** App logo URL shown in the paywall header */
  appLogo?: string;
  /** URL of the content being accessed (used for retry after payment) */
  currentUrl?: string;
  /** Whether to use testnet (default: true) */
  testnet?: boolean;
}

PaywallNetworkHandler

Interface for creating custom network-specific paywall handlers.

interface PaywallNetworkHandler {
  /**
   * Check if this handler supports the given payment requirement.
   * @param requirement - A single payment requirement from the 402 response
   * @returns true if this handler can generate HTML for this requirement
   */
  supports(requirement: PaymentRequirements): boolean;

  /**
   * Generate the full HTML paywall page.
   * @param requirement - The matched payment requirement
   * @param paymentRequired - The full PaymentRequired response
   * @param config - Paywall configuration
   * @returns Full HTML page as a string
   */
  generateHtml(
    requirement: PaymentRequirements,
    paymentRequired: PaymentRequired,
    config: PaywallConfig,
  ): string;
}

Built-in Handlers

Handler Selection

When PaywallProvider.generateHtml() is called, it iterates through registered handlers in order. The first handler whose supports() returns true for any of the accepts requirements is used to generate the HTML.

avmPaywall Handler

The avmPaywall handler generates a full React-based HTML page with:

1. window.x402 global -- Embeds payment configuration for the client-side app
2. Wallet discovery -- Uses @wallet-standard/app to find Algorand wallets
3. Wallet selection UI -- Dropdown with icons for detected wallets
4. Balance checking -- Reads USDC ASA balance for the connected account
5. Transaction signing -- Uses algorand:signTransaction wallet-standard feature
6. Payment submission -- Retries original request with PAYMENT-SIGNATURE header
7. Automatic redirect -- Redirects to paid content after successful payment

Supported Wallets

window.x402 Configuration Object

The generated HTML page injects this configuration:

window.x402 = {
  amount: 0.01,           // Amount in USDC (human-readable)
  paymentRequired: {...},  // Full PaymentRequired response
  testnet: true,           // Network mode
  currentUrl: "...",       // URL to retry after payment
  config: { chainConfig: {} },
  appName: "My App",
  appLogo: "https://...",
};

Framework Middleware

@x402-avm/express

@x402-avm/hono

@x402-avm/next

Route Configuration

interface RouteConfig {
  [path: string]: {
    /** Payment requirements -- single object or array for multi-network */
    accepts: PaymentAccepts | PaymentAccepts[];
    /** Human-readable description of the resource */
    description: string;
    /** MIME type of the response */
    mimeType: string;
  };
}

interface PaymentAccepts {
  /** Payment scheme (currently "exact") */
  scheme: string;
  /** CAIP-2 network identifier */
  network: string;
  /** Asset identifier (ASA ID for Algorand, contract address for EVM) */
  asset: string;
  /** Receiver address */
  payTo: string;
  /** Price string (e.g., "$0.01") */
  price: string;
  /** Maximum timeout in seconds for payment validity */
  maxTimeoutSeconds: number;
}

Bundle Sizes

The paywall system is designed for tree-shaking. Import only the network handlers you need:

// AVM only -- smallest bundle
import { avmPaywall } from "@x402-avm/paywall/avm";

// AVM + EVM
import { avmPaywall, evmPaywall } from "@x402-avm/paywall";

// All networks
import { avmPaywall, evmPaywall, svmPaywall } from "@x402-avm/paywall";

USDC Asset IDs

Testing

Testing the Paywall HTML Generation

import { createPaywall, avmPaywall } from "@x402-avm/paywall";

const paywall = createPaywall()
  .withNetwork(avmPaywall)
  .withConfig({ appName: "Test App", testnet: true })
  .build();

const html = paywall.generateHtml({
  x402Version: 2,
  accepts: [{
    scheme: "exact",
    network: "algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=",
    asset: "10458941",
    payTo: "TEST_ADDRESS",
    amount: "10000",
    maxTimeoutSeconds: 300,
  }],
  resource: {
    url: "https://test.example.com/premium",
    description: "Test content",
    mimeType: "application/json",
  },
});

// Verify the HTML contains expected elements
console.assert(html.includes("window.x402"));
console.assert(html.includes("Test App"));

Testing Middleware Integration

# Start server
npm start

# Test JSON 402 response (API client)
curl -H "Accept: application/json" http://localhost:3000/api/premium

# Test HTML paywall (browser-like)
curl -H "Accept: text/html" http://localhost:3000/api/premium

# Test with payment header (after obtaining one)
curl -H "PAYMENT-SIGNATURE: <base64-payload>" http://localhost:3000/api/premium

Important Notes

• The paywall HTML page is a self-contained React application served inline. No additional static files or CDN dependencies are required.
• withNetwork() order determines handler priority. Register your preferred network first.
• The testnet flag in PaywallConfig affects which Algod endpoint the paywall page connects to (AlgoNode testnet vs mainnet).
• Route paths support Express-style patterns (:param, * wildcards).
• The price field in route config accepts human-readable strings like "$0.01" which are converted to microunits internally.

External Resources

• x402-avm Examples Repository
• x402-avm Documentation
• @wallet-standard/app
• @txnlab/use-wallet