---

name: lightning-address description: | Lightning Address (LUD-16): email-style identifier resolving to LNURL-pay endpoint. user@domain.com → /.well-known/lnurlp/user. Also covers BIP 353 DNS payment instructions (₿user@domain, DNSSEC TXT record) and bLIP-32 onion-message DNS resolution. USE WHEN: building/registering Lightning Addresses or BIP 353 names, designing resolver / payer wallet logic. allowed-tools: Read, Grep, Glob

Lightning Address

A Lightning Address looks like an email: user@domain.com. It's a human-friendly identifier that resolves to a LNURL-pay endpoint.

Spec: LUD-16 in github.com/lnurl/luds.

Resolution

input: user@domain.com

GET https://domain.com/.well-known/lnurlp/user
  Accept: application/json

→ same JSON as LNURL-pay (LUD-06):
  {
    "tag": "payRequest",
    "minSendable": 1000,
    "maxSendable": 100000000,
    "metadata": "[[\"text/plain\",\"Pay user@domain.com\"]]",
    "callback": "https://domain.com/lnurl/pay/user/callback"
  }

From there, standard LNURL-pay flow.

Server implementation

A simple Lightning Address server:

1. Web server with /.well-known/lnurlp/<user> endpoint per user.
2. Backend connects to LN node (LND, CLN, LDK, phoenixd).
3. On <callback>?amount=..., generate BOLT11 invoice, return JSON.
4. Forward incoming Lightning payments to user's account.

Custodial: server holds keys. Non-custodial: server forwards via LSP / NWC to user-controlled wallet.

Provider examples

• getalby.com — custodial.
• Wallet of Satoshi — custodial.
• Phoenix — non-custodial via custom resolver.
• LNbits — self-hostable.
• BTCPay Server — self-hostable.
• Zaprite — service for businesses.
• bitcoin-vn-net — open-source self-host.

Privacy

• Same as email: server sees who pays whom.
• No public-key leak (LNURL handles that).
• Receiver privacy depends on whether final hop is custodial.

BIP 353 DNS payment instructions (the non-HTTP alternative)

LUD-16 is not the only human-readable identifier. BIP 353 "DNS Payment Instructions" (Matt Corallo, Bastien Teinturier) puts a BIP 21 URI — normally an lno= BOLT12 offer — in a DNSSEC-signed TXT record. Same user@domain shape, displayed with a ₿ prefix, no web server in the path. Status Complete in the BIPs repo as of September 2026 (Draft → Proposed September 2025, Proposed → Complete January 2026 under the revised BIP process).

Spec: bip-0353.mediawiki in github.com/bitcoin/bips; bLIP-32 and bLIP-42 in github.com/lightning/blips.

₿<user>@<domain>  →  <user>.user._bitcoin-payment.<domain>.  IN TXT

matt.user._bitcoin-payment.mattcorallo.com. 1800 IN TXT "bitcoin:?lno=lno1qsgr30k..."

Rules that bite:

• Exactly one bitcoin: TXT RR at that label. Concatenate the RR's <character-string>s in RDATA order with no separator; never across RRs. Two matching RRs = invalid, refuse the instructions.
• Every record in the chain MUST be DNSSEC-signed (CNAME/DNAME indirection is allowed if each hop is signed). Clients MUST validate to the DNS root themselves — trusting a resolver's AD bit is not conformant — and MUST NOT accept SHA-1 or <1024-bit RSA signatures.
• MUST NOT cache longer than the lowest TTL in the DNSSEC chain. If the URI carries a BOLT12 offer, the TTL must expire before the offer does.
• The ₿ is display only; it is never part of the DNS label. Wallets copying the name include the ₿, but SHOULD copy the underlying URI.
• Wallets MUST prefer an explicit address or BIP 21 URI when one is already available; DNS resolution is for the human-readable form.
• On-chain addresses in the URI path SHOULD be rotated after each confirmed spend, or omitted entirely (leave the path empty).
• PSBT_OUT_DNSSEC_PROOF = 0x35 (per-output, PSBT v0 and v2) carries a 1-byte-length-prefixed name plus an RFC 9102 AuthenticationChain, so a hardware wallet can verify ₿user@domain instead of an opaque script.

bLIP-32 onion-message resolution

A clearnet DNS lookup still signals to the network that you are about to pay someone. bLIP-32 "Onion Message DNS Resolution" (Active) moves the lookup onto Lightning: dnssec_query (65536), dnssec_proof (65538), dnssec_error (65550) onion messages, with resolver nodes advertising the dns_resolver feature bit 258/259 (bLIP-2). The sender validates the returned RFC 9102 proof itself, so the resolver is untrusted.

bLIP-42 "Bolt 12 Contacts" (Active) layers on top: attach contact info to payments made to a stored offer, so the payee can recognize a known contact and pay back without further interaction.

Implementations (as of September 2026)

• LDK — lightning-dns-resolver crate implements bLIP-32 resolution on top of the dnssec-prover crate.
• Phoenix / phoenixd — resolve <user>.user._bitcoin-payment.<domain> TXT records to a BOLT12 offer. phoenixd's PayDnsAddress queries a DNS-over-HTTPS resolver and checks the response AD flag rather than validating the chain locally — weaker than BIP 353 mandates, a common shortcut in mobile clients.

Compared to BOLT12 / BIP 353

Aspect	Lightning Address	BOLT12 Offer	BIP 353 name
Human-friendly	yes	partial (longer string)	yes (₿user@domain)
Self-custodial possible	depends on server	yes natively	yes (you own the TXT record)
Spec-level	LUD-16 (LNURL)	BOLT12	BIP 353 (+ bLIP-32)
Universal wallet support	yes (most)	partial (CLN, LDK best)	partial (LDK, Phoenix/phoenixd as of Sept 2026)
Privacy from server	no (server sees)	better (blinded paths)	no payee round-trip; DNS leak unless bLIP-32
HTTP dependency	yes	no (onion messages)	no (DNS; DoH in practice)
Trust anchor	TLS CA + server	none (offer is signed)	DNSSEC root

DNS / hosting

Most users get a Lightning Address via a service. Self-host:

• Buy domain.
• Run phoenixd or LNbits etc.
• Configure web server to serve /.well-known/lnurlp/<user>.

Self-host a BIP 353 name from the same domain (no web server needed):

• The zone must be DNSSEC-signed end to end — registrar-published DS record at the parent, not just a signed zone file.
• Publish <user>.user._bitcoin-payment.<domain> TXT = bitcoin:?lno=<offer>; leave the URI path empty unless you accept the on-chain address-rotation rules above.
• Keep the TTL below the offer's expiry, and low if you rotate.

Common bugs

• Failing to handle min/maxSendable boundary correctly → wallet rejects.
• Description_hash mismatch (forgot to update when changing metadata).
• HTTP instead of HTTPS — wallets reject.
• Caching /.well-known/lnurlp/<user> aggressively → stale callback URLs after server restart.
• BIP 353: building the label as <user>._bitcoin-payment.<domain>. The literal user component stays — <user>.user._bitcoin-payment.<domain>.
• BIP 353: publishing the TXT record in an unsigned zone. Without a DS record at the parent, conformant wallets see no valid instructions.

See also

• lnurl/SKILL.md
• bolt12/SKILL.md
• ../../infrastructure/btcpay/SKILL.md