nodana
SDKs / phoenixd-l402-sdk

phoenixd-l402-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

Connect to your node

For a Nodana-hosted node, copy its complete HTTPS URL from the node details in the dashboard. Use the limited-access Phoenixd password you saved when creating the node. For your own Phoenixd daemon, use its reachable URL and the http-password-limited-access value from its configuration.

Set these variables in your backend's environment or secret settings:

VariableValue
PHOENIXD_URLYour node's URL, for example https://node-a1b2.nodana.app
PHOENIXD_PASSWORDYour limited-access Phoenixd password
L402_SECRET_KEYA signing secret you generate for your application

Generate the signing secret once:

openssl rand -hex 32

Save the output as L402_SECRET_KEY. It signs your application's payment challenges. Keep the same value across deployments and application instances so outstanding challenges remain valid. Keep the secret and node password private in your backend.

The new Phoenixd(...) call below connects your backend directly to your node using its URL and password.

Charge for a request

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.

On this page