x402 Solana React Paywall

A reusable React component library that provides drop-in paywall functionality for Solana-based applications using the x402 payment protocol v2.

x402 Protocol v2: This package uses x402-solana which implements the x402 v2 specification with CAIP-2 network identifiers, PAYMENT-SIGNATURE headers, and improved payload structure. See the CHANGELOG for details.

Classic theme

Solana theme

Seeker theme

Terminal theme

🚀 Features

✅ Drop-in React Components: Easy integration with existing apps
✅ Auto-Setup Providers: Automatically configures wallet providers (or use your own)
✅ Solana Native: Built specifically for Solana blockchain
✅ Multi-Wallet Support: Works with Phantom, Solflare, and more
✅ Multiple Themes: Light, Dark, Solana, Seeker, Terminal themes
✅ Tailwind CSS: Utility-first styling with customization
✅ shadcn/ui: Accessible, beautiful components
✅ TypeScript: Full type safety and IntelliSense
✅ Network Auto-Detection: Automatically configures mainnet/devnet

📋 Prerequisites

Node.js: v18.0.0 or higher
React: v18.0.0 or higher
Solana Wallet: Phantom, Solflare, or any Solana wallet adapter compatible wallet
USDC Balance: For mainnet payments (devnet for testing)

📦 Installation

npm install @payai/x402-solana-react
# or
yarn add @payai/x402-solana-react
# or
pnpm add @payai/x402-solana-react

Install Peer Dependencies

You'll also need Solana wallet adapter packages:

npm install @solana/wallet-adapter-react @solana/wallet-adapter-react-ui @solana/wallet-adapter-wallets @solana/web3.js

⚙️ Setup

1. Import Styles

Import the required styles in your main file (e.g., main.tsx or App.tsx):

import '@payai/x402-solana-react/styles';
import '@solana/wallet-adapter-react-ui/styles.css';

2. Environment Variables (Optional - Recommended for Production)

For production use, configure a custom RPC endpoint to avoid rate limiting on public RPCs:

Create a .env file (you can copy from the included .env.example) and set your RPC URL:

# Your Helius/QuickNode/Alchemy RPC URL
VITE_SOLANA_RPC_URL=https://mainnet.helius-rpc.com/?api-key=your_api_key_here

Restart the dev server after changing .env so Vite picks up updates.

3. Wallet Provider Setup (Optional)

Option A: Auto-Setup (Recommended) 🎉

The component automatically sets up wallet providers for you! Just use it directly:

import { X402Paywall } from '@payai/x402-solana-react';

function App() {
  return (
    <X402Paywall
      amount={0.01}
      description="Premium Content"
      network="solana" // Automatically configures mainnet
    >
      <YourPremiumContent />
    </X402Paywall>
  );
}

Option B: Manual Setup (if you need custom wallet configuration)

Wrap your app with Solana wallet providers:

import { WalletAdapterNetwork } from '@solana/wallet-adapter-base';
import { ConnectionProvider, WalletProvider } from '@solana/wallet-adapter-react';
import { WalletModalProvider } from '@solana/wallet-adapter-react-ui';
import { PhantomWalletAdapter, SolflareWalletAdapter } from '@solana/wallet-adapter-wallets';
import { clusterApiUrl } from '@solana/web3.js';

function App() {
  const network = WalletAdapterNetwork.Mainnet;
  const endpoint = clusterApiUrl(network);
  const wallets = [new PhantomWalletAdapter(), new SolflareWalletAdapter()];

  return (
    <ConnectionProvider endpoint={endpoint}>
      <WalletProvider wallets={wallets} autoConnect={false}>
        <WalletModalProvider>
          <X402Paywall
            amount={0.01}
            description="Premium Content"
            network="solana"
            autoSetupProviders={false} // Disable auto-setup
          >
            <YourPremiumContent />
          </X402Paywall>
        </WalletModalProvider>
      </WalletProvider>
    </ConnectionProvider>
  );
}

🎯 Quick Start

Simplest Example (Auto-Setup)

import { X402Paywall } from '@payai/x402-solana-react';
import '@payai/x402-solana-react/styles';
import '@solana/wallet-adapter-react-ui/styles.css';

function PremiumPage() {
  return (
    <X402Paywall
      amount={0.02}
      description="Premium AI Chat Access"
      network="solana" // Use 'solana' for mainnet, 'solana-devnet' for testing
      onPaymentSuccess={txId => console.log('Payment successful!', txId)}
    >
      <PremiumContent />
    </X402Paywall>
  );
}

With Custom RPC (Recommended for Production)

import { X402Paywall } from '@payai/x402-solana-react';

function PremiumPage() {
  // Set via environment variable: VITE_SOLANA_RPC_URL
  const rpcUrl = import.meta.env.VITE_SOLANA_RPC_URL;

  return (
    <X402Paywall
      amount={0.02}
      description="Premium Content"
      network="solana"
      rpcUrl={rpcUrl} // Avoids rate limiting on public RPCs
      onPaymentSuccess={txId => {
        console.log('Payment successful!', txId);
        // Update your backend, show success message, etc.
      }}
      onPaymentError={error => {
        console.error('Payment failed:', error);
      }}
    >
      <PremiumContent />
    </X402Paywall>
  );
}

🎨 Themes & Styling

The component comes with multiple built-in themes:

Available Themes

light - Clean light theme with gradients
dark - Dark theme with pink/purple/blue gradients
solana-light - Official Solana light theme (default)
solana-dark - Official Solana dark theme
seeker - Emerald/teal gradient theme
seeker-2 - Enhanced seeker theme with backdrop blur
terminal - Retro terminal green-on-black theme

Theme Example

import { X402Paywall } from '@payai/x402-solana-react';
import { useState } from 'react';

function PremiumPage() {
  const [theme, setTheme] = useState('light');

  return (
    <X402Paywall
      amount={0.02}
      description="Premium Features"
      network="solana"
      theme={theme} // Try: 'light', 'dark', 'solana-light', 'solana-dark', etc.
      onPaymentSuccess={txId => console.log('Paid!', txId)}
    >
      <AdvancedFeatures />
    </X402Paywall>
  );
}

Custom Styling

You can customize further using classNames and customStyles props:

<X402Paywall
  amount={5.0}
  description="Premium Features"
  network="solana"
  theme="dark"
  classNames={{
    container: 'bg-gradient-to-r from-purple-600 to-blue-600',
    button: 'bg-white text-purple-600 hover:bg-gray-50 font-bold',
  }}
  customStyles={{
    button: { boxShadow: '0 10px 30px rgba(153, 69, 255, 0.4)' },
  }}
>
  <AdvancedFeatures />
</X402Paywall>

📚 API Reference

X402Paywall Props

Prop	Type	Required	Default	Description
`amount`	`number`	✅	-	Payment amount in USDC
`description`	`string`	✅	-	Payment description
`children`	`ReactNode`	✅	-	Protected content to show after payment
`network`	`'solana' \| 'solana-devnet'`	❌	`'solana-devnet'`	Solana network to use
`wallet`	`WalletAdapter`	❌	-	Optional wallet adapter (auto-uses context if not provided)
`rpcUrl`	`string`	❌	-	Custom RPC URL (recommended to avoid rate limits)
`autoSetupProviders`	`boolean`	❌	`true`	Automatically setup wallet providers
`providerNetwork`	`WalletAdapterNetwork`	❌	Auto-detected	Network for auto-setup providers
`providerEndpoint`	`string`	❌	-	Custom endpoint for auto-setup providers
`apiEndpoint`	`string`	❌	`https://x402.payai.network/api/solana/paid-content`	Custom API endpoint
`facilitatorUrl`	`string`	❌	-	Custom facilitator URL
`theme`	`ThemePreset`	❌	`'solana-light'`	Visual theme (see Themes section)
`logoUrl`	`string`	❌	-	Custom logo URL to display
`showBalance`	`boolean`	❌	`true`	Show wallet USDC balance
`showNetworkInfo`	`boolean`	❌	`true`	Show network information
`showPaymentDetails`	`boolean`	❌	`true`	Show payment details section
`maxPaymentAmount`	`number`	❌	-	Maximum allowed payment amount
`classNames`	`ComponentClassNames`	❌	-	Custom CSS classes for components
`customStyles`	`ComponentStyles`	❌	-	Custom inline styles for components
`onPaymentStart`	`() => void`	❌	-	Callback when payment starts
`onPaymentSuccess`	`(txId: string) => void`	❌	-	Callback on successful payment
`onPaymentError`	`(error: Error) => void`	❌	-	Callback on payment error
`onWalletConnect`	`(publicKey: string) => void`	❌	-	Callback when wallet connects
`onDisconnect`	`() => void`	❌	-	Callback when wallet disconnects

See full API documentation for complete reference.

🛠️ Development

Setup

# Clone the repository
git clone https://github.com/payainetwork/x402-solana-react.git
cd x402-solana-react

# Install dependencies
npm install

# Copy environment variables
cp .env.example .env
# Edit .env and add your custom RPC URL (Helius, QuickNode, etc.)
# Example: VITE_SOLANA_RPC_URL=https://mainnet.helius-rpc.com/?api-key=YOUR_KEY

# Start development server
npm run dev

Build

# Build library
npm run build

# Type check
npm run typecheck

# Lint
npm run lint

🐛 Troubleshooting

Common Issues

"Wallet not connected"

Ensure wallet provider is properly configured
Check that wallet extension is installed and unlocked
Verify network matches (mainnet vs devnet)

"Insufficient USDC balance"

Check wallet has enough USDC for payment + gas
On devnet: Use Solana Faucet for SOL
Get devnet USDC from test token faucets like Circle

"RPC rate limit exceeded"

Use a custom RPC provider (Helius, QuickNode, Alchemy)
Set VITE_SOLANA_RPC_URL in .env file
Pass via rpcUrl prop: rpcUrl={import.meta.env.VITE_SOLANA_RPC_URL}
For production, always use a paid RPC endpoint

"Transaction failed"

Verify network connectivity
Check Solana network status
Ensure sufficient SOL for transaction fees

Styling not working

Make sure you imported both required stylesheets:

import '@payai/x402-solana-react/styles';
import '@solana/wallet-adapter-react-ui/styles.css';

Check browser console for CSS loading errors
Verify Tailwind CSS is configured if using custom classes

"process is not defined" error

Use Vite's import.meta.env instead of process.env
Example: import.meta.env.VITE_SOLANA_RPC_URL

✅ Status

Ready for Production - Fully functional x402 paywall components with PayAI facilitator integration.

Features Complete

✅ Core paywall component with Solana integration
✅ x402 Protocol v2 - Full support via x402-solana
✅ Payment processing via x402 protocol
✅ Multi-wallet support (Phantom, Solflare, etc.)
✅ Beautiful Solana-themed UI with Tailwind CSS
✅ TypeScript support with full type safety
✅ Devnet integration with PayAI facilitator
✅ Responsive design and accessibility

x402 v2 Protocol

This package supports the x402 v2 specification which includes:

Feature	v1	v2
Network Format	`solana`, `solana-devnet`	CAIP-2 format (auto-converted)
Payment Header	`X-PAYMENT`	`PAYMENT-SIGNATURE`
Amount Field	`maxAmountRequired`	`amount`

Note: You can still use simple network names (solana, solana-devnet) in your code - the library automatically converts them to CAIP-2 format internally.

🤝 Contributing

This project is currently in early development. Contributions welcome!

📄 License

MIT License

🔗 Related Projects

x402-solana - Base Solana payment protocol implementation (x402 v2)
x402 - Core x402 payment protocol specification
PayAI Network - x402 payment infrastructure and facilitator

Built with ❤️ for the Solana ecosystem

Name		Name	Last commit message	Last commit date
Latest commit History 153 Commits
.github/workflows		.github/workflows
docs		docs
example-images		example-images
examples		examples
src		src
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.nvmrc		.nvmrc
CHANGELOG.md		CHANGELOG.md
Makefile		Makefile
README.md		README.md
components.json		components.json
env.example		env.example
eslint.config.mjs		eslint.config.mjs
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
postcss.config.js		postcss.config.js
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation

x402 Solana React Paywall

Classic theme

Solana theme

Seeker theme

Terminal theme

🚀 Features

📋 Prerequisites

📦 Installation

Install Peer Dependencies

⚙️ Setup

1. Import Styles

2. Environment Variables (Optional - Recommended for Production)

3. Wallet Provider Setup (Optional)

🎯 Quick Start

Simplest Example (Auto-Setup)

With Custom RPC (Recommended for Production)

🎨 Themes & Styling

Available Themes

Theme Example

Custom Styling

📚 API Reference

X402Paywall Props

🛠️ Development

Setup

Build

🐛 Troubleshooting

Common Issues

✅ Status

Features Complete

x402 v2 Protocol

🤝 Contributing

📄 License

🔗 Related Projects

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages