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