▶ まず402フローを見る
インタラクティブなターミナルデモ — リクエスト → 402 → Lightning支払い → 200 OK の流れをブラウザでライブ確認できます。
オプション A — 1コマンドでフルサーバーをスキャフォールド（最速）
npx create-l402-app my-api
server.ts、.env.example、tsconfig.json、そして Lightning 支払いを受け付ける準備が整った /premium エンドポイントが含まれます。
my-api/
src/server.ts ← l402 ミドルウェアを含むあなたのAPI
.env.example ← Blink/OpenNode 認証情報テンプレート
package.json ← npm install l402-kit + tsx
tsconfig.json
README.md
cd my-api
cp .env.example .env # Blink APIキーを追加
npm install
npm run dev
# ⚡ l402-kit server running on http://localhost:3000
# curl http://localhost:3000/premium → 402 Payment Required
オプション B — 既存プロジェクトに追加する
1. モードを選択する
| Managed ⭐ | Soberano |
|---|
| セットアップ時間 | 約2分 | 約5分 |
| 月額費用 | $0 | $0 |
| トランザクションごとの手数料 | 0.3% | 0% |
| 必要なもの | Lightning アドレス | Blink / Alby / BTCPay アカウント |
| 10,000 sats の処理 | 30 sat 手数料 | $0 手数料 |
| 最適な用途 | 素早く始める | ボリューム / 本番環境 |
yourname@blink.sv が発行されます。または Alby、Phoenix、Wallet of Satoshi を使うこともできます。
Soberano セットアップ: dashboard.blink.sv でサインアップ → API Keys → キーを作成 → ウォレットページから BTC Wallet ID をコピー。.env に BLINK_API_KEY と BLINK_WALLET_ID を設定してください。
2. インストール
3. APIに追加する
Lightning ノード不要 — Lightning アドレスだけで使えます。import express from "express";
import { l402, ManagedProvider } from "l402-kit";
const app = express();
const lightning = ManagedProvider.fromAddress("you@yourdomain.com");
app.get("/premium", l402({ priceSats: 100, lightning }), (_req, res) => {
res.json({ data: "You paid 100 sats. Here is your data." });
});
app.listen(3000);
// 0.3% fee · no node setup · works immediately
あなた自身の Lightning ウォレットを使います。dashboard.blink.sv でサインアップして、API Key と BTC Wallet ID をコピーしてください。import express from "express";
import { l402, BlinkProvider } from "l402-kit";
const app = express();
const lightning = new BlinkProvider(
process.env.BLINK_API_KEY!,
process.env.BLINK_WALLET_ID!,
);
app.get("/premium", l402({ priceSats: 100, lightning }), (_req, res) => {
res.json({ data: "You paid 100 sats. Here is your data." });
});
app.listen(3000);
4. テストする
curl http://localhost:3000/premium
{
"error": "Payment Required",
"price_sats": 100,
"invoice": "lnbc1u1p...",
"macaroon": "eyJoYXNo..."
}
curl http://localhost:3000/premium \
-H "Authorization: L402 <macaroon>:<preimage>"
{ "data": "You paid 100 sats. Here is your data." }
これであなたのAPIはビットコイン決済を受け付けられるようになりました。
実際の sats を使わずにテストする
インテグレーションのテストに Lightning ウォレットは必要ありません。モックプロバイダーを使いましょう — ネットワーク呼び出しなしで、有効な暗号トークンペアをローカルで生成します:
import { createHash, randomBytes } from "crypto";
import { l402 } from "l402-kit";
import type { LightningProvider, Invoice } from "l402-kit";
// Drop-in mock — generates real SHA256 hash/preimage pairs
function makeMockProvider(): LightningProvider & { preimage: string } {
const preimage = randomBytes(32).toString("hex");
const paymentHash = createHash("sha256").update(Buffer.from(preimage, "hex")).digest("hex");
return {
preimage, // use this in your test Authorization header
async createInvoice(amountSats: number): Promise<Invoice> {
const macaroon = Buffer.from(
JSON.stringify({ hash: paymentHash, exp: Date.now() + 3_600_000 })
).toString("base64");
return { paymentRequest: "lnbc_mock", paymentHash, macaroon, amountSats };
},
async checkPayment(): Promise<boolean> { return true; },
};
}
// Usage in tests:
const mock = makeMockProvider();
app.get("/premium", l402({ priceSats: 10, lightning: mock }), handler);
// Step 1 — unauthenticated → 402
const res402 = await request(app).get("/premium");
// res402.body.macaroon ← use this
// Step 2 — pay with mock preimage → 200
const res200 = await request(app)
.get("/premium")
.set("Authorization", `L402 ${res402.body.macaroon}:${mock.preimage}`);
// res200.status === 200 ✓
const lightning = new OpenNodeProvider(process.env.OPENNODE_KEY!, true); // testMode: 実際の sats は不要
