Install the package
Add @axlabs/x402-react-paywall with @x402/fetch, @x402/evm, and viem. Import the bundled styles or plan a custom overlay from day one.
Wallet-based x402 paymentsfor React SPAs
@axlabs/x402-react-paywall adds PaywallProvider and PaywallGate so browser users can pay gateway URLs with connected wallets — same verify and settle flow as SDK buyers.
React SPA
Seven-day forecast
PaywallGate wraps premium content behind a gateway URL — same verify and settle flow as SDK buyers.
Seven-day forecast for Zurich: partly cloudy with highs around 24°C…
Content locked
PaywallGate inspects the resource URL and shows payment UI when content requires x402 settlement.
https://weather-demo.ax402.dev/v1/forecast?city=Zurich
Auto-playing demo · not a real purchase
Click Cycle states to step through the paywall flow.
Workflow
From install to unlocked content
Create the paid route in the dashboard first, then point PaywallGate at your gateway URL. The paywall handles 402 discovery, wallet connection, signing, and retry.
Wrap your SPA
Mount PaywallProvider at the app root with network policy and RPC settings. Children inherit wallet state and payment configuration.
Gate a gateway URL
Point PaywallGate at a priced hostname. A plain fetch inspects the resource URL and surfaces HTTP 402 requirements from gateway accepts.
Pay and unlock
The user connects a wallet, signs via @x402/fetch, and retries until upstream returns 200 — paid body replaces the teaser content.
Capabilities
PaywallProvider and PaywallGate
Default styles for quick integration, appearance slots for branding, and custom UI when you need full control over the overlay.
PaywallGate
Wrap any React subtree behind a gateway URL. Free preview stays visible until payment succeeds and the paid response is fetched.
402 discovery
Inspect the resource URL with a plain fetch and render price, network, and asset from gateway accepts — no manual payment config in the SPA.
Wallet payments
Connect via viem and pay through @x402/fetch — the same verify and settle path SDK buyers use, adapted for browser wallets.
Default theme
Import bundled styles.css or override appearance slots for typography, colors, spacing, and overlay layout without forking core logic.
Custom UI
Replace the overlay entirely with your own components while keeping PaywallGate discovery, signing, and retry behavior.
Agent metadata
Expose discovery fields on gated resources so agents can find priced URLs and machine-readable payment requirements.
Integration
Minimal React setup
Install the package, wrap your app with PaywallProvider, and gate a gateway URL. Import default styles or supply a fully custom UI.
Install
pnpm add @axlabs/x402-react-paywall @x402/fetch @x402/evm viem react react-domMinimal example
import "@axlabs/x402-react-paywall/styles.css";
import { PaywallProvider, PaywallGate } from "@axlabs/x402-react-paywall";
export function ArticlePage() {
return (
<PaywallProvider
policy={{
preferredNetworks: "eip155:84532",
allowedAssets: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
}}
rpc={{ defaultUrl: "https://sepolia.base.org" }}
>
<PaywallGate
resourceUrl="https://your-gateway.example.com/v1/article"
title="Unlock full article"
description="One micropayment via x402 on your gateway."
>
<p>Free preview paragraph…</p>
</PaywallGate>
</PaywallProvider>
);
}Documentation
Go deeper in the React paywall guides
Components, theming, custom UI, agent discovery metadata, and runnable examples are documented for browser integrations.
React paywall overview
Package architecture, PaywallProvider, and PaywallGate behavior.
Getting started
Install, configure policy and RPC, and test against a gateway URL.
Components reference
Props, slots, and lifecycle for provider and gate components.
Theming
Appearance slots, bundled styles, and brand overrides.
Custom UI
Replace the overlay while keeping discovery and payment logic.
Agent discovery
Metadata fields agents use to find priced resources.
Add a paywall to your next SPA
Publish a gateway route, install @axlabs/x402-react-paywall, and test against staging or your own hostname.