feat: Extract paywall into modular package

[apmcdermott]

Extracts the paywall from the monolithic legacy package into a standalone @x402/paywall package with modular architecture, builder pattern API, and tree-shakeable network-specific imports.

New Package: @x402/paywall

Location: typescript/packages/http/paywall/

Key Features:

• Standalone paywall package with EVM and Solana support
• Builder pattern for flexible configuration
• Subpath exports for tree shaking: /evm and /svm
• Backwards compatible with legacy x402/paywall API

Bundle Sizes:

• Full paywall: 3.5 MB (both networks)
• EVM only: 3.4 MB (probably due to OnchainKit... we should figure out a way to reduce this)
• Solana only: 1.0 MB

Core Integration

@x402/core:

• Added PaywallProvider interface
• Added setPaywallProvider() method to x402HTTPResourceService
• Auto-detects and uses @x402/paywall if installed, otherwise falls back to basic HTML

@x402/express:

• Added optional PaywallProvider parameter to paymentMiddleware()

Architecture

@x402/paywall (main)
├── index.ts          - Legacy getPaywallHtml() + builder exports
├── builder.ts        - PaywallBuilder with withNetwork() and withConfig()
├── types.ts          - PaywallProvider, PaywallNetworkHandler interfaces
├── evm/
│   ├── index.ts      - evmPaywall handler
│   ├── EvmPaywall.tsx
│   └── build.ts      - Separate build for EVM-only bundle
└── svm/
    ├── index.ts      - svmPaywall handler
    ├── SolanaPaywall.tsx
    └── build.ts      - Separate build for Solana-only bundle

API

Legacy (Backwards Compatible)

import { getPaywallHtml } from '@x402/paywall';
const html = getPaywallHtml({...});

Builder Pattern

import { createPaywall } from '@x402/paywall';
import { evmPaywall } from '@x402/paywall/evm';

const paywall = createPaywall()
  .withNetwork(evmPaywall)
  .withConfig({ appName: 'My App', testnet: true })
  .build();

app.use(paymentMiddleware(routes, facs, schemes, undefined, paywall));

Network-Specific Imports

// EVM only - no Solana dependencies
import { evmPaywall } from '@x402/paywall/evm';

// Solana only - no EVM dependencies
import { svmPaywall } from '@x402/paywall/svm';

Migration Path

From legacy x402/paywall:

// Before
import { getPaywallHtml } from 'x402/paywall';

// After
import { getPaywallHtml } from '@x402/paywall';
// Same API - no code changes needed

Future Work

• Refactor to use x402Client internally for cleaner architecture
• Investigate OnchainKit bundle size optimizations

Checklist

• I have formatted and linted my code
• All new and existing tests pass
• My commits are signed (required for merge) -- you may need to rebase if you initially pushed unsigned commits

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
x402	Ready	Preview	Comment	Nov 4, 2025 10:20pm

[carsonroscoe-cb]

I feel like these networks should be pulled up.

Right now @x402/core has a /types export for v2 types, and /types/v1 for v1.

I know these are constants and not types, but I feel like these should be moved to /types/v1 as EVM_NETWORKS and we do the same for SVM_NETWORKS with solana/solana-devnet.

[apmcdermott]

Like this?: 6172acd#diff-58390f4af4a7ec12e7b9e75cf79672b9f3e3e7dd3f1b52e9436dace3ffd62793R60-R79

[CarsonRoscoe]

Ideally supports should take x402Version and PaymentRequirements, so that it can do a check on the version. Shape of PaymentRequirements is fine for now as there's just two versions, but as we improve it'll be much easier to maintain backwards compatibility if we push these v1/v2 scenarios to switch on x402Version rather than shape

[CarsonRoscoe]

Devx question, how about this join the builder pattern?

registerPaywallProvider(provider?: PaywallProvider): x402HTTPResourceService {
  this.paywallProvider = provider;
  return this;
}

This would allow middleware implementers to add it to the builder chain

[CarsonRoscoe]

One pattern I'm following is to operate as if v2 is the default, and v1 is the branching logic.

For example, this function can be a bit hard to read with the two cases mixed in every step of the way

I would suggest ensureValidAmount and ensureValidAmountV1 are two functions that each do their one thing right, and the caller should check the x402Version to determine which to call.

Either that, or the x402Version should be passed in, and there should be a switch statement about how handling v1 and v2 differ

[apmcdermott]

saddest rebase in the universe. new branch here: #600