x402 RPC Server - Enterprise-grade Solana RPC with x402 Payments

Monetize Solana RPC methods using the x402 payment protocol. Built for enterprise with rate limiting, structured logging, payment verification, and automatic settlement.

Features

• 9 Solana RPC v2 Methods - getAccountInfo, getBalance, getBlock, getTransaction, sendTransaction, getLatestBlockhash, getProgramAccounts, getTokenAccountBalance, getTokenAccountsByOwner
• x402 Payment Protocol - Industry-standard payment verification and settlement
• Enterprise Security - Helmet, CORS, rate limiting (100 req/min per IP)
• Structured Logging - Winston with file rotation and console output
• Schema Validation - Zod schemas for all RPC requests
• Automatic Retry - Resilient RPC proxy with configurable retries
• Health Monitoring - Built-in health checks and metrics
• Rate Limiting - Token bucket algorithm with memory storage
• Payment Verification - Via PayAI facilitator with on-chain settlement

📦 Installation

cd packages/x402-rpc-server
pnpm install

🏃 Running

Development

pnpm dev

Production

pnpm build
pnpm start

📖 API Documentation

Discovery Endpoint

GET /discovery

Returns all available RPC methods with pricing and payment requirements.

Health Check

GET /health

Returns server health status and upstream RPC connectivity.

Documentation

GET /docs/x402-rpc

RPC Methods

All RPC endpoints require x402 payment:

POST /rpc/{method}
Headers:
  Content-Type: application/json
  X-PAYMENT: <base64-encoded-payment-payload>

Body:
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getBalance",
  "params": ["<pubkey>"]
}

Batch RPC

POST /rpc

Submit multiple RPC calls in one request with combined payment.

💰 Pricing

Method	Price (USDC)	Timeout
getBalance	$0.02	5s
getLatestBlockhash	$0.03	5s
getTokenAccountBalance	$0.04	10s
getAccountInfo	$0.05	10s
getTransaction	$0.08	15s
getTokenAccountsByOwner	$0.12	30s
getBlock	$0.15	30s
getProgramAccounts	$0.25	60s
sendTransaction	$0.20	30s

🔄 Payment Flow

1. Client makes request without payment → receives 402 Payment Required
2. Client creates payment using x402 SDK
3. Client retries with X-PAYMENT header
4. Server verifies payment via facilitator
5. Server settles payment on-chain
6. Server proxies request to upstream RPC
7. Client receives RPC response

📊 Logging

Logs are written to:

• logs/combined.log - All logs
• logs/error.log - Errors only
• Console - Formatted output with colors

🔐 Security Features

• Rate Limiting: 1000 requests/minute per IP
• Helmet.js: Security headers
• CORS: Configurable origin control
• Input Validation: Zod schema validation
• Payment Verification: On-chain settlement via facilitator
• Structured Logging: Audit trail of all operations

🛠️ Architecture

┌─────────────┐      x402       ┌──────────────┐
│             │  ────────────>   │              │
│   Client    │                  │  x402 Server │
│             │  <────────────   │              │
└─────────────┘    RPC Response  └──────┬───────┘
                                        │
                                        │ Verify/Settle
                                        ▼
                               ┌──────────────────┐
                               │  PayAI           │
                               │  Facilitator     │
                               └──────────────────┘
                                        │
                                        │ Proxy RPC
                                        ▼
                               ┌──────────────────┐
                               │  Oobe Protocol   │
                               │  RPC Node        │
                               └──────────────────┘

🧪 Testing

# Get discovery resources
curl http://localhost:3002/discovery

# Try without payment (should return 402)
curl -X POST http://localhost:3002/rpc/getBalance \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getBalance","params":["EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"]}'

# Health check
curl http://localhost:3002/health

📝 License

Apache-2.0

🤝 Contributing

Contributions welcome! Please open an issue or PR.

🔗 Links

• x402 Specification
• PayAI Docs
• Oobe Protocol
• Synapse Gateway