Self-hosted Lightning payment and identity server with next-generation BOLT12 support.
- ⚡ BOLT12 Offers (create & pay)
- 🔗 Lightning Address (BIP353)
- 🔄 LNURL fallback
- 🧾 BOLT11 fallback invoices
- 🧠 Nostr identity (NIP-05 + Zaps)
- 📱 QR-based payments
- ☁️ Optional Cloudflare DNS automation
- 🌐 Automatic Cloudflare DNS provisioning for BIP353 and LNURL
- 🟢 Available in the official Start9 Community Registry
BOLT12 Pay requires a LND Lightning node with at least one active channel, better a well connected node with multiple channels opened.
BOLT12 Pay works best when you already own a domain name.
Recommended:
- a personal domain (for example
yourdomain.com) - DNS hosted at Cloudflare
- Cloudflare API Token (optional, for automatic DNS management)
Without a domain you can still:
- create, pay and receive BOLT12 Offers (without Bip 353)
- test BOLT12 functionality locally
However:
- BIP353 Lightning Addresses require a domain
- LNURL Addresses require a domain
- Public payment pages require a public domain
BOLT12 Pay is officially available on:
- Umbrel App Store
- StartOS Community Registry / Marketplace
BOLT12 Pay automatically detects native Onion Messaging support.
No manual LND configuration is required.
BOLT12 requires onion messaging support in LND.
This must be enabled manually.
Open Umbrel → Files and navigate to:
Apps → lightning → data → lnd → lnd.conf
[protocol]
protocol.custom-message=513
protocol.custom-nodeann=39
protocol.custom-init=39
From the official App Store, search for BOLT12 Pay.
Repository:
https://github.com/getumbrel/umbrel-apps/tree/master/bolt12-pay
yourdomain.com) as the Cloudflare Zone Domain, not a subdomain.
When exposing BOLT12 Pay on Umbrel through Cloudflare Tunnel, route your public domain to:
http://umbrel.local:8367
In Cloudflare Tunnel HTTP settings, set:
HTTP Host Header: umbrel.local
This helps Umbrel route authenticated app access correctly.
Important limitation:
Umbrel authentication may redirect authenticated app routes back to:
http://umbrel.local:8367
Public payment/discovery endpoints remain usable over the public HTTPS domain, but browser features that require a secure HTTPS context, such as QR camera scanning or PWA installation, may only work reliably when the page remains on the public HTTPS origin.
For best public payment functionality, use the public domain for LNURL, BIP353 and public payment endpoints.
If you previously used BOLT12 Pay with LND v0.20.1 beta, you likely added custom protocol settings to your lnd.conf:
[protocol] protocol.custom-message=513 protocol.custom-nodeann=39 protocol.custom-init=39
Before upgrading your Lightning node to LND v0.21.x, remove the entire custom protocol section from your lnd.conf.
In your LND configuration file (Go to Files: Apps → lightning → data → lnd → lnd.conf), remove
[protocol] protocol.custom-message=513 protocol.custom-nodeann=39 protocol.custom-init=39
Save and restart LND, then you may savely update the Lightning Node app on umbrel.
Native onion messaging support is now built directly into LND v0.21 and these legacy settings are no longer required.
Once the custom protocol entries are removed, LND will work again.
BOLT12 Pay is available in the official Start9 Community Registry ⚡
Features:
- one-click installation
- StartOS 0.4 support
- integrated LNDK runtime
- BOLT12 Offers
- Lightning Address support
- LNURL fallback
Inside StartOS:
- Open Marketplace
- Switch to Community Registry
- Search for
BOLT12 Pay - Install 🎉
Repository:
https://github.com/Start9-Community/bolt12-pay-startos
- official StartOS LND package
- onion messaging enabled
https://github.com/Start9Labs/lnd-startos/releases
Recommended:
- Cloudflare Tunnel
- Cloudflare Access for admin protection
Public payment endpoints must remain reachable.
No manual configuration is required.
Many setup issues are caused by confusion between:
- Cloudflare Zone Domain
- BIP353 (Lightning Address) Domain
- LNURL Domain
BOLT12 Pay can serve both BIP353 and LNURL from the same domain.
For most users this is the recommended configuration:
Cloudflare Zone:
yourdomain.com
BOLT12 Address:
bolt12@yourdomain.com
LNURL Address:
sats@yourdomain.com
LNURL Base Domain:
yourdomain.com
LNURL Base URL:
https://yourdomain.com
Advantages:
- simpler setup
- cleaner Lightning addresses
- fewer DNS records
- easier Cloudflare configuration
- less maintenance
Advanced users may choose to host LNURL on a separate subdomain:
Cloudflare Zone:
yourdomain.com
BOLT12 Address:
bolt12@yourdomain.com
LNURL Address:
sats@pay.yourdomain.com
LNURL Base Domain:
pay.yourdomain.com
LNURL Base URL:
https://pay.yourdomain.com
Reasons to use a dedicated subdomain:
- separate branding
- separate infrastructure
- advanced routing setups
- compatibility testing
This setup is optional and not required.
When configuring Cloudflare automation, the Zone Domain must always be your root domain.
Correct:
yourdomain.com
Incorrect:
pay.yourdomain.com
The Cloudflare Zone is the parent domain that contains all DNS records.
Cloudflare Zone:
alex71btc.com
BOLT12 Address:
bolt12@alex71btc.com
LNURL Address:
sats@alex71btc.com
LNURL Base Domain:
alex71btc.com
LNURL Base URL:
https://alex71btc.com
❌ Cloudflare Zone = pay.yourdomain.com
✅ Cloudflare Zone = yourdomain.com
❌ LNURL Base URL = http://yourdomain.com
✅ LNURL Base URL = https://yourdomain.com
✅ Using the same domain for BIP353 and LNURL is fully supported
✅ A dedicated LNURL subdomain is optional
Admin:
/pay/pay-login
Public:
- LNURL
- payment callbacks
- public pages
- LNDK → BOLT12 Offers
- LND → Lightning backend
- LNURL / BIP353 → compatibility
- Nostr → identity + zaps
- Web UI → admin + payments
BOLT12 Pay is available in the Start9 Community Registry.
MIT