A production-ready, per-article paywall system using the x402 protocol and Solana micropayments. No subscriptions needed — readers pay only for what they want to read.
Building a robust crypto payment system is hard. We made it 10x easier.
- 🚀 Save 100+ Hours — Don't reinvent the wheel. We handled the edge cases, wallet connections, and verification logic.
- 🛡️ Bank-Grade Security — Implements the full x402 standard with server-side validation and anti-replay protection.
- 🧩 Plug & Play — Drop-in React components and Next.js middleware. Get running in minutes, not weeks.
- 📱 Mobile Optimized — Built-in Solana Pay QR support for seamless mobile wallet payments.
Turn any content into paid content with one-time micropayments on Solana. No subscriptions, no recurring charges—just pay to unlock.
| Feature | Description |
|---|---|
| 💰 SOL & USDC Payments | Native SOL and SPL tokens (USDC, USDT) |
| 🔐 x402 Protocol | Full HTTP 402 compliance with X-Payment-Required headers |
| 🔑 JWT Sessions | Secure unlock tracking with anti-replay |
| 🛡️ Signature Store | Prevent double-spend at app layer |
| 🔌 Express & Next.js | Zero-boilerplate middleware |
| 💵 Price Conversion | USD↔SOL with multi-provider fallback |
| 🌳 Tree-Shakeable | Import only what you need |
| 🔄 RPC Fallback | Automatic failover on RPC errors |
| ⚡ Priority Fees | Land transactions faster |
| 📦 Versioned Tx | Full v0 transaction support |
- Node.js 18+
- npm or yarn
- A Solana wallet (Phantom, Solflare, etc.)
- An RPC URL (Tatum, Helius, QuickNode, etc.)
# Clone the repository
git clone https://github.com/AlleyBo55/micropay-solana-x402-paywall.git
cd solanapaywall
# Install dependencies
npm install
# Copy environment template
cp .env.example .env.local
# Edit .env.local with your configuration
nano .env.local# Network Configuration
NEXT_PUBLIC_SOLANA_NETWORK=devnet
# RPC Configuration (See "Flexible RPC Providers" below)
NEXT_PUBLIC_RPC_URL=https://api.devnet.solana.com
# Optional: Enable automatic fallback
ENABLE_RPC_FALLBACK=true
FALLBACK_RPC_URLS=https://api.devnet.solana.com,https://devnet.helius-rpc.com/your-key
# Payment Configuration
CREATOR_WALLET_ADDRESS=your_solana_wallet_address
# Session Configuration (JWT)
SESSION_SECRET=your_32_character_minimum_secret_key
SESSION_DURATION_HOURS=24This project is compatible with any Solana RPC provider. While the demo references Tatum.io for its free tier, you can use high-performance nodes from any provider:
- Helius — Specialized Solana RPCs & APIs
- QuickNode — Enterprise-grade infrastructure
- Tatum — Multi-chain developer platform
- Alchemy — Reliable blockchain infrastructure
- GenesysGo — Shadow generic RPCs
In packages/lib/src/config.ts or via environment variables, you can set your primary and fallback options:
const config = {
network: 'mainnet-beta',
// Primary RPC (e.g. Helius)
rpcUrl: 'https://mainnet.helius-rpc.com/?api-key=...',
// Enable automatic fallback
enableFallback: true,
fallbackRpcUrls: [
'https://api.mainnet-beta.solana.com', // Public node (rate limited but free)
'https://solana-mainnet.gateway.tatum.io/...'
]
};┌─────────────────────────────────────────────────────────────┐
│ USER'S BROWSER │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. User visits /article/premium-content │
│ │ │
│ ▼ │
│ 2. Server checks session → Not unlocked │
│ │ │
│ ▼ │
│ 3. Page renders with blurred content + paywall overlay │
│ │ │
│ ▼ │
│ 4. User clicks "Unlock" → Connects wallet │
│ │ │
│ ▼ │
│ 5. User signs transaction → SOL sent to creator │
│ │ │
│ ▼ │
│ 6. Frontend sends signature to /api/payment/verify │
│ │ │
│ ▼ │
│ 7. Server verifies on-chain → Creates session cookie │
│ │ │
│ ▼ │
│ 8. Content unlocks! Access valid for 24 hours │
│ │
└─────────────────────────────────────────────────────────────┘
Experience autonomous AI agent payments in action! The Agent Chat Demo showcases an AI agent that autonomously pays for premium API access using x402 micropayments on Solana.
cd packages/demo
npm install
npm run dev
# Visit http://localhost:3001/agent-chat| Feature | Description |
|---|---|
| 🧠 AI Agent | Chat with an agent that can pay for premium features |
| 💳 Autonomous Payments | Agent pays SOL micropayments without human interaction |
| 🔄 Live Streaming | Watch payment steps in real-time during chat |
| 📊 Premium Content | Premium queries trigger actual Devnet payments |
- User asks a free question → Agent responds normally
- User asks for "premium crypto analysis" → Agent detects premium request
- Agent autonomously pays 0.002 SOL via x402 protocol
- Payment confirmed on-chain → Premium content delivered
- All steps shown transparently in chat UI
# Generate a new keypair
node -e "console.log(require('@solana/web3.js').Keypair.generate().secretKey.toString())"
# Add to .env.local
AGENT_KEYPAIR_SECRET=<comma-separated-bytes>
# Fund on Devnet
solana airdrop 2 <agent-address> --url devnetAdd these variables in your Vercel project settings:
| Variable | Description |
|---|---|
NEXT_PUBLIC_SOLANA_NETWORK |
devnet or mainnet-beta |
NEXT_PUBLIC_RPC_URL |
Your RPC URL (Tatum, Helius, etc.) |
CREATOR_WALLET_ADDRESS |
Your Solana wallet |
SESSION_SECRET |
Random 32+ char string |
SESSION_DURATION_HOURS |
24 (default) |
DEFAULT_ARTICLE_PRICE_LAMPORTS |
10000000 (0.01 SOL) |
solanapaywall/
├── src/
│ ├── app/
│ │ ├── api/
│ │ │ ├── payment/verify/ # Payment verification endpoint
│ │ │ └── session/validate/ # Session validation endpoint
│ │ ├── article/[slug]/ # Dynamic article pages
│ │ ├── dashboard/ # Creator dashboard
│ │ ├── layout.tsx # Root layout with providers
│ │ └── page.tsx # Landing page
│ ├── components/
│ │ ├── article/ # Article content renderer
│ │ ├── paywall/ # Paywall overlay & modal
│ │ └── providers/ # Wallet provider context
│ ├── config/
│ │ └── articles.ts # Demo article configuration
│ ├── lib/
│ │ ├── session/ # JWT session management
│ │ ├── solana/ # Solana client & verification
│ │ └── x402/ # x402 protocol helpers
│ └── types/ # TypeScript type definitions
├── .env.example # Environment template
├── vercel.json # Vercel deployment config
└── README.md # This file
We take security seriously. Here's why you can trust this library:
-
Zero-Trust Verification
We never trust the client. All payment signatures are verified on-chain (or via high-performance RPCs) by your backend before issuing access tokens. -
Anti-Replay Protection
We implement a Signature Store (Redis/Memory) to ensure every transaction signature can only be used ONCE. This prevents "replay attacks" where a user tries to use the same payment proof multiple times. -
Stateless JWT Sessions
Access is granted via signed HTTP-only cookies. No database required for session management. The proof of payment is cryptographically sealed in the token. -
No Private Keys Stored
The library is designed to be non-custodial for the payment flow. User wallets sign transactions directly. Your server only needs a public key to verify.
- ✅ No hardcoded private keys
- ✅ Session cookies are HTTP-only and secure
- ✅ On-chain verification for all payments
- ✅ Environment variables for sensitive config
- ✅ CORS headers configured properly
Caution
SPL Token Validation Note: The library currently validates that tokens are sent to a valid token account, but does not perform the extra RPC call to verify that token account is owned by expectedRecipient. For high-value transactions, we recommend implementing a strict verification step server-side.
- Fork the repository
- Create your feature branch:
git checkout -b feature/amazing-feature - Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
MIT License - see LICENSE for details.
Built with ❤️ using x402 Protocol on Solana