pop402 Example Demos

A collection of example applications demonstrating pop402 challenge-response authentication with Solana USDC payments.

🌐 Live Demo

https://pop402.com/gallery

About pop402

pop402 is a payment protocol that brings HTTP 402 (Payment Required) to life. It enables seamless micropayments for digital content and services on the web, leveraging blockchain payments with challenge-response authentication.

The protocol uses a facilitator service to coordinate authentication and license management:

• Facilitator: https://facilitator.pop402.com
• Documentation: https://pop402.com

Key Features

• ⚡ Instant micropayments using USDC on Solana
• 🔐 Secure challenge-response authentication
• 📜 Flexible licensing models (permanent, time-based, usage-based)
• 🚀 Simple integration with existing web apps
• 💰 No subscriptions - pay only for what you use

Demo Applications

This repository showcases three different licensing models supported by pop402:

1. 📸 Paywalled Image Gallery - Permanent License

• Price: $0.01 USDC per image
• Model: One-time purchase, unlimited access
• Use Case: Digital content, photos, artwork
• Buy once, access forever. Perfect for digital goods.

2. 💬 Paid Chat Room - Time-Based License

• Price: $0.001 USDC = 1 minute access
• Model: Duration-based access with countdown timer
• Use Case: Premium communities, temporary access
• Pay for time-limited access to chat and send messages.

3. 📝 Social Feed - Usage-Based License

• Price: $0.05 USDC = 5 posts
• Model: Credit/quota system
• Use Case: Forums, social platforms, API calls
• Purchase credits, each action decrements your remaining count.

Coming Soon

• 🎥 Video Streaming
• 📦 File Downloads

Technical Features

• ⚡ Instant Payments: USDC on Solana mainnet
• 🔐 Secure Auth: Challenge-response via pop402 facilitator
• 💼 Wallet Integration: Phantom wallet support
• 🛡️ Protected Routes: @pop402/x402-express middleware
• 🎯 License Tracking: Real-time usage/expiration from facilitator API
• 📱 Responsive UI: Works on desktop and mobile

Quick Start

Prerequisites

• Node.js 18+
• Phantom wallet browser extension
• Some SOL and USDC on Solana mainnet (for testing purchases)

Installation

# Clone the repository
git clone <repo-url>
cd www-pop402-example

# Install dependencies
npm install

# Copy environment example
cp env.example .env

Configuration

Edit .env and set your merchant wallet address:

FACILITATOR_URL=https://facilitator.pop402.com
NETWORK=solana
MERCHANT_WALLET=YourSolanaWalletAddress
PORT=3000

Note: Set MERCHANT_WALLET to your Solana wallet address where you want to receive USDC payments.

Run the Application

npm start

Navigate to http://localhost:3000 and connect your Phantom wallet to start testing!

How It Works

Architecture Overview

┌─────────────┐      ┌──────────────────┐      ┌─────────────────┐
│   Browser   │◄────►│  Express Server  │◄────►│   Facilitator   │
│  (Phantom)  │      │  (x402-express)  │      │  (pop402.com)   │
└─────────────┘      └──────────────────┘      └─────────────────┘
      │                       │                         │
      │                       │                         │
   Wallet             Protected Routes          Auth & Licenses
 Transactions         Payment Verify           Usage Tracking

Payment Flow

1. Connect Wallet: User connects Phantom wallet
2. Authentication: Auto-signs challenge from facilitator
3. Check License: Frontend queries facilitator for existing licenses
4. Display Content: Show locked/unlocked state based on license
5. Purchase: User clicks to buy
   • Frontend builds USDC transaction
   • User approves in Phantom
   • Backend verifies payment with facilitator
   • Content unlocks instantly
6. Track Usage: Facilitator tracks time/usage limits

Code Structure

Backend (server/index.js)

• Express server with @pop402/x402-express middleware
• Protected routes for images, chat, and feed
• Proxies challenge requests to facilitator
• Verifies payments and enforces licenses

Frontend (public/)

• core.js - Wallet connection, authentication, shared state
• images.js - Image gallery (permanent licenses)
• chat.js - Chat room (time-based licenses)
• feed.js - Social feed (usage-based licenses)

Facilitator Integration

• License checking: POST https://facilitator.pop402.com/license
• Challenge generation: POST https://facilitator.pop402.com/challenge
• Real-time usage tracking from facilitator API

Environment Variables Reference

Variable	Default	Description
FACILITATOR_URL	https://facilitator.pop402.com	pop402 facilitator endpoint
NETWORK	solana	Blockchain network (currently only Solana supported)
MERCHANT_WALLET	(required)	Your Solana wallet address for receiving payments
PORT	3000	Server port

Resources

• 🌐 Live Demo: https://pop402.com/gallery
• 📚 Documentation: https://pop402.com
• 🔧 Facilitator API: https://facilitator.pop402.com
• 📦 NPM Package: @pop402/x402-express
• 💬 Discord: Join the pop402 community
• 🐦 Twitter: @pop402

Contributing

Contributions are welcome! This repository serves as example implementations of the pop402 protocol. Feel free to:

• Report bugs or issues
• Suggest new demo ideas
• Submit pull requests with improvements
• Share your own pop402 implementations

License

MIT