Building Miniapps with x402
This guide explains how to build miniapps that integrate x402 payments using our official template. The template provides a complete starting point with wallet integration, payment protection, and notifications already configured.
What are Miniapps?
Miniapps are lightweight applications that run inside Farcaster clients like TBA. Built with MiniKit, they provide a native app-like experience while leveraging the social graph and wallet capabilities of Farcaster. By integrating x402, your miniapp can accept instant USDC payments without requiring users to leave the app or manage complex payment flows.
Why x402 for Miniapps?
x402 is particularly well-suited for miniapps because:
- Seamless Payments: Users pay without leaving the miniapp experience
- No Account Setup: Works directly with connected wallets
- Instant Monetization: Builders can monetize their content or services directly
- Simple Integration: Payment protection with just middleware configuration
Prerequisites
Before starting, ensure you have:
- Node.js 18+ and pnpm v10 installed
- A Coinbase Developer Platform account and API keys (for mainnet)
- A wallet address to receive payments
Quick Start with the x402 Template
The fastest way to build an x402-powered miniapp is using our official template:
Template Features
The x402 miniapp template includes:
- Next.js App Router with TypeScript
- OnchainKit Integration for wallet connection
- x402 Payment Middleware for protected routes
- Farcaster Frame SDK for miniapp detection
- Notification System with Redis/Upstash
Project Structure
Environment Configuration
Create a .env.local
file with your configuration:
Required for x402 Payments
Frame Configuration (Auto-generated)
Run this command to generate Frame configuration:
This creates the necessary environment variables for:
- Frame metadata and account association
- Notification support via Redis/Upstash
- Mini app detection and integration
How the Template Works
1. Payment Middleware Setup
The middleware.ts
file configures x402 to protect API routes:
2. Protected API Endpoint
The /api/protected/route.ts
endpoint is automatically protected:
3. Frontend Integration
The main page demonstrates wallet connection and protected API calls:
4. Miniapp Detection
The template detects when running inside Farcaster:
Customizing the Template
Adding More Protected Routes
Update middleware.ts
to add new protected endpoints:
Implementing Notifications
The template includes notification support via Redis:
Customizing the UI
The template uses Tailwind CSS with a pixel theme. Modify theme.css
to customize:
Testing Your Miniapp
Local Development
-
Start your development server:
-
Open http://localhost:3000 in your browser
-
Test wallet connection and protected API calls
Testing in Farcaster
-
Use ngrok to expose your local server:
-
Update
NEXT_PUBLIC_URL
in.env.local
with your ngrok URL -
Cast your frame URL to test in Warpcast
-
Your miniapp will appear with the “Use App” button
Deployment
Production Checklist
- Set
NETWORK=base
for mainnet - Configure CDP API keys for mainnet settlement
- Update
RESOURCE_WALLET_ADDRESS
to your production wallet - Set proper
NEXT_PUBLIC_URL
for your domain - Test payment flows thoroughly on testnet first
- Configure Redis for production notifications
Best Practices
User Experience
- Clear Pricing: Always show prices before requiring payment
- Loading States: Show progress during payment processing
- Error Handling: Provide clear error messages and recovery options
- Success Feedback: Confirm successful payments immediately
Security
- Environment Variables: Never commit sensitive keys
- Server Validation: Always verify payments server-side
- Network Checking: Ensure users are on the correct network
- Rate Limiting: Consider adding rate limits to protected endpoints
Common Issues and Solutions
Payment Not Processing
Miniapp Not Detected
402 Errors Not Handled
Next Steps
- Explore the Template: Review all files in the example repository
- Customize for Your Use Case: Modify the template to fit your specific needs
- Add Your Features: Build on top of the payment foundation
- Deploy and Share: Launch your miniapp to the Farcaster community
Support
Start building your monetized Farcaster miniapp today with x402!