x402 over Lightning Network - API

Lightning Network による支払いが必要な REST API です。x402 HTTP Transport Specification v2 に完全準拠しています。

API エンドポイント

使い方

1. 初回リクエスト 402 Payment Required

curl -i -X POST https://simpl402.ocknamo.com/nostr/badge-challenge \
  -H "Content-Type: application/json" \
  -d '{"npub":"npub1xxxxxxx9dzc"}'

レスポンスに x402 v2 形式の PAYMENT-REQUIRED ヘッダーが返されます。

HTTP/1.1 402 Payment Required
Content-Type: application/json
PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6MiwgImVycm9yIjogIi4uLiIsICJyZXNvdXJjZSI6IHsuLi59LCAiYWNjZXB0cyI6IFt7Li4ufV19

{"error":"Payment required"}

2. PAYMENT-REQUIRED のデコード

echo "eyJ4NDAyVmVyc2lvbiI6Mi4uLiJ9" | base64 -d | jq

x402 v2 形式のペイロード：

{
  "x402Version": 2,
  "error": "Payment required",
  "resource": {
    "url": "https://simpl402.ocknamo.com/nostr/badge-challenge",
    "description": "Issue a NIP-58 badge award",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "bip122:000000000019d6689c085ae165831e93",
      "amount": "100000",
      "asset": "BTC",
      "payTo": "anonymous",
      "maxTimeoutSeconds": 3600,
      "extra": {
        "paymentMethod": "lightning",
        "invoice": "lnbc1..."
      }
    }
  ]
}

3. Invoice の支払い

accepts[0].extra.invoice の値を Lightning ウォレットで支払います（100 sats固定）。

3.5. PAYMENT-SIGNATURE ペイロードの構築

支払い後、x402 v2 形式の PAYMENT-SIGNATURE ヘッダーを構築します。

構築されたペイロードの中身（Base64デコード前）：

{
  "x402Version": 2,
  "resource": {
    "url": "https://simpl402.ocknamo.com/nostr/badge-challenge",
    "description": "Issue a NIP-58 badge award",
    "mimeType": "application/json"
  },
  "accepted": {
    "scheme": "exact",
    "network": "bip122:000000000019d6689c085ae165831e93",
    "amount": "100000",
    "asset": "BTC",
    "payTo": "anonymous",
    "maxTimeoutSeconds": 3600,
    "extra": {
      "paymentMethod": "lightning",
      "invoice": "lnbc1..."
    }
  },
  "payload": {
    "invoice": "lnbc1..."
  }
}

4. 支払い後のアクセス 200 OK

x402 v2 形式の PAYMENT-SIGNATURE ヘッダーを送信：

curl -i -X POST https://simpl402.ocknamo.com/nostr/badge-challenge \
  -H "Content-Type: application/json" \
  -H "PAYMENT-SIGNATURE: eyJ4NDAyVmVyc2lvbiI6MiwgInJlc291cmNlIjogey4uLn0sICJhY2NlcHRlZCI6IHsuLi59LCAicGF5bG9hZCI6IHsuLi59fQ==" \
  -d '{"npub":"npub1xxxxxxx9dzc"}'

支払い検証後、PAYMENT-RESPONSE ヘッダーと共にバッジ発行結果が返されます：

HTTP/1.1 200 OK
Content-Type: application/json
PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVlLCJ0cmFuc2FjdGlvbiI6ImxuYmMxLi4uIiwibmV0d29yayI6ImxpZ2h0bmluZzpiaXRjb2luIiwicGF5ZXIiOiJhbm9ueW1vdXMiLCJleHRyYSI6eyJpbnZvaWNlIjoibG5iYzEuLi4iLCJzZXR0bGVkQXQiOjE3MzkxMTY4MDB9fQ==

{"success":true,"eventId":"abc123...","message":"Badge awarded successfully"}

x402 v2 ヘッダー

• PAYMENT-REQUIRED: サーバーが支払い要求を送信（resource、accepts配列を含む）
• PAYMENT-SIGNATURE: クライアントが支払い情報を送信（x402Version、resource、accepted、payloadを含む）
• PAYMENT-RESPONSE: サーバーが決済結果を返却（success、transaction、errorReasonなどを含む）

セキュリティ

• 各 invoice は一度のみ使用可能
• 期限切れ invoice は自動的に拒否
• coinos.io Lightning ノードで支払い検証
• x402 v2 仕様に完全準拠

技術スタック

• x402 HTTP Transport Specification v2
• Cloudflare Workers
• Lightning Network（coinos.io API）
• TypeScript

終了したイベント

simpl402チャレンジ