Thunder Bridge

A normal payment processor can throw you out over your age, your country or a line of business the regulator dislikes this season. Running your own Lightning node is the other extreme, because channels, liquidity and backups are a full-time job nobody wants before knowing whether the idea even breathes.

Thunder Bridge is the shortcut in between. The payer pays an invoice your own wallet issued, so the gateway never holds your sats and has nothing to take. Once the payment lands, your wallet releases the preimage, and that is the proof the money actually moved. Not an operator's promise, maths. 🧡

1. Get Blink from the App Store or Google Play and pick the non-custodial wallet during setup, twelve words and the keys on your side.
2. On the home screen, tap Settings in the upper right.
3. Tap Your Blink address, then Set your Blink Address, and pick a username with no spaces and no special characters.
4. Done, the address reads name@blink.sv. Paste it into the demo below and see whether the sats land.

Leave the custodial version alone. Keys somebody else holds are somebody else's money. Blink also stops payments on custodial accounts after 31 August 2026, so it is a dead end in practice too. The non-custodial account runs on Spark, with an exit to the chain, and the name@blink.sv address stays the same.

If you would rather not use Blink

The wallet has to speak LUD-21, otherwise there is nothing to prove the payment arrived. These were measured doing it, ranked by how much custody stays with you.

• BTCPay Server from v2.3.8. Your own node, nobody else in the path of the money.
• The Spark-based wallets. Cake.cash, breez.tips, stacked.cash or Blitz Wallet. Self-custody with an exit to the chain.
• Alby Hub. Your own LDK node, addressed through getalby.com.
• coinos. Open source and self-hostable. The hosted coinos.io is custodial.
• stacker.news and Speed work too, but they hold your money.

It does not work with Wallet of Satoshi, Strike, Cash App, ZBD, Primal, Fountain or LNbits. ZEUS Pay does serve verify but releases no preimage, which amounts to the same thing. Minibits and Ark do speak LUD-21, but they never pin the invoice to their metadata, so the gateway refuses them as well. Support belongs to the address domain rather than the app, so when in doubt, paste the address into the demo below. It is refused as the invoice is created, not after somebody has already paid.

npm install thunder-bridge

On your server: the invoice and the watch

import { ThunderBridge } from "thunder-bridge";
import { invoiceFrom, relayedVerifyUrl } from "thunder-bridge/server";

const gateway = new ThunderBridge("https://thunder-bridge-production.up.railway.app", {
  secret: process.env.RAIL_SECRET,
});

const invoice = await invoiceFrom(["you@blink.sv"], 21_000);

const watched = await gateway.watchPayment({
  paymentHash: invoice.paymentHash,
  verifyUrl: await relayedVerifyUrl(
    "https://your.site/verify/lightning",
    { url: invoice.verifyUrl, hash: invoice.paymentHash },
    process.env.RAIL_SECRET,
  ),
  expiresAt: Math.min(invoice.expiresAt, Math.floor(Date.now() / 1000) + 3600),
});

return Response.json({ id: watched.id, bolt11: invoice.bolt11 });

In the browser: the QR and the wait

import { ThunderBridge, invoiceToSvg } from "thunder-bridge";

const gateway = new ThunderBridge("https://thunder-bridge-production.up.railway.app");
const { id, bolt11 } = await (await fetch("/api/invoice", { method: "POST" })).json();

document.querySelector("#qr").innerHTML = invoiceToSvg(bolt11);

const settled = await gateway.waitForWatched(id);

Your server resolves the address, the wallet issues the invoice, and the gateway is handed only a payment hash and a URL to poll. That URL is yours, not the wallet's: relayedVerifyUrl seals the wallet's into it, so the gateway does not even learn the host. Cap the expiry, it watches for three days at most and wallets write longer ones. The browser then waits on a socket with no secret at all, and waitForWatched returns paid only once the preimage hashes to that payment hash, otherwise it throws GatewayCheatError.

Webhook

import {
  answerWebhookChallengeRequest,
  isProvablySettled,
  parseSettlementRequest,
} from "thunder-bridge";

const signs = { publicKey: await gateway.webhookKey() };

export async function POST(request) {
  const challenge = await answerWebhookChallengeRequest(request, signs);
  if (challenge) return challenge;

  const settled = await parseSettlementRequest(request, signs);
  if (!settled) return new Response("bad signature", { status: 401 });
  if (!isProvablySettled(settled)) return new Response("no preimage", { status: 202 });

  unlock(settled.id);
  return new Response("ok");
}

The gateway signs every delivery with the key it publishes at /webhook-key, and there is no shared secret to register, so it holds nothing of yours. It challenges your URL before it takes the payment on and refuses it if nothing answers, so deploy the handler first and register it second. Delivery is at-least-once, so deduplicate on id.

The trigger and the address both have a working example in the repo, Deno Deploy for the address and the webhook, a watcher for the trigger.

Both then run on your account and your keys. The gateway behind the demo above is mine and it guarantees you nothing.

• The recipient must speak LUD-21. Wallet of Satoshi, Strike, Cash App, ZBD and Primal do not, and their addresses are refused up front.
• No privacy layer. The payer sees your real invoice and your node.
• No BOLT12. Fetching an invoice from an offer needs a node.
• The preimage proves your server released it. It protects the payer against the gateway, not against a recipient inflating their own totals.
• Alpha. The gateway runs in one Railway container, and a second instance is what makes it durable, not the disk.