@lnbot/l402

L402 payment middleware for Express.js — paywall any API in one line. Built on ln.bot.

Add Lightning-powered pay-per-request to any Express API. Protect premium routes with a paywall, or build clients that auto-pay L402-protected services — all without touching any cryptography.

import express from "express";
import { l402, LnBot } from "@lnbot/l402";

const app = express();
const ln = new LnBot({ apiKey: "key_..." });

app.use("/api/premium", l402.paywall(ln, { price: 10 }));

app.get("/api/premium/data", (req, res) => {
  res.json({ data: "premium content" });
});

This package is a thin glue layer. All L402 logic — macaroon creation, signature verification, preimage checking — lives in the ln.bot API via @lnbot/sdk. Zero crypto dependencies.

---

What is L402?

L402 is a protocol built on HTTP 402 Payment Required. It enables machine-to-machine micropayments over the Lightning Network:

1. Client requests a protected resource
2. Server returns 402 with a Lightning invoice and a macaroon token
3. Client pays the invoice, obtains the preimage as proof of payment
4. Client retries the request with Authorization: L402 <macaroon>:<preimage>
5. Server verifies the token and grants access

L402 is ideal for API monetization, AI agent tool access, pay-per-request data feeds, and any scenario where you want instant, permissionless, per-request payments without subscriptions or API key provisioning.

---

Install

npm install @lnbot/l402

pnpm add @lnbot/l402

yarn add @lnbot/l402

@lnbot/sdk and express are peer dependencies and will be resolved automatically.

---

Server — Protect Routes with L402

The l402.paywall() middleware intercepts requests, verifies L402 tokens via the SDK, and issues new challenges when payment is needed. Two SDK calls, ~40 lines of glue code, zero crypto.

import express from "express";
import { l402, LnBot } from "@lnbot/l402";

const app = express();
const ln = new LnBot({ apiKey: "key_..." });

// Paywall a route group — 10 sats per request
app.use("/api/premium", l402.paywall(ln, {
  price: 10,
  description: "API access",
}));

app.get("/api/premium/data", (req, res) => {
  // req.l402 is populated after successful payment verification
  res.json({
    data: "premium content",
    paymentHash: req.l402?.paymentHash,
  });
});

// Free routes still work normally
app.get("/api/free/health", (req, res) => {
  res.json({ status: "ok" });
});

app.listen(3000);

How the middleware works

1. Checks for an Authorization: L402 ... header
2. If present, calls ln.l402.verify() — the SDK checks signature, preimage, and caveats server-side
3. If valid, populates req.l402 and calls next()
4. If missing or invalid, calls ln.l402.createChallenge() and returns a 402 response with the invoice and macaroon

Dynamic pricing

// Fixed price per route
app.use("/api/cheap", l402.paywall(ln, { price: 1 }));
app.use("/api/expensive", l402.paywall(ln, { price: 100 }));

// Custom pricing function — receives the request, returns price in sats
app.use("/api/dynamic", l402.paywall(ln, {
  price: (req) => {
    if (req.path.includes("/bulk")) return 50;
    return 5;
  },
}));

Paywall options

Option	Type	Description
price	number | (req) => number	Price in satoshis — fixed or per-request
description	string	Invoice memo shown in wallets
expirySeconds	number	Challenge expiry in seconds
caveats	string[]	Macaroon caveats to attach

---

Client — Auto-Pay L402 APIs

The l402.client() wrapper makes L402 payment transparent. It detects 402 responses, pays the Lightning invoice via the SDK, caches the token, and retries — all in one fetch call.

import { l402, LnBot } from "@lnbot/l402";

const ln = new LnBot({ apiKey: "key_..." });

const client = l402.client(ln, {
  maxPrice: 100,         // refuse to pay more than 100 sats per request
  budgetSats: 50000,     // spending limit for the period
  budgetPeriod: "day",   // reset period: "hour" | "day" | "week" | "month"
  store: "memory",       // token cache: "memory" (default) | "none" | custom TokenStore
});

// Use like fetch — L402 payment is transparent
const response = await client.fetch("https://api.example.com/premium/data");
const data = await response.json();

// Convenience methods — all HTTP verbs
const json = await client.get("https://api.example.com/premium/data");
const result = await client.post("https://api.example.com/premium/submit", {
  body: JSON.stringify({ query: "test" }),
});
await client.put("https://api.example.com/premium/item/1", {
  body: JSON.stringify({ name: "updated" }),
});
await client.patch("https://api.example.com/premium/item/1", {
  body: JSON.stringify({ status: "active" }),
});
await client.delete("https://api.example.com/premium/item/1");

How the client works

1. Checks the token cache for a valid credential
2. If cached, sends the request with the Authorization header
3. If no cache (or server rejects), makes a plain request
4. On 402, parses the challenge and checks budget limits
5. Calls ln.l402.pay() — the SDK pays the invoice and returns a ready-to-use token
6. Caches the token and retries the request with authorization

Client options

Option	Type	Default	Description
maxPrice	number	1000	Max sats to pay for a single request
budgetSats	number	unlimited	Total budget in sats for the period
budgetPeriod	string	—	Reset period: "hour", "day", "week", "month"
store	string | TokenStore	"memory"	Token cache: "memory", "none", or custom

Custom token store

Implement the TokenStore interface for Redis, file system, or any persistence layer:

import { l402, LnBot } from "@lnbot/l402";
import type { TokenStore } from "@lnbot/l402";

const ln = new LnBot({ apiKey: "key_..." });

const redisStore: TokenStore = {
  async get(url) { /* read from Redis */ },
  async set(url, token) { /* write to Redis */ },
  async delete(url) { /* delete from Redis */ },
};

const client = l402.client(ln, { store: redisStore });

---

Header Utilities

Parse and format L402 headers for custom integrations:

import { l402 } from "@lnbot/l402";

// Parse Authorization: L402 <macaroon>:<preimage>
l402.parseAuthorization("L402 mac_base64:preimage_hex");
// → { macaroon: "mac_base64", preimage: "preimage_hex" }

// Parse WWW-Authenticate: L402 macaroon="...", invoice="..."
l402.parseChallenge('L402 macaroon="abc", invoice="lnbc1..."');
// → { macaroon: "abc", invoice: "lnbc1..." }

// Format headers
l402.formatAuthorization("mac_base64", "preimage_hex");
// → "L402 mac_base64:preimage_hex"

l402.formatChallenge("abc", "lnbc1...");
// → 'L402 macaroon="abc", invoice="lnbc1..."'

---

Error Handling

import { L402Error, L402BudgetExceededError, L402PaymentFailedError } from "@lnbot/l402";

try {
  const data = await client.get("https://api.example.com/expensive");
} catch (err) {
  if (err instanceof L402BudgetExceededError) {
    // Price exceeds maxPrice or total budget exhausted
  } else if (err instanceof L402PaymentFailedError) {
    // Lightning payment failed or didn't settle
  } else if (err instanceof L402Error) {
    // Other L402 protocol error (missing header, parse failure)
  }
}

---

API Reference

Server

Export	Description
l402.paywall(ln, options)	Express middleware factory — protects routes behind an L402 paywall

Client

Export	Description
l402.client(ln, options?)	Creates an L402-aware HTTP client with automatic payment
client.fetch(url, init?)	L402-aware fetch — pays 402 challenges automatically
client.get(url, init?)	GET + JSON parse with automatic L402 payment
client.post(url, init?)	POST + JSON parse with automatic L402 payment
client.put(url, init?)	PUT + JSON parse with automatic L402 payment
client.patch(url, init?)	PATCH + JSON parse with automatic L402 payment
client.delete(url, init?)	DELETE + JSON parse with automatic L402 payment

Header Utilities

Export	Description
l402.parseAuthorization(header)	Parse Authorization: L402 ... into { macaroon, preimage }
l402.parseChallenge(header)	Parse WWW-Authenticate: L402 ... into { macaroon, invoice }
l402.formatAuthorization(macaroon, preimage)	Format an Authorization header value
l402.formatChallenge(macaroon, invoice)	Format a WWW-Authenticate header value

Types

Type	Description
L402PaywallOptions	Options for l402.paywall()
L402ClientOptions	Options for l402.client()
L402Token	Cached L402 credential (macaroon + preimage + metadata)
TokenStore	Interface for custom token caches
L402RequestData	Data attached to req.l402 after verification

Errors

Class	Description
L402Error	Base error for all L402 protocol errors
L402BudgetExceededError	Price or cumulative spend exceeds configured limits
L402PaymentFailedError	Lightning payment failed or didn't return authorization

---

Requirements

• Node.js 18+, Bun, or Deno
• Express 4+ (server middleware)
• An ln.bot API key — create a wallet to get one

---

Related packages

• @lnbot/sdk — The TypeScript SDK this package is built on
• Python SDK · pypi
• Go SDK · pkg.go.dev
• Rust SDK · crates.io

Links

• ln.bot — website
• Documentation
• L402 specification
• GitHub
• npm

License

MIT