phoenixd-mpp-sdk

This sdk was build by GPT-6.1 Sol. Please get in touch if there are any issues.

Use @nodana/phoenixd-mpp-sdk to accept or send Lightning payments for API requests through the Machine Payments Protocol (MPP). It connects mppx payment handlers to your node through phoenixd-ts.

Install

Use Node.js 22.12 or later:

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

Charge for an API request

Set PHOENIXD_URL to your node's HTTPS endpoint and PHOENIXD_PASSWORD to its restricted password (http-password-limited-access). Set MPP_SECRET_KEY to a signing secret generated with openssl rand -hex 32. Keep these values in your backend's environment.

import { Phoenixd } from "@nodana/phoenixd-ts";
import { Mppx, phoenixd } from "@nodana/phoenixd-mpp-sdk/server";

const node = new Phoenixd(process.env.PHOENIXD_URL!, process.env.PHOENIXD_PASSWORD!);
const payments = Mppx.create({
  methods: [phoenixd.charge({ client: node })],
  secretKey: process.env.MPP_SECRET_KEY!,
});

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

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

Mount the handler at your paid endpoint. An unpaid request receives a payment challenge. Once payment is accepted, the handler returns the result and a receipt. Replace the sample result with your query or tool call, keeping that work after the payment check. amount: "100" charges 100 sats.

The example uses in-memory payment state. Use Redis for deployed services; see the MPP guide for setup, pricing and expiry. The client entry point, @nodana/phoenixd-mpp-sdk/client, can pay for requests using a funded node and its full-access password.