The Real Problem
Developers building high-value APIs or serverless functions are forced into monthly subscription billing or manual API key provisioning. Buyers who only need 5 requests per month cannot justify a monthly plan, leading to churn and friction.
Real-World Example: For example, an API developer could configure an endpoint to charge $0.02 per request instead of requiring a recurring monthly subscription.
How aipp Solves It
aipp acts as an HTTP 402 gateway layer. When an unauthenticated request arrives without a valid payment proof header, your API responds with HTTP 402 Payment Required containing an invoice. Once paid via Lightning or USDC, the client retries with the payment proof and your API handler executes.
Step-by-Step Payment Flow
STEP 01
HTTP Request
Client or script sends GET/POST request to your API endpoint.
STEP 02
HTTP 402 Challenge
API responds HTTP 402 with invoice header (Lightning bolt11 or Base USDC).
STEP 03
Payment Settlement
Client wallet pays Lightning invoice or Base USDC transfer.
STEP 04
Proof Check & Unlock
Client retries request with payment receipt; API verifies proof and executes.
Scope & Boundaries
What aipp Does
- ✓ Generates Lightning (L402) and Base USDC (x402) invoice headers on demand
- ✓ Verifies settlement proof before executing protected handler
- ✓ Automatically forwards net merchant earnings to your configured wallet address
What aipp Does Not Do
- ✗ Does not host your API server logic or business application code
- ✗ Does not hold a user-controlled spendable merchant balance
- ✗ Does not enforce monthly recurring subscription logic
Implementation Pattern
Below is the minimal implementation pattern using standard aipp endpoints / SDK:
import { Aipp, l402Paywall } from 'aipp-sdk';
import express from 'express';
const app = express();
const aipp = new Aipp({ apiKey: process.env.AIPP_API_KEY });
// Protect API route with $0.02 paywall example
app.post('/api/v1/translate', l402Paywall({
client: aipp,
amountUsd: 0.02
}), (req, res) => {
res.json({ translation: "Bonjour le monde", status: "success" });
});
Settlement Architecture Note:
• Lightning Rail: In hosted Lightning flows, payments route through aipp's Lightning gateway before net proceeds are automatically forwarded to your configured wallet address.
• Base USDC Rail: USDC transfers settle directly on-chain to your designated EVM wallet address.
• No Merchant Spending Balance: aipp does not maintain a spendable merchant balance or require manual withdrawal steps.
Requirements & Limitations
- Requires client to handle 402 response headers or use aipp SDK client
- In hosted Lightning flows, payments route through aipp gateway before net proceeds are automatically forwarded
Frequently Asked Questions
How is payment verified?
Settlement verification occurs via local preimage cryptography or node status check.
How are merchant funds settled?
Funds settle to your configured wallet. In hosted Lightning flows, funds pass through aipp before net proceeds are automatically forwarded. Base USDC transfers settle on-chain to your EVM address.
Related Use Cases
Implement Pay per API Call with aipp
Read the developer documentation or generate your API key to gate requests behind Lightning and Base USDC payments.