@powforge/x402-lightning

The only x402 Lightning facilitator that accepts payments from self-custodial NWC wallets.

If you are building an MCP server or HTTP API that needs to charge agents per call, and you want those agents to be able to pay from a wallet they actually control (Alby Hub, Mutiny, Zeus, Phoenixd-via-bridge), this is the facilitator you wire in.

Why this exists

There is already a deployed buyer in the wild that needs an answer to this question.

forgesworn/402-mcp is an L402 + x402 client MCP that lets AI agents discover, pay for, and consume any payment-gated API autonomously. It supports four payment rails. Lightning over NWC is priority one for autonomous flows because NWC is the only Lightning rail that does not require giving the agent your node credentials or trusting a custodian.

As of 2026-05-13, no other x402 facilitator implementation accepts NWC payments. The Coinbase CDP facilitator is EVM-only. The Rust x402-rs facilitator is EVM/SVM-only. The draft TypeScript Lightning PR (x402-foundation/x402#2262) ships LNBits + Blink, no NWC.

@powforge/x402-lightning v0.2.0 closes that gap. If your buyer pays from an NWC connection, this is the facilitator that settles them.

Why NWC

NWC is NIP-47, Nostr Wallet Connect. Three properties matter for x402:

• Self-custody by default. The buyer holds the keys. The facilitator never sees or stores them. The connection string is a capability token the buyer can revoke at any time.
• No intermediary required. Works against any NIP-47-compliant wallet. Alby Hub, Mutiny, Zeus v0.12+, Coinos, Primal, Flash. The buyer picks.
• Stateless on the facilitator side. No webhook config, no callback URL, no LND macaroon, no LNBits invoice key sitting in your env. Just a connection URI when you want to mint or look up invoices.

Custodial options (LNBits, Blink) are fine for some setups. They are also gated on whichever provider chose to onboard you. NWC routes around that.

Network identifiers

mainnet: bip122:000000000019d6689c085ae165831e93
testnet: bip122:000000000933ea01ad0ee984209779ba

Amount unit: millisatoshis (matching BOLT11 precision and the spec in x402-foundation/x402#1311).

Install

npm install @powforge/x402-lightning

Quick start: NWC backend (self-custody)

Paste a nostr+walletconnect://... URI from your wallet's NWC settings into NWC_URL and you have a working facilitator. No LNBits required.

const { createLightningFacilitator, LIGHTNING_MAINNET } = require('@powforge/x402-lightning');
const { createNwcBackend } = require('@powforge/x402-lightning/nwc');

const backend = createNwcBackend({
  nwcUrl: process.env.NWC_URL,        // nostr+walletconnect://...
  lookupTimeoutMs: 8000,              // optional, default 8000
});

const facilitator = createLightningFacilitator({ backend });

app.post('/verify', async (req, res) => {
  const { paymentPayload, paymentRequirements } = req.body;
  res.json(await facilitator.verify(paymentPayload, paymentRequirements));
});

app.post('/settle', async (req, res) => {
  const { paymentPayload, paymentRequirements } = req.body;
  res.json(await facilitator.settle(paymentPayload, paymentRequirements));
});

app.get('/supported', (req, res) => {
  res.json({ kinds: [{ x402Version: 2, scheme: 'exact', network: LIGHTNING_MAINNET }] });
});

The backend handles relay reconnect, request encryption (nip44_v2), and timeouts. Requests like make_invoice and lookup_invoice are dispatched over the relay your wallet picked.

Runnable smoke

A one-command end-to-end demo lives in examples/nwc-quickstart.js. It mints a 21-sat invoice, prints the bolt11, polls for settlement against your real wallet, and exits with structured JSON. Pair it with a buyer-side x402 client like forgesworn/402-mcp to validate the dual-rail story without writing any glue code.

NWC_URL=nostr+walletconnect://... node examples/nwc-quickstart.js

See examples/README.md for prereqs, expected output, and troubleshooting; examples/recorded-run.txt shows what a successful run looks like.

NWC install requirements

npm install @powforge/x402-lightning @getalby/sdk
# Node 18 or 20 only (Node 22+ has native WebSocket):
npm install websocket-polyfill

@getalby/sdk and websocket-polyfill are listed as optionalDependencies, so only operators using the NWC backend pull them in.

Tested NWC wallets

| Wallet | Self-custody | Notes | |---|---|---| | Alby Hub | yes | Direct | | Mutiny | yes | Direct | | Zeus v0.12+ | yes | Direct | | Coinos | no (custodial) | NWC enabled | | Primal Wallet | no (custodial) | NWC enabled | | Phoenixd | yes | Via satdress bridge |

Backend: LNBits (also supported)

If you already run LNBits, you can use it as the backend instead. Same facilitator surface.

const { createLightningFacilitator, createLnbitsBackend, LIGHTNING_MAINNET } = require('@powforge/x402-lightning');

const backend = createLnbitsBackend({
  lnbitsUrl: process.env.LNBITS_URL,
  lnbitsApiKey: process.env.LNBITS_INVOICE_KEY,  // NOT admin key
});

const facilitator = createLightningFacilitator({ backend });

Resource server (mints 402 responses)

const { createLightningServer, LIGHTNING_MAINNET } = require('@powforge/x402-lightning');

// backend can be NWC or LNBits, same shape either way
const server = createLightningServer({ backend });

const requirements = await server.enhancePaymentRequirements({
  scheme: 'exact',
  network: LIGHTNING_MAINNET,
  amount: '21000',        // 21000 msat = 21 sats
  asset: 'BTC',
  payTo: 'anonymous',
  maxTimeoutSeconds: 300,
  resource: { url: req.url },
});

res.status(402).setHeader('payment-required', btoa(JSON.stringify({ accepts: [requirements] })));

Client (pays invoices)

const { createLightningClient } = require('@powforge/x402-lightning');

const client = createLightningClient({
  pay: async (bolt11) => {
    await yourWallet.payInvoice(bolt11);
  },
});

const payload = await client.createPaymentPayload(2, requirements);
// Retry the request with the payment payload

Replay store options

By default, replay protection is in-memory and lost on restart. For production, use the SQLite store:

const { createSqliteReplayStore } = require('@powforge/x402-lightning/sqlite');
// requires: npm install better-sqlite3

const replayStore = createSqliteReplayStore('/data/x402-replay.db');
const facilitator = createLightningFacilitator({ backend, replayStore });

The store evicts expired hashes lazily on every isConsumed check. No cron required.

Custom backend

Any object with { createInvoice(msats, memo), checkPaid(hash) } works:

const backend = {
  async createInvoice(msats, memo) {
    return { payment_hash: '...', bolt11: 'lnbc...' };
  },
  async checkPaid(paymentHash) {
    return false;
  },
};

Security properties

• Anti-substitution: payload.invoice must equal requirements.extra.invoice. An attacker cannot swap in a different invoice they control.
• Replay protection: ReplayStore tracks consumed payment_hash values. Same invoice cannot be used twice.
• Amount check: BOLT11 prefix amount is decoded and checked against requirements.amount (msat).
• payTo: "anonymous": Per spec, the Lightning recipient is embedded in the invoice, not exposed as a signing address.

Protocol

The x402 Lightning flow:

1. Server mints a BOLT11 invoice and includes it in PaymentRequirements.extra.invoice.
2. Client pays the invoice out-of-band (any Lightning wallet, NWC or otherwise).
3. Client re-requests with payload.invoice = <same bolt11> as payment proof.
4. Facilitator verifies: invoice matches, settled, not replayed.
5. Server responds 200.

Ecosystem

• npm: @powforge/mcp-l402-gate, MCP L402 middleware
• PyPI: powforge, Python L402 decorator
• powforge.dev
• x402-foundation/x402#1311, Lightning spec PR
• x402-foundation/x402#2258, TS mechanism request
• getAlby/awesome-nwc, wallet + app inventory
• forgesworn/402-mcp, deployed NWC buyer that needs this facilitator

MIT · PowForge