TypeScript SDK

Complete reference for the l402-kit TypeScript/Node.js SDK — Express middleware for Bitcoin Lightning pay-per-call APIs.

Installation

npm install l402-kit

Requirements: Node.js 18+, Express 4+

---

Quickstart

Your wallet (0% fee)

import express from 'express';
import { l402, BlinkProvider } from 'l402-kit';

const app = express();

// Payments go directly to your Blink wallet — 0% fee
const lightning = new BlinkProvider(
  process.env.BLINK_API_KEY!,
  process.env.BLINK_WALLET_ID!,
);

app.get('/api/data', l402({ priceSats: 10, lightning }), (req, res) => {
  res.json({ data: 'premium content' });
});

app.listen(3000);

Managed (no node needed)

import express from 'express';
import { l402, ManagedProvider } from 'l402-kit';

const app = express();

// l402kit.com hosts the node. You receive 99.7% of each payment.
const lightning = ManagedProvider.fromAddress('[e-mail]');

app.get('/api/data', l402({ priceSats: 10, lightning }), (req, res) => {
  res.json({ data: 'premium content' });
});

app.listen(3000);

---

l402(options) — middleware

Returns an Express RequestHandler that enforces L402 payment on the route.

Options

Option	Type	Default	Description
priceSats	number	required	Price per call in satoshis
lightning	LightningProvider	required	Your Lightning backend
supabaseUrl	string	SUPABASE_URL env	Supabase URL for payment logging
supabaseKey	string	SUPABASE_ANON_KEY env	Supabase key for payment logging
onPayment	(token, amountSats) => void	—	Callback fired after each verified payment
webhookUrl	string	—	Your endpoint to receive signed payment events
webhookSecret	string	—	HMAC-SHA256 secret for webhook signing
replayAdapter	ReplayAdapter	in-memory	Pluggable replay protection backend

Behavior

Request	Response
No Authorization header	402 Payment Required with BOLT11 invoice + macaroon
Valid L402 <macaroon>:<preimage>	next() — handler executes
Invalid or expired token	401 Unauthorized
Replayed preimage	401 Token already used

402 response body

{
  "error": "Payment Required",
  "invoice": "lnbc100n1p...",
  "macaroon": "eyJoYXNoIjoiYWJjMTIzIiwiZXhwIjoxNzAwMDAwMDAwfQ==",
  "priceSats": 10
}

WWW-Authenticate header

WWW-Authenticate: L402 macaroon="eyJ...", invoice="lnbc..."

---

Providers

AlbyProvider — recommended for soberano mode

Alby — self-custodial wallet. You control the keys.

import { AlbyProvider } from 'l402-kit';

// 1. Create an Alby Hub at hub.getalby.com (or self-host)
// 2. Settings → Access Tokens → create token (scopes: invoices:create, invoices:read)
const lightning = new AlbyProvider(
  process.env.ALBY_ACCESS_TOKEN!, // Hub access token
  process.env.ALBY_HUB_URL!,      // e.g. "https://your-name.getalby.com"
);

BTCPayProvider — self-hosted, zero trust

Run your own BTCPay Server. Full soberanoty.

import { BTCPayProvider } from 'l402-kit';

const lightning = new BTCPayProvider(
  process.env.BTCPAY_URL!,         // https://your-btcpay.com
  process.env.BTCPAY_API_KEY!,     // store API key
  process.env.BTCPAY_STORE_ID!,    // store ID
);

BlinkProvider — custodial, easiest start

Blink — free, no KYC for small amounts.

import { BlinkProvider } from 'l402-kit';

const lightning = new BlinkProvider(
  process.env.BLINK_API_KEY!,    // dashboard.blink.sv → API Keys
  process.env.BLINK_WALLET_ID!,  // your BTC wallet ID
);

LNbitsProvider

Self-hosted or legend.lnbits.com.

import { LNbitsProvider } from 'l402-kit';

const lightning = new LNbitsProvider(
  process.env.LNBITS_API_KEY!,
  'https://your-lnbits-instance.com', // optional, defaults to legend.lnbits.com
);

OpenNodeProvider

import { OpenNodeProvider } from 'l402-kit';

const lightning = new OpenNodeProvider(
  process.env.OPENNODE_API_KEY!,
  false, // testMode — set to true for sandbox
);

ManagedProvider — cloud mode (0.3% fee)

l402kit.com hosts the Lightning node. You receive 99.7% of each payment. Explicit opt-in.

import { ManagedProvider } from 'l402-kit';

const lightning = ManagedProvider.fromAddress('[e-mail]');

// Optional: auto-register in the public API directory
const lightning = ManagedProvider.fromAddress('[e-mail]', {
  registerDirectory: {
    url: 'https://api.you.com/v1/data',
    name: 'My Data API',
    priceSats: 10,
    category: 'data',          // data | ai | finance | weather | compute | storage | other
    description: 'Optional',
  },
});

Registration fires once at startup (fire-and-forget, errors are silent). The API appears at l402kit.com/apis.json so agents can discover it automatically.

---

Replay protection

Default — in-memory (development)

Built-in. Resets on restart. Suitable for single-process deployments.

app.get('/api', l402({ priceSats: 10, lightning }), handler);

Redis (production — multi-instance)

import Redis from 'ioredis';
import { l402, RedisReplayAdapter } from 'l402-kit';

const replay = new RedisReplayAdapter(
  new Redis(process.env.REDIS_URL!),
  86400, // TTL in seconds (24h)
);

app.get('/api', l402({ priceSats: 10, lightning, replayAdapter: replay }), handler);

RedisReplayAdapter uses SET key 1 NX EX ttl — atomic, race-condition free.

---

Payment webhooks

Receive a signed event after each payment.

import { l402, verifyWebhook } from 'l402-kit';

app.get('/api/data', l402({
  priceSats: 10,
  lightning,
  webhookUrl: 'https://yourapi.com/webhooks/l402',
  webhookSecret: process.env.L402_WEBHOOK_SECRET!,
}), handler);

// Webhook receiver
app.post('/webhooks/l402', express.raw({ type: '*/*' }), (req, res) => {
  const valid = verifyWebhook(
    process.env.L402_WEBHOOK_SECRET!,
    req.body.toString(),
    req.headers['l402-signature'] as string,
  );
  if (!valid) return res.status(401).end();

  const event = JSON.parse(req.body.toString());
  console.log('Payment:', event.data.paymentHash, event.data.amountSats);
  res.json({ ok: true });
});

Webhook payload:

{
  "id": "evt_abc123",
  "type": "payment.received",
  "created": 1700000000,
  "data": {
    "endpoint": "/api/data",
    "amountSats": 10,
    "paymentHash": "sha256-of-preimage"
  }
}

---

onPayment callback

Synchronous hook called after each verified payment, before next():

app.get('/api/data', l402({
  priceSats: 10,
  lightning,
  onPayment: async ({ macaroon, preimage }, amountSats) => {
    await myAnalytics.track('payment', { amountSats });
  },
}), handler);

---

Supabase payment logging

Set SUPABASE_URL + SUPABASE_ANON_KEY in your environment to log payments automatically.

app.get('/api', l402({ priceSats: 10, lightning }), handler);
// SUPABASE_URL and SUPABASE_ANON_KEY are read from process.env automatically

Payments table schema (payments):

create table payments (
  id            uuid primary key default gen_random_uuid(),
  payment_hash  text unique not null,  -- SHA256(preimage) — safe to store
  endpoint      text,
  amount_sats   integer,
  paid_at       timestamptz default now()
);

payment_hash stores SHA256(preimage), not the raw preimage. The preimage is the 32-byte Lightning payment secret — its hash is already public in the BOLT11 invoice.

---

Standalone utilities

import { verifyToken, parseToken, checkAndMarkPreimage } from 'l402-kit';

// Verify a token (returns true/false)
const isValid = await verifyToken('eyJoYXNoIjoi...:deadbeef...');

// Parse token parts
const { macaroon, preimage } = parseToken(token);

// Custom replay check (returns true = first use, false = replay)
const isFirstUse = await checkAndMarkPreimage(preimage);

---

Types

import type { L402Options, LightningProvider, Invoice, L402Token } from 'l402-kit';

interface L402Options {
  priceSats: number;
  lightning: LightningProvider;
  supabaseUrl?: string;
  supabaseKey?: string;
  onPayment?: (token: L402Token, amountSats: number) => void | Promise<void>;
  webhookUrl?: string;
  webhookSecret?: string;
  replayAdapter?: ReplayAdapter;
}

interface Invoice {
  paymentRequest: string;
  paymentHash: string;
  macaroon: string;
  amountSats: number;
  expiresAt: number;        // Unix ms
}

interface LightningProvider {
  createInvoice(amountSats: number): Promise<Invoice>;
  checkPayment(paymentHash: string): Promise<boolean>;
}

---

Verification timing

Token verification runs SHA256(preimage) == paymentHash in memory — sub-millisecond, no network call on the hot path.

The in-memory ReplayAdapter (default) also runs synchronously. If you use RedisReplayAdapter, add a 5–50 ms Redis round-trip per request. Plan capacity accordingly for high-frequency endpoints.

---

x402 compatibility (X-Payment header)

The middleware silently accepts the X-Payment header (used by Coinbase’s x402 protocol) in addition to the standard Authorization: L402 … header. Both are treated identically — useful if you want to serve clients that speak either protocol.

// Client using x402 header — handled transparently
// X-Payment: <macaroon>:<preimage>

No configuration needed; it is always enabled.

---

Migration guide

v1.1 → v1.2

Rename column in your payments table:

ALTER TABLE payments RENAME COLUMN preimage TO payment_hash;