SPL-402 Proxy

Monetize your APIs with Solana payments in minutes

SPL-402 Proxy is a powerful payment middleware that sits between your clients and your existing API, handling payment verification automatically. No code changes to your API required!

Features

• Zero API Changes - Works with any existing HTTP API
• Config-Based Setup - Simple JSON configuration
• No Private Keys - Only needs your public wallet address
• Multiple Routes - Different prices for different endpoints
• Flexible Payments - Native SOL or SPL tokens
• Discovery & Analytics - Built-in balance and history tracking

Installation

npm install -g spl402-proxy

Usage

1. Initialize Configuration

spl402-proxy init

This creates a config file at ~/.spl402/proxy.config.json. You can use the interactive wizard or skip it with --quick flag.

2. Configure Your Routes

Edit ~/.spl402/proxy.config.json:

{
  "server": {
    "port": 3000,
    "recipientWallet": "Your-Solana-Wallet-Address",
    "network": "mainnet-beta",
    "rpcUrl": "https://api.mainnet-beta.solana.com"
  },
  "payment": {
    "scheme": "transfer",
    "mint": null,
    "decimals": null
  },
  "proxy": {
    "target": "http://localhost:8080"
  },
  "routes": [
    {
      "path": "/api/free",
      "price": 0,
      "method": "GET"
    },
    {
      "path": "/api/premium",
      "price": 0.001,
      "method": "GET"
    }
  ]
}

3. Start Your Backend API

Make sure your existing API is running:

# Example: Your API running on port 8080
node your-api-server.js

4. Start the Payment Proxy

spl402-proxy serve

That's it! Your API is now protected with Solana payments.

How It Works

┌──────────┐   Request with payment    ┌──────────────┐   Verified request   ┌──────────────┐
│  Client  │ ───────────────────────> │  SPL-402     │ ──────────────────> │  Your API    │
│          │                            │  Proxy       │                      │  (port 8080) │
│          │ <─────────────────────── │  (port 3000) │ <────────────────── │              │
└──────────┘   Response                └──────────────┘   Response           └──────────────┘
                                              │
                                              │ Verifies payment
                                              │ on Solana blockchain
                                              ▼
                                       ┌──────────────┐
                                       │   Solana     │
                                       │   Network    │
                                       └──────────────┘

1. Client makes request to proxy (port 3000)
2. Proxy requires payment (402 Payment Required)
3. Client pays on Solana and includes payment proof
4. Proxy verifies payment on blockchain
5. Proxy forwards request to your API (port 8080)
6. Your API responds normally
7. Proxy returns response to client

Configuration

Server Settings

| Field | Description | Required | |-------|-------------|----------| | port | Port for proxy server | Yes | | recipientWallet | Your Solana wallet address to receive payments | Yes | | network | Solana network: mainnet-beta, devnet, or testnet | Yes | | rpcUrl | Custom RPC endpoint URL | Optional |

Payment Settings

| Field | Description | Required | |-------|-------------|----------| | scheme | Payment type: transfer (SOL) or token-transfer (SPL tokens) | Yes | | mint | SPL token mint address (only for token-transfer) | Conditional | | decimals | Token decimals (only for token-transfer) | Conditional |

Proxy Settings

| Field | Description | Required | |-------|-------------|----------| | target | Your backend API URL | Yes |

Route Configuration

Each route can have:

| Field | Description | Required | Default | |-------|-------------|----------|---------| | path | Endpoint path (e.g., /api/data) | Yes | - | | price | Price in SOL/tokens (0 = free) | Yes | - | | method | HTTP method | No | GET |

Commands

spl402-proxy init

Create a new configuration file.

# Interactive wizard
spl402-proxy init

# Quick setup with defaults
spl402-proxy init --quick

# Force overwrite existing config
spl402-proxy init --force

spl402-proxy serve

Start the payment proxy server.

# Use default config (~/.spl402/proxy.config.json)
spl402-proxy serve

# Use custom config file
spl402-proxy serve --config /path/to/my-config.json

# Override port from config
spl402-proxy serve --port 4000

spl402-proxy discover

Discover SPL-402 enabled services.

# List all services
spl402-proxy discover

# Search for specific services
spl402-proxy discover --search "api"

# Get info about specific wallet
spl402-proxy discover <wallet-address>

# JSON output
spl402-proxy discover --json

spl402-proxy balance

Check wallet balance (SOL and token if configured in ~/.spl402/proxy.config.json).

# Check balance of a wallet
spl402-proxy balance <wallet-address>

# On different network
spl402-proxy balance <wallet-address> --network devnet

Note: If your config uses token-transfer scheme, this command will show both SOL balance and token balance using the mint address and decimals from your config.

spl402-proxy history

View payment history.

# View recent payments
spl402-proxy history <wallet-address>

# Limit results
spl402-proxy history <wallet-address> --limit 50

# JSON output
spl402-proxy history <wallet-address> --json

Payment Schemes

Native SOL Transfers (Recommended)

Simple and fast. Users pay in SOL.

{
  "payment": {
    "scheme": "transfer",
    "mint": null,
    "decimals": null
  }
}

SPL Token Transfers

Accept payments in any SPL token (USDC, USDT, custom tokens).

{
  "payment": {
    "scheme": "token-transfer",
    "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "decimals": 6
  }
}

Popular Token Addresses:

• SPL402 Token: DXgxW5ESEpvTA194VJZRxwXADRuZKPoeadLoK7o5pump (6 decimals)
• USDC: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v (6 decimals)
• USDT: Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB (6 decimals)

Advanced Examples

Multiple Route Pricing

{
  "routes": [
    { "path": "/api/free", "price": 0, "method": "GET" },
    { "path": "/api/basic", "price": 0.0001, "method": "GET" },
    { "path": "/api/premium", "price": 0.001, "method": "GET" },
    { "path": "/api/ai/generate", "price": 0.01, "method": "POST" },
    { "path": "/api/ai/image", "price": 0.05, "method": "POST" }
  ]
}

SPL402 Token Payments

{
  "server": {
    "port": 3000,
    "recipientWallet": "Your-Wallet-Address",
    "network": "mainnet-beta"
  },
  "payment": {
    "scheme": "token-transfer",
    "mint": "DXgxW5ESEpvTA194VJZRxwXADRuZKPoeadLoK7o5pump",
    "decimals": 6
  },
  "proxy": {
    "target": "http://localhost:8080"
  },
  "routes": [
    { "path": "/api/data", "price": 1, "method": "GET" }
  ]
}

Note: Price is in SPL402 tokens (1 = 1 SPL402)

USDC Payments

{
  "server": {
    "port": 3000,
    "recipientWallet": "Your-Wallet-Address",
    "network": "mainnet-beta"
  },
  "payment": {
    "scheme": "token-transfer",
    "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "decimals": 6
  },
  "proxy": {
    "target": "http://localhost:8080"
  },
  "routes": [
    { "path": "/api/data", "price": 0.1, "method": "GET" }
  ]
}

Note: Price is in USDC tokens (0.1 = $0.10 USD)

Devnet Testing

{
  "server": {
    "port": 3000,
    "recipientWallet": "Your-Devnet-Wallet",
    "network": "devnet",
    "rpcUrl": "https://api.devnet.solana.com"
  },
  "payment": {
    "scheme": "transfer"
  },
  "proxy": {
    "target": "http://localhost:8080"
  },
  "routes": [
    { "path": "/api/test", "price": 0.001, "method": "GET" }
  ]
}

Working with Existing API Keys

SPL-402 Proxy forwards ALL headers to your backend, including existing API keys. This enables two-layer security:

1. SPL-402 Layer: Verifies Solana payment first
2. Your API Layer: Validates API keys/tokens as usual

Client Request (x-solana-signature + x-api-key)
    ↓
SPL-402 Proxy (verifies payment)
    ↓ (forwards all headers including x-api-key)
Your Backend API (checks API key)
    ↓
Response

Benefits:

• Keep your existing authentication system
• Add payment layer without changing backend code
• Clients must provide BOTH payment proof AND valid credentials
• No migration needed for existing API security

See the /test directory for a complete working example.

Free Endpoints

These endpoints are always free and auto-registered:

• GET /health - Health check
• GET /status - Status check
• GET /.well-known/spl402.json - Payment information

Troubleshooting

"Config file not found"

Run spl402-proxy init to create a config file, or use --config to specify a custom config path.

"Recipient wallet not configured"

Edit ~/.spl402/proxy.config.json (or your custom config file) and set your Solana wallet address in server.recipientWallet.

"Failed to connect to backend server"

Make sure your backend API is running on the URL specified in proxy.target.

"Bad Gateway"

Check that:

1. Your backend API is running
2. The proxy.target URL is correct
3. Your backend is accessible from the proxy

Payment verification failures

• Ensure you're on the correct network (mainnet-beta, devnet, testnet)
• Check RPC endpoint is responding
• Verify wallet address is correct

Production Recommendations

1. Use a reliable RPC provider for mainnet:

   • Helius (https://helius.dev)
   • QuickNode (https://quicknode.com)
   • Alchemy (https://alchemy.com)

2. Set up monitoring for your proxy server

3. Use HTTPS in production with a reverse proxy (nginx, caddy)

4. Rate limiting - Add rate limiting to prevent abuse

5. Logging - Monitor payment activity and errors

Client Integration

Clients can use the spl402 SDK to make payments:

import { SPL402Client } from 'spl402';

const client = new SPL402Client({
  network: 'mainnet-beta',
  rpcUrl: 'https://api.mainnet-beta.solana.com'
});

const response = await client.fetch('http://localhost:3000/api/premium', {
  method: 'GET',
  wallet: userWallet
});

Support

• Documentation: https://spl402.org/docs
• GitHub: https://github.com/astrohackerx/spl402
• Issues: https://github.com/astrohackerx/spl402/issues

License

MIT