x402 at Scale! Battle-test your x402-enabled APIs before production
Features • Quick Start • Architecture • Usage • Documentation
Plethora is a comprehensive load testing and simulation framework designed specifically for x402-enabled APIs. It simulates thousands of autonomous AI agents making concurrent micropayments on the Solana devnet, providing critical insights into your application's performance, scalability, and resilience under real-world pressure.
When you build an API monetized with x402, manual testing only answers "Does it work?" but leaves critical questions unanswered:
- Scalability: What happens when 1,000 agents access your API simultaneously?
- Resilience: Can your app handle failed Solana transactions gracefully?
- Performance: How does response time degrade under heavy load?
- Cost: What are your actual Solana network fees at scale?
Plethora provides the missing piece of the development lifecycle, moving x402 from prototype to production-ready.
- Concurrent Agent Simulation: Spin up thousands of virtual agents making real x402 payments
- Real-time Analytics Dashboard: Monitor throughput, response times, and error rates live
- Interactive CLI: Configure and control simulations from your terminal
- Blockchain Integration: Full Solana devnet/testnet support with wallet management
- Multiple Load Patterns: Constant load, spike testing, stress testing until failure
- Comprehensive Reporting: Detailed breakdowns of HTTP errors, blockchain failures, and performance metrics
| Component | Description |
|---|---|
| go-cli | Interactive command-line interface for simulation control |
| engine | Core simulation engine managing virtual agents and payments |
| dashboard | Web App version of our CLI App |
| x402-test | Protected backend service for testing x402 implementations |
| solana-stress-forge | Real-time analytics and monitoring web interface |
- Go 1.21 or higher
- Node.js 18 or higher
- npm or yarn
- Solana CLI tools (optional, for wallet management)
git clone https://github.com/yourusername/plethora.git
cd plethoraThe engine manages wallet pools and payment processing.
cd engine
npm installConfigure Wallets: Create a wallets.json file in the engine directory with your pre-funded Solana devnet wallets:
{
"wallets": [
{
"publicKey": "YOUR_PUBLIC_KEY_1",
"privateKey": "YOUR_PRIVATE_KEY_1"
},
{
"publicKey": "YOUR_PUBLIC_KEY_2",
"privateKey": "YOUR_PRIVATE_KEY_2"
}
],
"network": "devnet"
}Start the Engine:
node server.jsThe engine will start on http://localhost:3000 (or your configured port).
This is your test x402-enabled API endpoint.
cd ../x402-test
npm install
cp .env.example .env
node server.jsThe protected backend will start on http://localhost:4000 (default).
The dashboard provides real-time visualization of your simulation metrics.
cd ../dashboard
npm install
npm startThe dashboard will open automatically at http://localhost:5000.
The interactive CLI guides you through the entire simulation process.
cd ../go-cli
go run main.goFollow the interactive prompts:
- Enter your target x402 API endpoint
- Configure the number of concurrent agents
- Select your load pattern (constant, spike, or stress test)
- Set test duration and ramp-up period
- Start the simulation!
The CLI will automatically orchestrate all components and display real-time progress.
┌─────────────────────────────────────────────────────────────┐
│ Plethora Suite │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ │ │ │ │ │ │
│ │ CLI │────────▶│ Engine │────────▶│ x402 API │ │
│ │ (Go) │ │ (Node) │ │ (Test) │ │
│ │ │ │ │ │ │ │
│ └──────────┘ └────┬─────┘ └──────────┘ │
│ │ │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ │ │
│ │ Solana │ │
│ │ Devnet │ │
│ │ │ │
│ └──────────┘ │
│ │ │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ │ │
│ │Dashboard │ │
│ │Analytics │ │
│ │ │ │
│ └──────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
- CLI receives user configuration and starts the simulation
- Engine spawns virtual agents that execute the x402 payment flow:
- Make initial GET request → receive 402 Payment Required
- Construct & sign Solana SPL token transfer
- Submit transaction to Solana network
- Make authenticated request with transaction signature
- Record metrics (success/failure, response time)
- Dashboard displays real-time metrics and visualizations
- x402-test backend serves as the protected API being tested
cd go-cli
go run main.goExample Configuration:
backend_endpoint: http://localhost:3000/api/v1
target_endpoint: http://localhost:4021/premium/content
num_agents: 15
test_duration_seconds: 10
ramp_up_period_seconds: 10
traffic_pattern: Constant Load
solana_network: devnet
payer_wallet_count: 10
output_file: config.yamlOnce the simulation starts, open the dashboard at the url shown in the terminal to monitor:
- Throughput: Requests per second
- Response Times: Average, median, p95, p99
- Error Rates: HTTP errors vs blockchain errors
- Time-series Graphs: Performance over time
- Transaction Success Rate: Solana payment confirmations
Simulates sudden traffic bursts:
Load Pattern: Spike
Peak Agents: 5000
Spike Duration: 30 seconds
Rest Duration: 60 secondsContinuously increases load until failure:
Load Pattern: Stress
Starting Agents: 100
Increment: 100 agents/minuteDashboard (url which is shown in the terminal)
- The whole analytics of the simulation for metrics
backend_endpoint: string # Engine API endpoint
target_endpoint: string # x402-protected API to test
num_agents: integer # Number of concurrent agents
test_duration_seconds: integer # Total test duration
ramp_up_period_seconds: integer # Gradual agent spawn period
traffic_pattern: string # Constant/Spike/Stress
solana_network: string # devnet/testnet/mainnet
payer_wallet_count: integer # Number of wallets in pool
output_file: string # Results output path{
"wallets": [
{
"publicKey": "Base58PublicKey",
"privateKey": "[byte array or base58]"
}
],
"network": "devnet|testnet|mainnet-beta"
}- Go: Follow standard Go formatting (
gofmt) - JavaScript/TypeScript: ESLint + Prettier
- Solana Foundation for blockchain infrastructure
- x402 Protocol for micropayment standards
- Open source community for incredible tools and libraries
Made with ❤️ for the x402 community
⭐ Star us on GitHub if Plethora helps your project!