A blockchain-based payment gateway for automated services using the X-402 protocol on Solana.
Billz is a pay-per-use automation platform that allows users to pay for and execute automated tasks using USDC cryptocurrency on the Solana blockchain. It implements the X-402 payment protocol (similar to HTTP 402 "Payment Required") to gate access to services behind verified on-chain payments.
- No subscriptions - Pay only for what you use
- Instant payments - Blockchain-powered micropayments
- Auto refunds - Failed jobs trigger automatic refunds
- Trustless - All payments verified on-chain
- Extensible - Easy to add new automation services
- Blockchain Payments: Accept USDC payments on Solana for automated services
- X-402 Protocol: Industry-standard payment-required HTTP protocol
- Automated Refunds: Failed jobs automatically trigger refunds to users
- Job Queue System: Background processing with retry logic
- Wallet Integration: Seamless Phantom wallet integration
- Multiple Automations: Extensible system for various paid services
Billz consists of three core processes:
- billz-web - Next.js frontend and API server
- billz-queue - Background worker for executing automation jobs
- billz-refund - Automated refund processor for failed jobs
| Automation | Price | Description |
|---|---|---|
| CS Skin Scraper | $2.50 | Scrape CS skin prices from 20+ websites |
| Email Automation | $0.50 | Automated email workflow |
- User Requests Service: Client makes API call without payment
- 402 Response: Server responds with payment requirements
- Payment Submission: Client signs and submits USDC transaction
- Verification: Server verifies payment on-chain
- Job Queued: Execution job added to background queue
- Processing: Worker picks up job and executes with 3 retry attempts
- Settlement: On success, payment is settled; on failure, refund is initiated
Get started in 10 minutes:
# 1. Clone the repository
git clone https://github.com/sahilparikh03/billz.git
cd billz
# 2. Install dependencies
npm install
# 3. Set up environment variables
cp .env.local.example .env.local
# Edit .env.local with your configuration
# 4. Set up database
npm run db:generate
npm run db:push
# 5. Start development server
npm run devOpen http://localhost:3000 and connect your Phantom wallet!
For detailed setup instructions, see QUICKSTART.md.
- Node.js 18+
- MongoDB database (MongoDB Atlas or local)
- Solana wallet with USDC (Phantom recommended)
- N8N instance (for automation workflows)
- Git
Create a .env.local file with the following:
# Network Configuration
NEXT_PUBLIC_NETWORK=solana-devnet # or solana for mainnet
NETWORK=solana
# USDC Token Addresses
USDC_MINT_ADDRESS=4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU # Devnet for testing
# Backend Configuration
NEXT_PUBLIC_API_URL=http://localhost:3000
TREASURY_WALLET_ADDRESS=your_treasury_wallet_address_here
# Solana RPC
SOLANA_RPC_URL=https://api.devnet.solana.com
# Database (MongoDB)
DATABASE_URL="mongodb://localhost:27017/billz"
# N8N Configuration
N8N_BASE_URL=http://localhost:5678
# Optional: Automated refunds (⚠️ hot wallet risk)
# OPERATIONAL_WALLET_PRIVATE_KEY=your_base64_encoded_private_keyFor a complete example, see .env.local.example.
# Install dependencies
npm install
# Setup database
npx prisma generate
npx prisma db push
# Build the application
npm run build# Start the web server
npm run dev# Start all three processes
pm2 start ecosystem.config.js
# View logs
pm2 logs
# Stop all processes
pm2 stop all# Terminal 1: Web server
npm start
# Terminal 2: Job queue worker
node --loader ts-node/esm ./lib/job-queue.ts
# Terminal 3: Refund processor
node --loader ts-node/esm ./lib/refund-processor.tsbillz/
├── app/
│ ├── api/
│ │ ├── execute-automation/ # Main payment & execution endpoint
│ │ ├── job/[jobId]/status/ # Job status polling endpoint
│ │ └── health/ # Health check for monitoring
│ ├── layout.tsx # Root layout with wallet provider
│ ├── page.tsx # Landing page
│ └── globals.css # Global styles
├── components/
│ ├── WalletProvider.tsx # Solana wallet setup
│ └── ExecuteAutomationButton.tsx # Smart execution button
├── lib/
│ ├── x402-handler.ts # Server-side payment handler
│ ├── x402-client.ts # Client-side payment client
│ ├── job-queue.ts # Background job processor
│ ├── refund-processor.ts # Automated refund system
│ ├── n8n-client.ts # N8N workflow integration
│ └── database.ts # Prisma client
├── prisma/
│ └── schema.prisma # MongoDB schema
├── README.md # This file
├── QUICKSTART.md # Quick setup guide
├── DEPLOYMENT.md # Production deployment guide
└── .env.local.example # Example environment variables
The system uses Prisma with MongoDB:
- Payment: Stores payment records with verification data and refund tracking
- Execution: Tracks job status (pending → running → completed/failed)
View the full schema in prisma/schema.prisma.
Edit lib/x402-handler.ts and add to the AUTOMATION_PRICING object:
export const AUTOMATION_PRICING = {
'your-automation-id': {
name: 'Your Automation Name',
priceUSDC: 1.00,
priceAtomicUnits: '1000000', // Price in micro-units (6 decimals)
description: 'What your automation does',
},
// ... existing automations
} as const;- The treasury wallet receives all payments
- Use a secure wallet (hardware wallet recommended for mainnet)
- Only the public address is needed for receiving payments
- High Risk: Requires private key stored on server
- Used for automated refunds
- Consider manual refunds for mainnet to avoid hot wallet risk
- If using automated refunds, encrypt private key and use dedicated operational wallet
- Start on devnet for testing
- Use environment variables for all sensitive data
- Never commit private keys to version control
- Set reasonable
maxPaymentAmountlimits in client - Monitor refund queue for suspicious activity
Execute a paid automation
Request:
{
"automationId": "cs-skin-scraper",
"params": {}
}Response (202 Accepted):
{
"success": true,
"jobId": "job_123",
"status": "pending",
"statusUrl": "/api/job/job_123/status"
}Check job execution status
Response:
{
"status": "completed",
"result": { /* automation results */ }
}- Ensure treasury wallet address is correct
- Check network matches (devnet vs mainnet)
- Verify USDC mint address is correct for network
- Ensure job queue worker is running
- Check worker logs for errors
- Verify N8N integration is configured
- Check refund processor is running
- Verify operational wallet has sufficient SOL for gas
- Check operational wallet has USDC balance for refunds
- Frontend: Next.js 14, React 18, TailwindCSS
- Blockchain: Solana Web3.js, SPL Token
- Wallet: Solana Wallet Adapter (Phantom)
- Payment Protocol: X-402 (x402-solana)
- Database: MongoDB with Prisma ORM
- Automation: N8N workflows
- Process Management: PM2
- Language: TypeScript
- QUICKSTART.md - Get running locally in 10 minutes
- DEPLOYMENT.md - Production deployment guide
- .env.local.example - Example environment configuration
Contributions are welcome! Please:
- Fork the repository
- Create a 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
- Support for multiple cryptocurrencies (SOL, other SPL tokens)
- Dashboard for tracking automation history
- Webhook notifications for job completion
- API key authentication for programmatic access
- Multi-wallet support (Solflare, Backpack, etc.)
- Analytics and usage metrics
- Treasury wallet uses public address only (no private key on server)
- Payment verification happens on-chain
- All environment variables should be kept secure
- Consider manual refunds for production (avoid hot wallet risk)
For security issues, please email security@yourdomain.com (do not open public issues).
[Add your license here - MIT recommended]
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Twitter: @yourusername
Built with:
- Solana - High-performance blockchain
- N8N - Workflow automation
- Next.js - React framework
- Prisma - Database ORM
Made with ❤️ for the Solana ecosystem