lightning-lnurlLNURL: bech32-encoded HTTP URL fetched by wallet to enable payment flows. LUDs (LNURL specs): LUD-01 (encoding), LUD-04 (auth), LUD-06 (pay), LUD-09 (success action), LUD-12 (comment), LUD-16 (lightning address), LUD-21 (verify). USE WHEN: implementing LNURL servers/clients, building Lightning Address resolver, designing pay/withdraw/auth flows.
Independent GitHub snapshot · Automated classification · Original documentation governs
LNURL is a set of protocols for using Lightning via HTTP-mediated flows. Wallet scans a bech32-encoded URL, fetches a JSON descriptor, then follows the workflow indicated.
Specs (LUDs) live at github.com/lnurl/luds.
LNURL = bech32(hrp="lnurl", data=URL bytes)
Example URL https://example.com/pay/123 →
LNURL1DP68GURN8GHJ7MR9VAJKUEPWD3HXY6T5WVHXXMMD9AKXUATJDSKHQCT5
Wallets scan QR with LNURL... prefix or lightning:LNURL... URI.
Login via Lightning. Server issues challenge, wallet signs with derived key per server, server verifies.
challenge_response.derive_lnurl_key(seed, domain) →
same wallet's "identity" with same domain across sessions.Use case: account login / OAuth-like.
Wallet fetches metadata:
{
"tag": "payRequest",
"minSendable": 1000,
"maxSendable": 100000000,
"metadata": "[[\"text/plain\",\"Coffee\"]]",
"callback": "https://example.com/lnurl/pay/123/callback",
"commentAllowed": 200
}
User chooses amount, optional comment, then GETs callback:
GET /callback?amount=5000&comment=Thanks
→ { "pr": "lnbc50u1...", "successAction": {...} }
Wallet pays the BOLT11 invoice. After success, optionally show
successAction (URL, message, AES-encrypted message).
After payment success:
message: text to show user.url: redirect (e.g., download link).aes: encrypted blob decrypted by preimage.If commentAllowed > 0, payer can attach a free-form text comment
to the payment.
user@domain.com — see lightning-address/SKILL.md.
Resolves to https://domain.com/.well-known/lnurlp/user, returns
LNURL-pay metadata.
Allow client to verify payment status post-pay:
GET /callback/verify/<payment_hash>
→ { "settled": true, "preimage": "..." }
Server pre-funds a withdrawal. User scans, wallet calls callback, server pays the wallet's invoice. Used for faucets, refunds, voucher redemption.
LNURL-pay binds the metadata to the invoice via:
description_hash = SHA256(metadata_json_string)
The BOLT11 invoice has tag h (description_hash) instead of d
(description). Wallet verifies that the displayed metadata matches.
1. User scans QR → wallet decodes → URL = https://merchant.com/pay/abc
2. GET https://merchant.com/pay/abc
→ { tag: "payRequest", minSendable, maxSendable, metadata, callback, ... }
3. Wallet shows description (from metadata), user picks amount.
4. GET <callback>?amount=<msat>
→ { pr: "lnbc...", successAction }
5. Wallet decodes pr, verifies description_hash == SHA256(metadata_json).
6. Wallet pays the invoice.
7. After success, wallet shows successAction.
description_hash. Otherwise server could swap
metadata mid-flow.successAction.url should be on the same domain as the callback
(mitigate phishing).