@te-btc/cashu-l402

Cashu ecash ↔ L402 settlement bridge. Atomic exchange between Cashu proofs and L402 access tokens.

What

Framework-agnostic TypeScript library for gating API endpoints behind Bitcoin micropayments. Supports both:

• L402 — Lightning invoice + macaroon token flow (HTTP 402)
• Cashu NUT-24 — Ecash proof payment (blinded, instant, no LN round-trip)
• Dual challenge — Offer both payment methods simultaneously
• Spending conditions — Detect NUT-10/11/14 conditions (P2PK, HTLCs, time-locks, proof-of-service)

Install

npm install @te-btc/cashu-l402

Quick Start

Server — Gate an endpoint

import {
  createL402Challenge,
  verifyCashuPayment,
  detectPaymentMethod,
  buildDualChallenge,
} from '@te-btc/cashu-l402';

// In your route handler (Fastify, Express, Hono, etc.)
async function premiumEndpoint(req, res) {
  const auth = req.headers.authorization;
  const { method, token } = detectPaymentMethod(auth);

  if (method === 'cashu' && token) {
    const result = await verifyCashuPayment(token, {
      priceSats: 100,
      mintUrl: 'https://mint.example.com',
    });
    if (result.paid) return { data: 'premium content' };
  }

  // Issue 402 challenge
  const headers = buildDualChallenge({ priceSats: 100, mintUrl: 'https://mint.example.com' });
  res.status(402).headers(headers).send({ error: 'Payment required' });
}

Client — Auto-pay with L402

import { l402Fetch } from '@te-btc/cashu-l402';

// Provide your own Lightning payment function
const payInvoice = async (bolt11: string) => {
  const result = await myLndClient.sendPayment(bolt11);
  return { preimage: result.preimage, feeSats: result.fee };
};

// Fetch with automatic 402 handling
const response = await l402Fetch(
  'https://api.example.com/premium',
  payInvoice,
  {},
  1000, // max 1000 sats
);

API

Cashu Paywall (NUT-24)

Function	Description
parseCashuAuthHeader(header)	Extract token from Cashu <token> header
buildCashuChallenge(config)	Build WWW-Authenticate challenge
verifyCashuPayment(token, config)	Full verification + double-spend prevention
detectPaymentMethod(header)	Detect L402 vs Cashu vs none
buildDualChallenge(config, l402?)	Both challenges in one 402 response

L402 Server

Function	Description
createL402Challenge(params)	Generate macaroon + request invoice
verifyL402Token(params)	Verify macaroon signature + preimage
signMacaroon(payload, rootKey)	HMAC-SHA256 sign a macaroon
verifyMacaroon(token, rootKey)	Verify macaroon (timing-safe)
verifyPreimage(preimage, rHash)	SHA-256 preimage check (constant-time)

L402 Client

Function	Description
parseL402Challenge(header)	Parse macaroon + invoice from WWW-Authenticate
buildL402Header(token)	Build L402 <mac>:<preimage> header
l402Fetch(url, payFn, opts?, max?)	Auto-pay fetch with token caching

Spending Conditions

Function	Description
parseNut10Secret(secret)	Parse NUT-10 well-known secret format
detectConditions(proof)	Detect P2PK, HTLC, PoS, time-locks on a proof
extractConditionCaveats(info)	Convert conditions to macaroon caveats
prevalidateCondition(proof, time?)	Client-side locktime validation

Spend Router

Function	Description
routePayment(params)	Choose optimal backend (cashu/lightning/fedimint)

Ecosystem Positioning

This library occupies a unique niche — no standalone TypeScript L402+Cashu bridge exists.

	@te-btc/cashu-l402	x402 (Coinbase/Stripe)	aperture (Lightning Labs)
Settlement	Cashu ecash (blinded, instant) + Lightning fallback	USDC on EVM L2s	Lightning only
Privacy	Blinded bearer proofs (NUT-12 DLEQ)	On-chain (transparent)	Invoice-linked
Offline capable	Yes (P2PK+DLEQ local verification)	No (on-chain settlement)	No (LN routing required)
Spending conditions	NUT-10/11/14 (P2PK, HTLC, PoS, escrow)	None	Macaroon caveats only
Language	TypeScript (Node.js)	TypeScript + Go	Go

Complements Lightning Agent Tools (Lightning Labs, Feb 2026) — agents use their MCP server for LN reconnaissance, our library for Cashu settlement. Validates Fewsats pattern — policy engine + L402 for safe agent payments. Ahead of NIST — AI Agent Standards Initiative (early 2026) is formalizing the security controls this library already implements.

Scripts

Script	Description
npm run build	Compile TypeScript to dist/
npm run typecheck	Type-check without emitting
npm test	Run test suite
npm run lint	Lint with Biome

License

MIT