AIPP Documentation

Quick start

1. Go to aipp.dev, paste your Lightning address or BOLT12 offer.
2. Receive an API key starting with aipp_merch_.
3. Call the /invoice/create endpoint to mint an invoice.
4. Your customer pays it — 99% is instantly available in your merchant balance.
5. Call the /merchant/payout endpoint to withdraw to your Lightning address.

Official SDKs

The fastest way to integrate AIPP is using our official SDKs for Node.js and Python. They provide fully typed clients and zero-dependency designs.

from aipp import Aipp

client = Aipp("aipp_merch_...")
charge = client.create_charge(500)
print(charge.payment_request)

import { Aipp } from 'aipp-node';

const aipp = new Aipp({ apiKey: '...' });
const charge = await aipp.createCharge({
  amountSats: 500
});

Authentication

Send the API key as a header:

X-Api-Key: aipp_merch_xxxxxxxxxxxxxxxxxx

Register Merchant

POST /merchant/register

{
  "ln_address": "satoshi@getalby.com",
  "usdc_address": "0xFCAd0B19bB29D4674531d6f115237E16AfCE377c", // EVM Wallet for Base USDC
  "email": "merchant@example.com" // Optional for payout notifications
}

Create an invoice

POST /invoice/create

{
  // For L402 (Lightning):
  "amount_sats": 2100,
  
  // For x402 (USDC on Base):
  "amount_usd": 0.05,
  "protocol": "x402",
  
  "memo": "1 article unlock"
}

{
  "payment_hash": "x402_0a1b...",
  "protocol": "x402",
  "amount_usd": 0.05,
  "pay_to": "0xFCAd...",
  "network": "base",
  "token": "0x036cbd...", // USDC contract address
  "status": "pending"
}

Check invoice status

GET /invoice/status/:hash

For x402, pass the transaction hash (EVM tx hash) as a query parameter to trigger on-chain verification and settle the invoice.

GET /invoice/status/x402_0a1b...?tx_hash=0xe526...

{
  "paid": true,
  "status": "settled",
  "preimage": "0xe526..." // Transaction hash serves as preimage
}

Withdraw Funds (Manual Payout)

POST /merchant/payout

Triggers a withdrawal of your balance. Lightning payouts are processed via LN, while USDC payouts are managed automatically by the Background Payout Worker with flat 1% fee calculation.

{}

{
  "message": "Payout triggered successfully"
}

Get Invoice Receipt NEW

GET /invoice/receipt/:hash

Returns an EU AI Act Article 26 compliant machine-readable receipt for a settled invoice. Useful for audit trails and regulatory compliance for AI-to-AI transactions.

{
  "receipt_id": "rec_550e8400-e29b-41d4",
  "transaction_id": "a3f2b9c1d0e4f5...",
  "date": "2026-07-13T20:00:00.000Z",
  "status": "settled",
  "compliance": {
    "regulation": "EU AI Act Article 26",
    "note": "Verifiable record of a machine-to-machine transaction."
  },
  "payment_details": {
    "protocol": "L402",
    "proof": "0000...preimage",
    "merchant_destination": "merchant@ln.tips"
  },
  "financials": {
    "currency": "SATS",
    "total_amount": 1000,
    "merchant_amount": 990,
    "platform_fee": 10
  }
}

Marketplace Manifest NEW

GET /paidmcp.json

Returns a PaidMCP.dev compatible JSON manifest. Use this to list your AIPP-protected endpoints on global AI agent marketplaces. Copy it from your Dashboard with one click.

{
  "id": "aipp-merchant-api",
  "name": "AIPP Monetized API",
  "endpoint": "https://aipp.dev",
  "chains": ["base", "base-sepolia"],
  "tools": [
    { "name": "premium_article", "priceUsdt": 0.005 }
  ],
  "tags": ["aipp", "l402", "x402"]
}

L402 micropayments (Lightning)

Any of your endpoints can require Lightning payment using L402. The flow:

1. Client requests resource → server returns 402 with Www-Authenticate: L402 macaroon="..." invoice="...".
2. Client pays invoice via any Lightning wallet and obtains preimage.
3. Client retries with header Authorization: L402 <macaroon>:<preimage_hex>.

Try it live on the L402 demo page.

x402 micropayments (USDC on Base)

Monetize programmatically using EVM on-chain transactions via Base network. The flow:

1. Client requests resource → server returns 402 with Base64 JSON challenge in the PAYMENT-REQUIRED header.
2. Client decodes challenge (scheme, network, payTo, price, token, payment_hash) and transfers USDC on-chain.
3. Client retries request with header Authorization: Bearer <tx_hash> or query string ?tx_hash=<tx_hash>.

Dual-Rail Hybrid Payments (L402 + x402)

Provide ultimate payment flexibility to your users and agents by offering both Bitcoin Lightning and USDC on Base in a single request. When creating an invoice, specify protocol: "dual". AIPP will return both Lightning and USDC parameters. The client can pay via either channel to unlock the content.

POST /invoice/create
{
  "amount_usd": 0.01,
  "protocol": "dual",
  "memo": "Dual-Rail Protection"
}

{
  "payment_hash": "mock_hash",
  "protocol": "dual",
  "payment_request": "lnbc...", // Lightning BOLT11 invoice
  "pay_to": "0x...",           // Gateway EVM Address
  "token": "0x...",            // Base USDC Contract Address
  "network": "base",
  "amount_usd": 0.01,
  "amount_sats": 42
}

AI Agent Auto-Discovery

AI agents can query the machine-readable /aipp-agent.json or /.well-known/aipp-agent.json endpoints to dynamically discover supported chains, payment methods, pricing, and API endpoints without human intervention.

{
  "spec_version": "1.0",
  "name": "AIPP.dev AI Payment Gateway",
  "endpoints": {
    "create_invoice": "https://aipp.dev/invoice/create",
    "invoice_status": "https://aipp.dev/invoice/status/{hash}"
  },
  "protocols": {
    "dual": {
      "name": "Dual-Rail Hybrid"
    }
  }
}

Drop-in Paywall

Monetize any static content on your website by simply dropping in our paywall.js script. It automatically handles Lightning invoices, WebLN browser wallets (like Alby or Zeus), and renders a beautiful UI without any dependencies.

1. Include the script in your HTML:

<script src="https://aipp.dev/paywall.js"></script>

2. Wrap your premium content in a div with the data-aipp-src attribute pointing to your L402-protected endpoint:

<div id="premium-content" data-aipp-src="https://your-api.com/premium-article">
  Loading premium content...
</div>

AI Agent Autopayment & Security

For autonomous AI agents running in cloud environments, catching a 402 Payment Required response and paying it programmatically can be implemented with a lightweight interceptor. If you use Nostr Wallet Connect (NWC) or an Alby token, your agent can pay invoices dynamically.

import os
import requests
from aipp import AippClient

# Load the NWC wallet URL securely from environment variables
nwc_url = os.environ.get("NWC_URL")
client = AippClient(nwc_url=nwc_url)

def get_api_resource(url):
    # Initial request to L402 protected resource
    res = requests.get(url)
    
    if res.status_code == 402:
        auth_header = res.headers.get("Www-Authenticate")
        if auth_header and auth_header.startswith("L402 "):
            # Extract invoice and macaroon from challenge
            challenge = parse_l402_challenge(auth_header)
            
            # Check budget and pay invoice
            try:
                preimage = client.pay_invoice(challenge["invoice"])
                # Retry request with payment proof
                headers = {"Authorization": f"L402 {challenge['macaroon']}:{preimage}"}
                return requests.get(url, headers=headers).json()
            except InsufficientBudgetError:
                raise Exception("AI Agent out of wallet budget!")
    return res.json()

Machine-Readable Pricing Discovery

Before making requests, autonomous agents can query the pricing structure of an endpoint to evaluate budget constraints without triggering 402 Payment Required challenge loops.

AIPP exposes a standardized /pricing.json manifest detailing pricing rates:

{
  "currency": "USD",
  "endpoints": [
    {
      "path": "/premium-article-1",
      "protocol": "L402",
      "price_usd": 0.005,
      "price_sats_fixed": 21,
      "description": "Access premium article for AI Autonomy research"
    },
    {
      "path": "/chat",
      "protocol": "L402",
      "price_sats_fixed": 5,
      "description": "Submit request to OpenAI proxy chatbot endpoint"
    }
  ]
}

Webhooks

When a charge is paid, AIPP automatically forwards 99% to your Lightning address and writes a transaction to your dashboard. You can configure a webhook URL for your backend to be notified instantly.

Errors

AIPP returns standard HTTP response codes to indicate success or failure. All error responses contain a JSON body detailing the error code and message:

{
  "error": "Unauthorized: Invalid or missing API key"
}

{
  "error": "Daily limit reached ($100). Resets at midnight UTC."
}

{
  "error": "Single request exceeds $10 limit"
}