クイックスタート

ゼロから60秒で有料APIを構築する。

▶ まず402フローを見る

インタラクティブなターミナルデモ — リクエスト → 402 → Lightning支払い → 200 OK の流れをブラウザでライブ確認できます。

オプション A — 1コマンドでフルサーバーをスキャフォールド（最速）

npx create-l402-app my-api

これにより、完全な Express + l402-kit プロジェクトが作成されます: 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 手数料
最適な用途	素早く始める	ボリューム / 本番環境

迷ったら？ Managed から始めましょう — ノード不要、アカウント不要、Lightning アドレスだけでOKです。0% 手数料が必要になったら、コード1行で Soberano に切り替えられます。切り替え後も、支払い済みトークンはそのまま使い続けられます。

Lightning アドレスを取得する（無料、2分）: dashboard.blink.sv でサインアップすると [e-mail] が発行されます。または Alby、Phoenix、Wallet of Satoshi を使うこともできます。

Soberano セットアップ: dashboard.blink.sv でサインアップ → API Keys → キーを作成 → ウォレットページから BTC Wallet ID をコピー。.env に BLINK_API_KEY と BLINK_WALLET_ID を設定してください。

2. インストール

TypeScript

npm install l402-kit

3. APIに追加する

Managed (⭐ 推奨)

Lightning ノード不要 — Lightning アドレスだけで使えます。

Express

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

const app = express();
const lightning = ManagedProvider.fromAddress("[e-mail]");

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

Soberano (0% 手数料 — Blink)

あなた自身の Lightning ウォレットを使います。dashboard.blink.sv でサインアップして、API Key と BTC Wallet ID をコピーしてください。

Express

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..."
}

任意の Lightning ウォレットでインボイスを支払い、その後:

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 ✓

サンドボックスを使った実際の課金テストには、OpenNode の testMode を使用してください:

const lightning = new OpenNodeProvider(process.env.OPENNODE_KEY!, true); // testMode: 実際の sats は不要

テストの完全ガイド → テスト