SolX402 - AI Agent Subscription Platform

Full-stack subscription platform using Solana devnet, x402 payment streaming, and Firebase Auth.

Features

• No Wallet Required: Users sign in with Google or phone OTP
• Ephemeral Wallets: Backend creates and manages Solana wallets
• Payment Streaming: x402 SDK for continuous subscription payments
• AI Agent Access: Pay-per-use agent with 402 Payment Required logic
• Beautiful UI: React + Tailwind CSS frontend
• Real-time Updates: Webhook integration for stream events

📁 Project Structure

SolX402/
├── backend/          # Node.js Express API
│   ├── config/       # Firebase & Solana configuration
│   ├── middleware/   # Auth middleware
│   ├── routes/       # API endpoints
│   ├── services/     # Business logic
│   └── scripts/      # Database seeding
├── frontend/         # React + Vite + Tailwind
│   └── src/
│       ├── components/  # Reusable components
│       ├── contexts/    # React contexts (Auth)
│       ├── pages/       # Page components
│       ├── services/    # API client
│       └── config/      # Firebase config
└── sdk/              # x402 SDK wrapper

🛠️ Setup

Prerequisites

• Node.js 18+
• Firebase project with Authentication enabled
• Solana wallet with devnet SOL (for funding)

Backend Setup

1. Install dependencies:

   cd backend
   npm install

2. Configure environment:

   cp .env.example .env

   Edit .env with your credentials:

   • Firebase service account
   • Solana devnet wallet private key
   • Encryption key: openssl rand -base64 32

3. Seed initial data:

   node scripts/seedPlans.js

4. Start server:

   npm run dev

   Server runs on http://localhost:5000

Frontend Setup

1. Install dependencies:

   cd frontend
   npm install

2. Configure environment:

   cp .env.example .env

   Edit .env with Firebase config

3. Start development server:

   npm run dev

   App runs on http://localhost:3000

📚 API Endpoints

Authentication

• POST /api/auth/profile - Save/update user profile
• GET /api/auth/profile - Get user profile

Wallets

• POST /api/wallets/create - Create ephemeral wallet
• GET /api/wallets - Get user wallet
• POST /api/wallets/fund - Fund wallet (devnet faucet)

Subscriptions

• GET /api/subscriptions/plans - List available plans
• POST /api/subscriptions/create - Create subscription with x402 stream
• GET /api/subscriptions - Get user subscriptions
• PATCH /api/subscriptions/:id/status - Update subscription status

Webhooks

• POST /api/x402/webhook - Handle x402 stream events

Agent

• POST /api/agent/task - Execute AI task (requires active subscription)
• GET /api/agent/status - Check agent availability

🎨 Frontend Pages

• Login - Firebase Auth with Google & phone OTP
• Plans - 3 subscription tiers with pricing
• Dashboard - Wallet balance, active subscriptions, payment history
• Agent - AI agent interface with payment status
• Subscribe Modal - 3-step flow: Create wallet → Fund → Subscribe

🔧 SDK Usage

import SolX402 from './sdk';
import { Keypair, PublicKey } from '@solana/web3.js';

const x402 = new SolX402({ network: 'devnet' });

// Create payment stream
const stream = await x402.createStream({
  fromWallet: userKeypair,
  toWallet: providerPublicKey,
  ratePerSecond: 0.0001,
  duration: null, // Indefinite
});

// Manage stream
await x402.pauseStream(stream.streamId, userKeypair);
await x402.resumeStream(stream.streamId, userKeypair);
await x402.cancelStream(stream.streamId, userKeypair);

🔐 Security

• Private keys encrypted with AES-256
• Firebase token validation on protected routes
• Webhook secret verification
• Environment-based configuration
• No client-side private key exposure

🚧 Development Notes

• x402 SDK integration is simulated for demo purposes
• Replace with actual x402 SDK when available
• Faucet mode for devnet funding
• All payments use Solana devnet

📝 License

MIT

🤝 Contributing

Contributions welcome! Please open an issue or PR.