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 stopped payments on custodial accounts on 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 are the ones I measured, 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, none of those domains publishes verify at all. ZEUS Pay and ecash.love do serve verify but release no preimage, which amounts to the same thing. 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 { invoiceFrom, msat, relayedVerifyUrl, ThunderBridge } from "thunder-bridge";

const CALLBACK_SECRET = process.env.CALLBACK_SECRET as string;
const payWithinSecs = 3600;

const gateway = new ThunderBridge("https://public.thunder-bridge.agora.gripe", {
  secret: CALLBACK_SECRET,
});

export async function POST(): Promise<Response> {
  const invoice = await invoiceFrom(["you@blink.sv"], msat(21_000));

  const watched = await gateway.watch({
    paymentHash: invoice.paymentHash,
    verifyUrl: await relayedVerifyUrl(
      "https://your.site/api/verify",
      { url: invoice.verifyUrl, hash: invoice.paymentHash },
      CALLBACK_SECRET,
    ),
    expiresAt: Math.min(invoice.expiresAt, Math.floor(Date.now() / 1000) + payWithinSecs),
  });

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

import { ThunderBridge } from "thunder-bridge";

const gateway = new ThunderBridge("https://public.thunder-bridge.agora.gripe");

const serveVerify = gateway.serve.lightningVerify({
  secret: process.env.CALLBACK_SECRET as string,
});

export const GET = serveVerify;
export const POST = serveVerify;

CALLBACK_SECRET is one random string you generate with openssl rand -hex 16 and set on both routes. It seals the wallet's URL into your own, so the gateway never learns the host, and the same route unseals it again. It has to answer both methods: GET is the gateway asking whether it is paid, POST is the one-off challenge it uses to check the route is yours before it takes the payment on. payWithinSecs is your call on how long the invoice stays payable, the gateway itself watches for up to 30 days.

In the browser: the QR and the wait

import { ThunderBridge } from "thunder-bridge";
import { invoiceToSvg } from "thunder-bridge/qr";

const gateway = new ThunderBridge("https://public.thunder-bridge.agora.gripe");

export async function payInto(target: HTMLElement): Promise<boolean> {
  const minted = await fetch("/api/invoice", { method: "POST" });
  const { id, paymentHash, bolt11 } = (await minted.json()) as {
    id: string;
    paymentHash: string;
    bolt11: string;
  };

  target.innerHTML = invoiceToSvg(bolt11);

  const settled = await gateway.settled({ id, paymentHash });

  return settled.status === "paid";
}

The browser gets no secret, only an id, a payment hash and a bolt11. It draws the QR and waits on a socket. settled returns paid only once the preimage hashes to that payment hash, otherwise it throws GatewayCheatError.

Webhook

import { ThunderBridge } from "thunder-bridge";

declare function fulfil(paymentId: string, preimage: string): Promise<void>;

const gateway = new ThunderBridge("https://public.thunder-bridge.agora.gripe");

export const POST = gateway.serve.webhook({
  onSettled: async (settlement) => {
    await fulfil(settlement.id, settlement.preimage);
  },
});

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. fulfil is your own function, the declaration only marks where the package ends and you begin.

• The recipient must speak LUD-21. Which domains do and which do not is up above, under picking a wallet.
• No privacy layer. The payer sees your real invoice and your wallet provider's 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 as a single replica on my own cluster, and a second instance is what makes it durable, not the disk. The one behind the demo above keeps its ledger in memory, so a restart forgets everything.