nodana
SDKs / phoenixd-mpp-sdk

phoenixd-mpp-sdk

Use @nodana/phoenixd-mpp-sdk to create Lightning invoices and verify MPP payment proofs through your Phoenixd node. It supplies a custom mppx receiving method using phoenixd-ts.

Install

Use Node.js 22.12 or later:

npm install @nodana/phoenixd-mpp-sdk @nodana/phoenixd-ts mppx

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
MPP_SECRET_KEYA signing secret you generate for your application

Generate the signing secret once:

openssl rand -hex 32

Save the output as MPP_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

phoenixd.charge supplies the Lightning payment method. Register it with Mppx.create, which handles payment challenges and receipts. This example charges 100 sats per request using your application's database functions:

import { Challenge, Errors } from "mppx";
import { Phoenixd } from "@nodana/phoenixd-ts";
import { Mppx, phoenixd } from "@nodana/phoenixd-mpp-sdk";
import { db } from "./database"; // Your application's database functions.

const node = new Phoenixd(process.env.PHOENIXD_URL!, process.env.PHOENIXD_PASSWORD!);
const lightning = phoenixd.charge({ client: node });

const payments = Mppx.create({
  secretKey: process.env.MPP_SECRET_KEY!,
  methods: [
    {
      ...lightning,
      async verify(context: Parameters<typeof lightning.verify>[0]) {
        const receipt = await lightning.verify(context);
        const challenge = context.credential.challenge;
        const accepted = await db.redeemChallengeOnce({
          id: challenge.id,
          challenge: Challenge.serialize(challenge),
          paymentHash: receipt.reference,
        });
        if (!accepted) throw new Errors.PaymentRequiredError();
        return receipt;
      },
    },
  ],
});

export async function handler(request: Request): Promise<Response> {
  const payment = await payments.charge({ amount: "100" })(request);

  if (payment.status === 402) {
    const challenge = Challenge.fromResponse(payment.challenge);
    await db.saveChallenge({
      id: challenge.id,
      challenge: Challenge.serialize(challenge),
      expiresAt: Date.parse(challenge.expires!),
    });
    return payment.challenge;
  }

  return payment.withReceipt(Response.json({ answer: "Your paid result" }));
}

Mount handler at your paid endpoint. db.saveChallenge and db.redeemChallengeOnce are functions you implement in your application. Save the exact challenge and expiry before returning the 402 response. On redemption, compare it with the saved original, check expiry, and atomically mark it used with a unique payment hash. Return false for an invalid or reused challenge and throw on database errors.

Run your protected operation after successful verification and redemption, then attach the payment receipt with payment.withReceipt.

See the MPP integration guide for database requirements, expiry and troubleshooting.

On this page