TypeScript SDK

l402-kit TypeScript/Node.js SDK का पूर्ण संदर्भ — Bitcoin Lightning pay-per-call APIs के लिए Express middleware।

​

इंस्टॉलेशन

npm install l402-kit

आवश्यकताएं: Node.js 18+, Express 4+

---

​

त्वरित शुरुआत

आपका wallet (0% शुल्क)

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

const app = express();

// भुगतान सीधे आपके Blink wallet में जाते हैं — 0% शुल्क
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 (कोई node आवश्यक नहीं)

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

const app = express();

// l402kit.com node होस्ट करता है। आपको प्रत्येक भुगतान का 99.7% प्राप्त होता है।
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

एक Express RequestHandler लौटाता है जो route पर L402 भुगतान लागू करता है।

​

विकल्प

विकल्प	प्रकार	डिफ़ॉल्ट	विवरण
priceSats	number	आवश्यक	प्रति कॉल satoshis में मूल्य
lightning	LightningProvider	आवश्यक	आपका Lightning backend
supabaseUrl	string	SUPABASE_URL env	भुगतान लॉगिंग के लिए Supabase URL
supabaseKey	string	SUPABASE_ANON_KEY env	भुगतान लॉगिंग के लिए Supabase key
onPayment	(token, amountSats) => void	—	प्रत्येक सत्यापित भुगतान के बाद callback
webhookUrl	string	—	हस्ताक्षरित भुगतान events प्राप्त करने के लिए आपका endpoint
webhookSecret	string	—	webhook signing के लिए HMAC-SHA256 secret
replayAdapter	ReplayAdapter	in-memory	Pluggable replay protection backend

​

व्यवहार

अनुरोध	प्रतिक्रिया
कोई Authorization header नहीं	BOLT11 invoice + macaroon के साथ 402 Payment Required
वैध L402 <macaroon>:<preimage>	next() — handler निष्पादित होता है
अमान्य या समाप्त token	401 Unauthorized
Replayed preimage	401 Token already used

​

402 प्रतिक्रिया body

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

​

WWW-Authenticate header

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

---

​

Providers

​

AlbyProvider — soberano mode के लिए अनुशंसित

Alby — self-custodial wallet। आप keys नियंत्रित करते हैं।

import { AlbyProvider } from 'l402-kit';

// 1. hub.getalby.com पर एक Alby Hub बनाएं (या self-host करें)
// 2. Settings → Access Tokens → token बनाएं (scopes: invoices:create, invoices:read)
const lightning = new AlbyProvider(
  process.env.ALBY_ACCESS_TOKEN!, // Hub access token
  process.env.ALBY_HUB_URL!,      // जैसे "https://your-name.getalby.com"
);

​

BTCPayProvider — self-hosted, शून्य विश्वास

अपना खुद का BTCPay Server चलाएं। पूर्ण स्वायत्तता।

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, सबसे आसान शुरुआत

Blink — छोटी राशि के लिए मुफ़्त, बिना KYC।

import { BlinkProvider } from 'l402-kit';

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

​

LNbitsProvider

Self-hosted या legend.lnbits.com।

import { LNbitsProvider } from 'l402-kit';

const lightning = new LNbitsProvider(
  process.env.LNBITS_API_KEY!,
  'https://your-lnbits-instance.com', // वैकल्पिक, डिफ़ॉल्ट legend.lnbits.com है
);

​

OpenNodeProvider

import { OpenNodeProvider } from 'l402-kit';

const lightning = new OpenNodeProvider(
  process.env.OPENNODE_API_KEY!,
  false, // testMode — sandbox के लिए true करें
);

​

ManagedProvider — cloud mode (0.3% शुल्क)

l402kit.com Lightning node होस्ट करता है। आपको प्रत्येक भुगतान का 99.7% प्राप्त होता है। स्पष्ट opt-in।

import { ManagedProvider } from 'l402-kit';

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

// वैकल्पिक: सार्वजनिक API directory में auto-register करें
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 startup पर एक बार होती है (fire-and-forget, त्रुटियाँ silent रहती हैं)। API l402kit.com/apis.json पर दिखाई देती है ताकि agents इसे स्वतः खोज सकें।

---

​

Replay protection

​

डिफ़ॉल्ट — in-memory (विकास)

Built-in। restart पर reset होता है। 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 seconds में (24 घंटे)
);

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

RedisReplayAdapter SET key 1 NX EX ttl उपयोग करता है — atomic, race-condition मुक्त।

---

​

Payment webhooks

प्रत्येक भुगतान के बाद एक हस्ताक्षरित event प्राप्त करें।

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

प्रत्येक सत्यापित भुगतान के बाद, next() से पहले synchronous hook:

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

---

​

Supabase payment logging

भुगतान स्वचालित रूप से लॉग करने के लिए अपने environment में SUPABASE_URL + SUPABASE_ANON_KEY सेट करें।

app.get('/api', l402({ priceSats: 10, lightning }), handler);
// SUPABASE_URL और SUPABASE_ANON_KEY स्वचालित रूप से process.env से पढ़े जाते हैं

Payments table schema (payments):

create table payments (
  id            uuid primary key default gen_random_uuid(),
  payment_hash  text unique not null,  -- SHA256(preimage) — store करना सुरक्षित
  endpoint      text,
  amount_sats   integer,
  paid_at       timestamptz default now()
);

payment_hash में SHA256(preimage) संग्रहीत होता है, raw preimage नहीं। preimage 32-byte Lightning payment secret है — इसका hash BOLT11 invoice में पहले से सार्वजनिक है।

---

​

स्वतंत्र उपयोगिताएं

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

// एक token सत्यापित करें (true/false लौटाता है)
const isValid = await verifyToken('eyJoYXNoIjoi...:deadbeef...');

// token के भाग parse करें
const { macaroon, preimage } = parseToken(token);

// कस्टम replay जांच (true = पहला उपयोग, false = replay)
const isFirstUse = await checkAndMarkPreimage(preimage);

---

​

प्रकार

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

---

​

सत्यापन समय

Token सत्यापन memory में SHA256(preimage) == paymentHash चलाता है — sub-millisecond, hot path पर कोई network call नहीं।

in-memory ReplayAdapter (डिफ़ॉल्ट) भी synchronously चलता है। यदि आप RedisReplayAdapter उपयोग करते हैं, तो प्रति अनुरोध 5–50 ms Redis round-trip जोड़ें। उच्च-आवृत्ति endpoints के लिए क्षमता की योजना तदनुसार बनाएं।

---

​

x402 compatibility (X-Payment header)

middleware चुपचाप X-Payment header स्वीकार करता है (Coinbase के x402 protocol द्वारा उपयोग किया जाता है) मानक Authorization: L402 … header के अतिरिक्त। दोनों को समान रूप से संभाला जाता है — उपयोगी यदि आप उन clients को serve करना चाहते हैं जो किसी भी protocol में बात करते हैं।

// x402 header का उपयोग करने वाला Client — पारदर्शी रूप से संभाला जाता है
// X-Payment: <macaroon>:<preimage>

कोई configuration आवश्यक नहीं; यह हमेशा सक्षम है।

---

​

Migration guide

​

v1.1 → v1.2

अपनी payments table में column का नाम बदलें:

ALTER TABLE payments RENAME COLUMN preimage TO payment_hash;