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 mppxConnect 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 |
MPP_SECRET_KEY | A signing secret you generate for your application |
Generate the signing secret once:
openssl rand -hex 32Save 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.