📖 Documentation

Quick Start

Get paywalled content running in under 2 minutes.

1. Sign up and get your API key

Create an account at /signup. You'll receive an API key like l402_sk_abc123...

2. Add the JS snippet to your page

Place this before the closing </body> tag:

<script src="https://l402-gateway.yf-ae7.workers.dev/js/l402.js"
        data-api-key="YOUR_API_KEY"></script>

3. Tag your premium content

Wrap any content you want to paywall with data-l402-price (in satoshis):

<div data-l402-price="10" data-l402-resource="article-1">
  <h2>Premium Article</h2>
  <p>This content is hidden until the visitor pays 10 sats.</p>
</div>

That's it! Visitors will see a paywall overlay. After paying, the content unlocks and a token is stored in their browser.

JS Snippet Reference

Attributes

Attribute	Required	Description
data-l402-price	Yes	Price in satoshis (1 sat ≈ $0.001)
data-l402-resource	No	Unique ID for this content (default: "default"). Used for token caching.

Script tag attributes

Attribute	Required	Description
data-api-key	Yes	Your tenant API key

API Reference

Base URL: https://l402-gateway.yf-ae7.workers.dev

POST /api/v1/invoice

Create an L402 invoice challenge.

curl -X POST /api/v1/invoice \
  -H "X-L402-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_sats": 10, "memo": "Premium article", "resource_id": "art-1"}'

Response (402):

{
  "payment_request": "lnbc100n1p...",
  "payment_hash": "abc123...",
  "macaroon": "eyJ...",
  "amount_sats": 10,
  "fee_sats": 1,
  "total_sats": 11
}

GET /api/v1/verify

Verify an L402 token after payment.

curl /api/v1/verify \
  -H "Authorization: L402 <macaroon>:<preimage>"

Response (200):

{
  "valid": true,
  "resource_id": "art-1",
  "amount_sats": 10
}

GET /api/v1/status/:payment_hash

Check if an invoice has been paid. Requires X-L402-Key header.

curl /api/v1/status/abc123... \
  -H "X-L402-Key: YOUR_API_KEY"

GET /api/v1/payments

List your payments. Supports ?status=paid&limit=50&offset=0.

GET /api/v1/stats

Get payment statistics for your account.

GET /api/v1/tenants/me

Get your tenant info (email, verification status, fee rate).

Authentication

All API calls require your API key in the X-L402-Key header:

X-L402-Key: l402_sk_your_key_here

Keep your API key secret. It provides full access to your tenant's invoices and payment data.

L402 Flow

The L402 protocol works in 4 steps:

1. Request — Client requests protected content
2. Challenge — Server responds with 402 + Lightning invoice + macaroon
3. Payment — Client pays the invoice, receives preimage as proof
4. Access — Client presents Authorization: L402 macaroon:preimage → content unlocked

The macaroon is HMAC-signed and contains the tenant ID, payment hash, resource ID, amount, and expiry. It cannot be forged without the server's secret key.