TypeScript SDK

Referência completa para o SDK TypeScript/Node.js l402-kit — middleware Express para APIs Bitcoin Lightning com pagamento por chamada.

Instalação

npm install l402-kit

Requisitos: Node.js 18+, Express 4+

---

Início rápido

Sua carteira (0% de taxa)

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

const app = express();

// Pagamentos vão diretamente para sua carteira Blink — 0% de taxa
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);

Gerenciado (sem nó próprio)

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

const app = express();

// l402kit.com hospeda o nó. Você recebe 99,7% de cada pagamento.
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

Retorna um RequestHandler do Express que aplica pagamento L402 na rota.

Opções

Opção	Tipo	Padrão	Descrição
priceSats	number	obrigatório	Preço por chamada em satoshis
lightning	LightningProvider	obrigatório	Seu backend Lightning
supabaseUrl	string	env SUPABASE_URL	URL do Supabase para registro de pagamentos
supabaseKey	string	env SUPABASE_ANON_KEY	Chave do Supabase para registro de pagamentos
onPayment	(token, amountSats) => void	—	Callback disparado após cada pagamento verificado
webhookUrl	string	—	Seu endpoint para receber eventos de pagamento assinados
webhookSecret	string	—	Segredo HMAC-SHA256 para assinatura de webhook
replayAdapter	ReplayAdapter	em memória	Backend plugável de proteção contra replay

Comportamento

Requisição	Resposta
Sem cabeçalho Authorization	402 Payment Required com fatura BOLT11 + macaroon
L402 <macaroon>:<preimage> válido	next() — handler é executado
Token inválido ou expirado	401 Unauthorized
preimage repetido	401 Token already used

Corpo da resposta 402

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

Cabeçalho WWW-Authenticate

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

---

Provedores

AlbyProvider — recomendado para modo soberano

Alby — carteira autocustodial. Você controla as chaves.

import { AlbyProvider } from 'l402-kit';

// 1. Crie um Alby Hub em hub.getalby.com (ou hospede você mesmo)
// 2. Configurações → Access Tokens → criar token (escopos: invoices:create, invoices:read)
const lightning = new AlbyProvider(
  process.env.ALBY_ACCESS_TOKEN!, // Token de acesso do Hub
  process.env.ALBY_HUB_URL!,      // ex.: "https://your-name.getalby.com"
);

BTCPayProvider — auto-hospedado, sem necessidade de confiança

Execute seu próprio BTCPay Server. Soberania total.

import { BTCPayProvider } from 'l402-kit';

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

BlinkProvider — custodial, início mais fácil

Blink — gratuito, sem KYC para pequenos valores.

import { BlinkProvider } from 'l402-kit';

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

LNbitsProvider

Auto-hospedado ou legend.lnbits.com.

import { LNbitsProvider } from 'l402-kit';

const lightning = new LNbitsProvider(
  process.env.LNBITS_API_KEY!,
  'https://your-lnbits-instance.com', // opcional, padrão é legend.lnbits.com
);

OpenNodeProvider

import { OpenNodeProvider } from 'l402-kit';

const lightning = new OpenNodeProvider(
  process.env.OPENNODE_API_KEY!,
  false, // testMode — defina como true para sandbox
);

ManagedProvider — modo cloud (0,3% de taxa)

l402kit.com hospeda o nó Lightning. Você recebe 99,7% de cada pagamento. Opt-in explícito.

import { ManagedProvider } from 'l402-kit';

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

// Opcional: registrar automaticamente no diretório público de APIs
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',
  },
});

O registro ocorre uma vez na inicialização (fire-and-forget, erros são silenciosos). A API aparece em l402kit.com/apis.json para que agentes possam descobri-la automaticamente.

---

Proteção contra replay

Padrão — em memória (desenvolvimento)

Integrado. Reinicia ao reiniciar o processo. Adequado para implantações de processo único.

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

Redis (produção — múltiplas instâncias)

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

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

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

RedisReplayAdapter usa SET key 1 NX EX ttl — atômico, sem condições de corrida.

---

Webhooks de pagamento

Receba um evento assinado após cada pagamento.

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);

// Receptor do webhook
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 });
});

Payload do webhook:

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

---

Callback onPayment

Hook síncrono chamado após cada pagamento verificado, antes de next():

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

---

Registro de pagamentos com Supabase

Defina SUPABASE_URL + SUPABASE_ANON_KEY em seu ambiente para registrar pagamentos automaticamente.

app.get('/api', l402({ priceSats: 10, lightning }), handler);
// SUPABASE_URL e SUPABASE_ANON_KEY são lidos de process.env automaticamente

Schema da tabela de pagamentos (payments):

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

payment_hash armazena SHA256(preimage), não o preimage bruto. O preimage é o segredo de pagamento Lightning de 32 bytes — seu hash já é público na fatura BOLT11.

---

Utilitários independentes

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

// Verificar um token (retorna true/false)
const isValid = await verifyToken('eyJoYXNoIjoi...:deadbeef...');

// Analisar partes do token
const { macaroon, preimage } = parseToken(token);

// Verificação de replay personalizada (retorna true = primeiro uso, false = replay)
const isFirstUse = await checkAndMarkPreimage(preimage);

---

Tipos

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>;
}

---

Tempo de verificação

A verificação do token executa SHA256(preimage) == paymentHash em memória — sub-milissegundo, sem chamada de rede no caminho crítico.

O ReplayAdapter em memória (padrão) também é executado de forma síncrona. Se você usar RedisReplayAdapter, adicione uma ida e volta ao Redis de 5–50 ms por requisição. Planeje a capacidade adequadamente para endpoints de alta frequência.

---

Compatibilidade com x402 (cabeçalho X-Payment)

O middleware aceita silenciosamente o cabeçalho X-Payment (usado pelo protocolo x402 da Coinbase) além do cabeçalho padrão Authorization: L402 …. Ambos são tratados de forma idêntica — útil se você quiser atender clientes que utilizam qualquer um dos protocolos.

// Cliente usando cabeçalho x402 — tratado de forma transparente
// X-Payment: <macaroon>:<preimage>

Nenhuma configuração é necessária; está sempre habilitado.

---

Guia de migração

v1.1 → v1.2

Renomeie a coluna em sua tabela payments:

ALTER TABLE payments RENAME COLUMN preimage TO payment_hash;