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-tsConnect 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:
| Variable | Value |
|---|---|
PHOENIXD_URL | Your node's URL, for example https://node-a1b2.nodana.app |
PHOENIXD_PASSWORD | Your limited-access Phoenixd password |
L402_SECRET_KEY | A signing secret you generate for your application |
Generate the signing secret once:
openssl rand -hex 32Save 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.