phoenixd-l402-sdk

Nodana also provides hosted L402 API endpoints that handle invoices, payment verification and redemption records. Follow the L402 integration guide to use the API instead of integrating the SDK.

Use @nodana/phoenixd-l402-sdk to create Lightning invoices and verify L402 payment credentials through your Phoenixd node. It connects using phoenixd-ts. Your application records payments and controls resource access.

Install

Use Node.js 22.12 or later:

$ npm install @nodana/phoenixd-l402-sdk @nodana/phoenixd-ts

Charge for a request

Set PHOENIXD_URL, the restricted password as PHOENIXD_PASSWORD, and an application signing secret as L402_SECRET_KEY. Generate the secret with openssl rand -hex 32 and retain it across deployments.

L402.create configures invoice creation and credential verification directly. This example charges 100 sats per request using your application's database function:

import { Phoenixd } from "@nodana/phoenixd-ts";
import { L402 } from "@nodana/phoenixd-l402-sdk";
import { db } from "./database"; // Your application's database functions.

const node = new Phoenixd(process.env.PHOENIXD_URL!, process.env.PHOENIXD_PASSWORD!);
const payments = L402.create({
  client: node,
  secretKey: process.env.L402_SECRET_KEY!,
});
const check = payments.charge({ amount: "100", description: "Weather report" });

export async function handler(request: Request): Promise<Response> {
  const proof = await check(request);
  if (proof.status === 402) return proof.challenge;

  // A unique payment-hash insert makes each payment usable once in this application.
  const recorded = await db.recordPaymentOnce(proof.payment.paymentHash);
  if (!recorded) return new Response("Payment already used", { status: 409 });

  return Response.json({ weather: "sunny" }, { headers: { "Cache-Control": "no-store" } });
}

Mount handler at your paid endpoint. check(request) returns either a payment challenge (status: 402) or verified payment details (status: 200). Run your protected operation after verification and successful payment recording.

db.recordPaymentOnce is a function you implement in your application. Use a unique payment-hash insert: return true for the first insert, false for an existing payment, and throw on other database errors. This makes each payment usable once. Your own payment records can support other access policies.

See the L402 integration guide for access policies, expiry and troubleshooting.