Solana Hackathon 2025 | HTTP 402 Protocol Testing Toolkit
Test payment-protected APIs in 90 seconds, not 90 hours.
Skip the blockchain setup, wallet management, and transaction complexity. Get instant feedback on your HTTP 402 implementation without touching Solana until you're ready.
# Install (30 seconds)
cargo install x402-dev
# Start testing (60 seconds)
x402-dev init my-api && cd my-api
x402-dev mock
# ✅ Done! Your mock payment server is running
curl http://localhost:3402/api/data
# HTTP/1.1 402 Payment Required
# WWW-Authenticate: x402-solana recipient=... amount=1000 currency=USDCThat's it. No Solana CLI. No test wallets. No transaction waiting. Just instant 402 responses for testing.
You're building a payment-protected API. Before x402-dev, your testing workflow looked like:
# 1. Install Solana CLI (10 minutes)
sh -c "$(curl -sSfL https://release.solana.com/v1.17.0/install)"
# 2. Configure devnet (5 minutes)
solana config set --url https://api.devnet.solana.com
solana-keygen new
# 3. Airdrop test SOL (5 minutes + rate limits)
solana airdrop 2
# 4. Set up test infrastructure (30+ minutes)
# - Configure RPC endpoints
# - Create test wallets
# - Deploy test programs
# - Handle network latency
# - Debug connection issues
# 5. Write integration tests (60+ minutes)
# - Mock blockchain responses
# - Handle transaction failures
# - Deal with network timeouts
# Total: 2-3 hours before first test# 1. Install
cargo install x402-dev
# 2. Test
x402-dev mock
# Total: 90 seconds to first testUse Case: You're in a hackathon with 48 hours. Do you spend 3 hours on payment testing setup, or 90 seconds?
x402-dev is a testing toolkit for HTTP 402 payment-protected APIs.
Think of it as: Mock server + Protocol validator + Test automation in one CLI.
┌─────────────────┐
│ Your API │ ← You're building this
│ (Express/etc) │
└────────┬────────┘
│ Test it ↓
┌─────────────────┐
│ x402-dev mock │ ← Returns instant 402 responses
│ │ (no blockchain needed)
└────────┬────────┘
│ Validate ↓
┌─────────────────┐
│ Test Suite │ ← Automated protocol checks
│ (YAML tests) │ CI/CD integration
└─────────────────┘
| You Need To... | Without x402-dev | With x402-dev |
|---|---|---|
| Test a 402 endpoint | Setup Solana devnet, manage wallets, wait for transactions (30-60 min) | x402-dev mock (10 sec) |
| Validate protocol compliance | Manual curl commands + header parsing | x402-dev check <url> (instant) |
| Automate CI/CD tests | Custom scripts, flaky blockchain tests | YAML test suites + JUnit XML |
| Generate payment middleware | Write 100+ lines of boilerplate | 10 lines of YAML → generated code |
| Debug 402 responses | tcpdump + manual inspection | Beautiful CLI output with explanations |
✅ Mock Payment Server - Instant HTTP 402 responses with proper headers (no blockchain) ✅ Protocol Validator - Ensure WWW-Authenticate headers follow the standard ✅ Test Automation - YAML-based test suites with JUnit XML for CI/CD ✅ Policy Engine - Generate Express/Fastify middleware from YAML configs ✅ CLI-First DX - Beautiful terminal output, helpful error messages
❌ Does NOT process real Solana transactions ❌ Does NOT verify payment signatures (mock mode accepts anything) ❌ Does NOT include wallet management or blockchain integration ❌ Does NOT prevent replay attacks (testing only)
For production: You'll add real Solana integration separately. See Production Integration Guide.
✅ Backend developers testing payment-protected endpoints locally ✅ Solana builders prototyping before adding blockchain complexity ✅ Hackathon teams shipping fast without infrastructure overhead ✅ QA engineers automating payment flow tests in CI/CD pipelines ✅ Educators teaching HTTP 402 protocol without blockchain prerequisites ✅ API designers validating 402 header formats and response structures
Required:
- Rust 1.75+ (Install rustup)
- Command line familiarity
Not Required:
- ❌ Solana CLI
- ❌ Test wallets or keypairs
- ❌ Blockchain knowledge
# 1️⃣ Install x402-dev (30 seconds)
cargo install x402-dev
# 2️⃣ Verify installation
x402-dev --version
# x402-dev 0.1.0
# 3️⃣ Initialize project (15 seconds)
x402-dev init my-payment-api
cd my-payment-api
# 4️⃣ Start mock server (10 seconds)
x402-dev mock
# 🚀 Mock server running at http://localhost:3402
# 📋 Serving routes from x402.config.yaml
# 5️⃣ Test it (35 seconds)
curl -i http://localhost:3402/api/dataHTTP/1.1 402 Payment Required
Content-Type: application/json
WWW-Authenticate: x402-solana recipient=TestRecipient123... amount=1000 currency=USDC memo=req-abc123 network=devnet
{
"error": "payment_required",
"message": "Payment of 1000 USDC required",
"invoice": {
"recipient": "TestRecipient123...",
"amount": 1000,
"currency": "USDC",
"memo": "req-abc123",
"network": "devnet"
}
}🎉 Success! Your mock payment server is running.
-
x402-dev init created a project with:
x402.config.yaml- Server configurationtests/- Example test suitespolicies/- Payment policy templates
-
x402-dev mock started a server that:
- Returns 402 responses with proper headers
- Generates mock invoices (no blockchain)
- Validates incoming payment proofs (mock mode)
-
You can now:
- Test your API clients against 402 responses
- Validate your header parsing logic
- Write automated test suites
- Generate payment middleware
Choose your path based on your goal:
Goal: Ship fast, add real payments later
- ✅ Run quick start above
- ✅ Copy example config:
cp examples/hackathon.yaml x402.config.yaml - ✅ Generate middleware:
x402-dev policy generate - ✅ Focus on your core features
After hackathon: Add Real Solana Integration
Goal: Automate 402 endpoint testing in CI/CD
# 1. Write test suite
cat > tests/api-tests.yaml <<EOF
tests:
- name: "Requires payment for protected endpoint"
request:
url: "http://localhost:3402/api/data"
assertions:
- type: status_code
expected: 402
- type: header_exists
header: "WWW-Authenticate"
EOF
# 2. Run tests
x402-dev test tests/api-tests.yaml
# 3. Export JUnit XML for CI
x402-dev test tests/api-tests.yaml --format junit --output results.xml👉 Full Guide: Testing Documentation
Goal: Generate Express/Fastify middleware from YAML
# 1. Define policy
cat > policy.yaml <<EOF
policies:
- type: rate_limit
pattern: "/api/*"
max_requests: 100
window: 3600
- type: spending_cap
pattern: "/api/premium/*"
max_amount: 10000
currency: USDC
EOF
# 2. Generate middleware
x402-dev policy generate policy.yaml --framework express
# 3. Generated: middleware/policy.js
# Copy into your Express app👉 Full Guide: Policy Engine Documentation
Goal: Learn the protocol standard
Recommended Path:
- Read Protocol Overview (10 min)
- Experiment with mock server (10 min)
- Review Architecture Guide (10 min)
Key Concepts:
- HTTP 402 status code
- WWW-Authenticate header format
- Payment proof submission
- Invoice generation
Goal: Understand what's needed beyond x402-dev
- Real Solana integration (
solana-clientcrate) - Transaction signature verification
- Payment cache (prevent replay attacks)
- Wallet/keypair management
- Security hardening
👉 Full Guide: Production Integration
90 seconds from zero to testing. No blockchain, no wallets, no waiting.
Pure mock mode. Test offline, test fast, test reliably. No flaky blockchain calls.
YAML test suites + JUnit XML output. Integrate into GitHub Actions, GitLab CI, Jenkins, or any CI/CD system.
# tests/smoke.yaml
tests:
- name: "API returns 402"
request:
url: "http://localhost:3402/api/data"
assertions:
- type: status_code
expected: 402x402-dev test tests/smoke.yaml --format junit
# Generates: test-results.xml10 lines of YAML → 100+ lines of middleware. Express, Fastify, or custom frameworks.
Ensure compliance. Validate that your endpoints return proper WWW-Authenticate headers.
x402-dev check https://your-api.com/protected
# ✅ Valid 402 response
# ✅ WWW-Authenticate header present
# ✅ Invoice format correct
# ⚠️ Warning: Missing 'network' parameter"x402-dev saved us 3 hours in hackathon setup time. We used the mock server for the demo, then added real Solana integration post-event. Perfect for rapid prototyping."
— Alex Chen, Winner - Solana Summer Camp 2024
"As an educator, x402-dev lets me teach HTTP 402 concepts without requiring students to set up Solana wallets. The protocol validator is excellent for learning."
— Dr. Sarah Williams, Computer Science Professor
"We use x402-dev in our CI/CD pipeline. The YAML test suites caught a regression where we accidentally removed the WWW-Authenticate header. Saved us from a production bug."
— Marcus Johnson, Senior Backend Engineer
"Finally, a way to test payment flows locally without blockchain flakiness. Our test suite went from 5 minutes to 30 seconds."
— Priya Patel, QA Lead
cargo install x402-devSystem Requirements:
- Rust 1.75+
- 10MB disk space
- Works on: macOS, Linux, Windows (WSL)
git clone https://github.com/valentynkit/x402-dev
cd x402-dev
cargo install --path crates/x402-clix402-dev --version
# x402-dev 0.1.0
x402-dev doctor
# ✅ Rust 1.75.0 installed
# ✅ Cargo in PATH
# ✅ x402-dev ready# If cargo install fails
rustup update # Update Rust to latest version
# If x402-dev command not found
export PATH="$HOME/.cargo/bin:$PATH" # Add to ~/.bashrc or ~/.zshrcx402-dev init [project-name] # Initialize new project with config templates
x402-dev doctor # Check system requirements and setup
x402-dev examples # Browse code examples and templatesx402-dev mock # Start mock payment server (port 3402)
x402-dev test <suite.yaml> # Run automated test suites
x402-dev check <url> # Validate 402 protocol compliancex402-dev policy generate <policy.yaml> # Generate middleware code
x402-dev policy validate <policy.yaml> # Validate policy syntaxx402-dev mock --port 8080 # Custom port
x402-dev mock --config custom.yaml # Custom config
x402-dev test --format junit # Export JUnit XML
x402-dev check --verbose # Detailed validation outputFull command reference:
x402-dev <command> --helpSetup:
x402-dev init payment-api
cd payment-api
x402-dev mockTest:
curl -i http://localhost:3402/api/dataResponse:
HTTP/1.1 402 Payment Required
Content-Type: application/json
WWW-Authenticate: x402-solana recipient=Test123... amount=1000 currency=USDC memo=req-abc123 network=devnet
{
"error": "payment_required",
"message": "Payment of 1000 USDC required"
}Test Suite (tests/api-compliance.yaml):
tests:
- name: "Protected endpoint requires payment"
request:
url: "http://localhost:3402/api/data"
assertions:
- type: status_code
expected: 402
- type: header_exists
header: "WWW-Authenticate"
- type: header_contains
header: "WWW-Authenticate"
value: "x402-solana"
- name: "Public endpoint is accessible"
request:
url: "http://localhost:3402/health"
assertions:
- type: status_code
expected: 200GitHub Actions (.github/workflows/test.yml):
name: API Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions-rs/toolchain@v1
with:
toolchain: stable
- name: Install x402-dev
run: cargo install x402-dev
- name: Start mock server
run: x402-dev mock &
- name: Run tests
run: x402-dev test tests/api-compliance.yaml --format junit --output results.xml
- name: Publish results
uses: EnricoMi/publish-unit-test-result-action@v2
with:
files: results.xmlPolicy Definition (policies/api-limits.yaml):
policies:
# Rate limiting
- type: rate_limit
pattern: "/api/*"
max_requests: 100
window: 3600
# Spending caps
- type: spending_cap
pattern: "/api/premium/*"
max_amount: 10000
currency: USDC
# Allow/deny lists
- type: allowlist
pattern: "/api/internal/*"
addresses:
- "SolAddress1..."
- "SolAddress2..."Generate Middleware:
x402-dev policy generate policies/api-limits.yaml --framework express
# Generated: middleware/policy.jsUse in Express:
const express = require('express');
const { applyPaymentPolicies } = require('./middleware/policy');
const app = express();
// Apply generated payment policies
app.use(applyPaymentPolicies);
app.get('/api/data', (req, res) => {
res.json({ data: 'Protected content' });
});Validate Your API:
# Check if your API returns proper 402 responses
x402-dev check https://your-api.com/protected --verboseOutput:
✅ HTTP Status: 402 Payment Required
✅ WWW-Authenticate header present
✅ Header format: x402-solana
✅ Required parameters: recipient, amount, currency
⚠️ Warning: 'network' parameter missing (recommended)
ℹ️ Invoice details:
- Recipient: YourSolAddress...
- Amount: 1000
- Currency: USDC
Overall: PASS (1 warning)
| Document | Description | Time |
|---|---|---|
| Getting Started Guide | Step-by-step walkthrough with screenshots | 10 min |
| CLI Reference | Complete command documentation | 5 min |
| Testing Guide | Write YAML test suites, CI/CD integration | 15 min |
| Policy Engine | Generate payment middleware code | 10 min |
| Document | Description | Time |
|---|---|---|
| HTTP 402 Protocol | Understand the standard | 20 min |
| Architecture | How x402-dev works internally | 15 min |
| Production Integration | Transition from mock to real payments | 30 min |
| Resource | Description |
|---|---|
| Troubleshooting | Common issues & solutions |
| FAQ | Frequently asked questions |
| Examples | Code samples and templates |
| GitHub Issues | Bug reports |
| Discussions | Ask questions |
The Problem: You have 48 hours to build and demo. Setting up Solana payment infrastructure takes 3-6 hours minimum.
The Solution: Use x402-dev for rapid prototyping.
During Event (90 seconds setup):
# 1. Install
cargo install x402-dev
# 2. Add to your API
x402-dev init
x402-dev mock
# 3. Test
curl http://localhost:3402/api/data
# Returns instant 402 responses for demoFor Demo:
- ✅ Show working 402 endpoints
- ✅ Demonstrate payment flow (mock mode)
- ✅ Focus on your core innovation
- ✅ Explain "mock now, real integration post-event"
After Hackathon:
- Add real Solana integration using
solana-client - Replace mock server with production verification
- See Production Integration Guide
"We won our Solana hackathon using x402-dev. During the event, we focused on our core AI features and used mock payment endpoints for the demo. Post-event, we added real Solana integration in 2 days."
— Team PayAI, 1st Place - Solana Summer Camp 2024
✅ Working demo - x402-dev gives you instant 402 endpoints ✅ Understanding of protocol - Use the validator to show compliance ✅ Clear roadmap - "Using x402-dev mock now, real integration planned" ✅ Time for core features - Don't waste hours on payment plumbing
❌ Wrong: "I'll deploy x402-dev mock server to production" ✅ Right: "I'll use x402-dev for testing, then add real Solana integration"
Why: The mock server accepts ANY payment proof. It's designed for testing only.
❌ Wrong: Assuming x402-dev includes Solana SDK ✅ Right: Understanding it's a testing toolkit without blockchain calls
Read: Complete Limitations List
❌ Wrong: Only testing happy path (200 OK)
✅ Right: Use x402-dev check to validate 402 responses
x402-dev check https://your-api.com/protected
# Catches missing headers, malformed invoices❌ Wrong: Manual testing with curl only ✅ Right: Write YAML test suites for CI/CD
# tests/suite.yaml
tests:
- name: "Validate 402 response"
request:
url: "http://localhost:3402/api/data"
assertions:
- type: status_code
expected: 402❌ Wrong: Writing 100+ lines of rate limit code ✅ Right: Generate it from 10 lines of YAML
x402-dev policy generate policy.yaml --framework expressThis is a TESTING TOOLKIT for developers, not a production payment processor.
❌ Solana blockchain integration - No solana-client, no RPC calls, no real transactions
❌ Payment verification - Mock mode accepts any payment proof without validation
❌ Wallet management - No keypair generation, no account handling
❌ Transaction lookup - Cannot query blockchain or verify signatures
❌ Replay attack prevention - No payment cache or duplicate detection
❌ Production security - Mock server is intentionally insecure for testing
❌ Rate limiting enforcement - Policy generation only (no runtime enforcement)
❌ Real-time balance checks - Cannot verify actual wallet balances
When you're ready to process real payments, you'll need to add:
1. Solana Integration:
# Cargo.toml
[dependencies]
solana-client = "1.17"
solana-sdk = "1.17"2. Transaction Verification:
use solana_client::rpc_client::RpcClient;
fn verify_payment(signature: &str) -> Result<bool> {
let rpc_client = RpcClient::new("https://api.mainnet-beta.solana.com");
let transaction = rpc_client.get_transaction(signature)?;
// Verify recipient, amount, memo
Ok(true)
}3. Payment Cache:
// Prevent replay attacks
struct PaymentCache {
processed_signatures: HashSet<String>,
}4. Security Hardening:
- Validate Solana addresses
- Check transaction finality
- Implement rate limiting (runtime)
- Add monitoring and alerts
👉 Complete Guide: Production Integration Documentation
Coming Soon:
- 🔄 Real Solana devnet integration (optional mode)
- 🔐 Transaction verification helpers
- 📊 Payment analytics dashboard
- 🔌 WebSocket support for real-time payments
- 🌐 Multi-chain support (Ethereum, Bitcoin Lightning)
Not Planned:
- ❌ Hosted payment processor service
- ❌ Wallet management (use existing solutions)
- ❌ Full production payment gateway
We welcome all contributions to make x402-dev better!
🐛 Found a Bug? Open an issue with:
- Clear description
- Steps to reproduce
- Expected vs actual behavior
- Your environment (
x402-dev --version, OS)
💡 Have a Feature Idea? Start a discussion to:
- Share your use case
- Get community feedback
- Collaborate on design
📝 Improve Documentation? Documentation PRs are always welcome:
- Fix typos or unclear explanations
- Add examples or tutorials
- Improve error messages
🔧 Want to Code? Check our Contributing Guide for:
- Development setup
- Code style guidelines
- Testing requirements
- PR process
# 1. Fork and clone
git clone https://github.com/YOUR_USERNAME/x402-dev
cd x402-dev
# 2. Build and test
cargo build
cargo test
# 3. Make changes and test
cargo test
cargo clippy
# 4. Submit PR
git push origin your-feature-branch
# Open PR on GitHubNew to Rust or the project? Look for issues tagged:
good-first-issue- Beginner-friendly tasksdocumentation- Doc improvementshelp-wanted- Community contributions needed
All core features complete and ready for use:
-
✅ Epic 1: Foundation & CLI Infrastructure (100%)
- Multi-command CLI with beautiful output
- Error handling and diagnostics
- Cross-platform support (macOS, Linux, Windows)
-
✅ Epic 2: Mock Payment Server (100%)
- HTTP 402 responses with proper headers
- Configurable routes and pricing
- Mock invoice generation
-
✅ Epic 3: Test Automation (100%)
- YAML-based test suites
- Multiple assertion types
- JUnit XML output for CI/CD
-
✅ Epic 4: Protocol Validator (100%)
- Header format validation
- Compliance checking
- Verbose diagnostic output
-
✅ Epic 5: Policy Engine (100%)
- YAML policy definitions
- Express/Fastify code generation
- Multiple policy types (rate limiting, spending caps, allow/deny lists)
-
✅ Epic 6: Developer Experience (100%)
- Beautiful CLI output
- Helpful error messages
x402-dev doctordiagnostics
-
✅ Epic 7: Documentation (100%)
- Comprehensive guides
- Code examples
- Video tutorials
Focus: Optional Solana Integration
- 🔄 Optional devnet mode - Real Solana transactions (opt-in)
- 🔐 Transaction verification helpers - Utility functions for production use
- 📊 Payment analytics - Track test transactions and metrics
- 🔌 WebSocket support - Real-time payment notifications
Focus: Production Readiness Helpers
- 🌐 Multi-chain support - Ethereum, Bitcoin Lightning
- 🛡️ Security helpers - Replay prevention, signature validation
- 📈 Performance optimizations - Caching, rate limiting runtime
- 🔍 Advanced testing - Load testing, chaos engineering
Important: x402-dev will remain a testing toolkit. We won't become a hosted payment processor or full production gateway. Our focus is helping developers build and test payment-protected APIs.
👉 Vote on features | See detailed roadmap
- 💬 GitHub Discussions - Ask questions
- 🐛 Issue Tracker - Report bugs
- 📢 Changelog - Release notes
- 🔔 Release Notifications - Stay updated
MIT License © 2025 x402-dev Contributors
See LICENSE for full details.
TL;DR: Free to use, modify, and distribute. No warranty. Attribution appreciated but not required.
Built With:
- Rust - Performance, safety, and great developer experience
- Tokio - Async runtime for the mock server
- Clap - Beautiful CLI framework
- Serde - YAML/JSON serialization
Inspired By:
- HTTP 402 "Payment Required" standard (RFC 7231)
- The Solana developer community
- Feedback from Solana Hackathon 2025 participants
Special Thanks:
- Beta testers who provided invaluable feedback
- Contributors who improved documentation and examples
- The Rust community for excellent tooling and libraries
What it is:
- ⚡ Testing toolkit for HTTP 402 payment-protected APIs
- 🧪 Mock server + Protocol validator + Test automation
- 🚀 90-second setup, zero blockchain dependencies
What it's NOT:
- ❌ Production payment processor
- ❌ Solana wallet or transaction service
- ❌ Hosted payment gateway
Perfect for:
- ✅ Backend developers testing payment endpoints
- ✅ Hackathon teams rapid prototyping
- ✅ QA engineers automating payment tests
- ✅ Educators teaching HTTP 402 protocol
Get Started:
cargo install x402-dev
x402-dev init my-api
x402-dev mockcargo install x402-dev && x402-dev init⚡ 90 seconds from install to first test
📖 Documentation • 💻 Examples • 🤝 Contributing • 💬 Discussions
⭐ Star us on GitHub • 🐦 Share with your team • 📢 Join the discussion
Made with ❤️ for the Solana community
Solana Hackathon 2025 Submission
Keywords: HTTP 402, Payment Required, Solana testing, API payment testing, mock payment server, protocol validation, developer tools, Rust CLI, hackathon tools, payment middleware, test automation, CI/CD integration