LNURL & Lightning Addresses
Bitnob supports LNURL and Lightning addresses to make Lightning Network usage more user-friendly. By integrating these flows, you can issue LNURL links for customers, enable them to receive or withdraw sats easily, and let them pay or be paid with email-style addresses (like alice@company.com).
What is LNURL?
LNURL is a set of open protocols that layer on top of Bitcoin’s Lightning Network. They aim to simplify workflows like receiving and paying with Lightning. LNURL can operate in two major directions:
LNURL-Pay: Customer pays a static link that auto-fetches the invoice.
LNURL-Withdraw: Customer scans a link to claim funds from a service.
Instead of manually generating an invoice for each transaction, LNURL allows a user’s wallet to request one on the fly. This makes recurring or unpredictable payments simpler because the user only has to scan a single QR or link once.
Common LNURL Use Cases
Tipping: A content creator shares an LNURL to receive tips from fans instantly.
Withdraw: A user can withdraw earnings from a platform by scanning or clicking an LNURL that spawns an invoice behind the scenes.
Static Donations: Similar to tipping, but used for ongoing donation flows.
Lightning Addresses
Lightning addresses provide an even simpler approach: users have an “email-like” identifier (e.g., joe@company.com). When someone wants to send them sats, they type or paste that address into a Lightning wallet that supports LNURL behind the scenes, automatically retrieving an invoice.
Receive: The payer’s wallet queries joe@company.com, obtains the invoice, and completes the payment.
Send: Similarly, you can pay another user’s Lightning address by letting your system generate the appropriate LNURL flow under the hood.
Why Lightning Addresses?
Familiar experience: Email or username style format.
Great for real-time micropayments or user handles.
No manual copying of BOLT11 invoice strings.
LNURL + Bitnob Integration
With Bitnob, you can:
Issue LNURLs to customers (for receiving or withdrawal flows).
Issue or manage Lightning addresses for each user.
Use the same underlying Lightning accounts you already have in Bitnob.
Listen for LNURL or address-based payments via webhooks.
LNURL Setup Flows
LNURL-Pay
User sees a static QR or link (the LNURL).
Their wallet decodes the LNURL, fetches the invoice, and pays.
Payment arrives in the user’s custodial or non-custodial wallet, and Bitnob sends a lightning.payment.success webhook.
LNURL-Withdraw
Your app shows a user an LNURL code that references your “custody.”
The user’s wallet scans it, and Bitnob receives a request to provide an invoice.
Payment flows from your side (e.g., a payout) to the user’s LN wallet.
Lightning Address Setup
You assign an address to each user (e.g., username@yourdomain.com).
This domain or subdomain is LNURL-enabled with the help of Bitnob’s API or your own LNURL server.
When someone pays username@yourdomain.com, Bitnob automatically generates an invoice and forwards the payment to that user’s wallet.
Creating LNURLs and Lightning Addresses via API
Register your domain or subdomain for LNURL with Bitnob.
Issue LNURL (Pay or Withdraw) by calling endpoints that create an LNURL link plus any constraints (amount range, comment?).
Lightning Address: If you prefer address-based flows, pass user information to Bitnob’s API to provision name@yourdomain.com. You can also implement your own LNURL server but use Bitnob’s underlying Node.
Key Fields to Note
| FIELD | DEFINITION |
|---|---|
| Callback URLs: | LNURL relies on endpoints that return invoice data upon request. |
| Min/Max Sats: | LNURL-Pay can define ranges. |
| Expiry: | LNURL or invoice expires after a certain time for security. |
| Reference IDs: | For each LNURL or lightning address creation, store references to track user identity and handle webhooks properly. |
Handling Payment Notifications
Whenever a LNURL-based or Lightning address-based payment arrives:
Webhook: You receive an event like lightning.payment.success from Bitnob, containing the paid invoice details.
Idempotency: As always, mark the payment as processed in your DB using a unique reference.
Optional Extra Steps: If the LNURL was for a withdrawal, you can automatically finalize the user’s request. If it was a LNURL pay link, you can credit them once confirmed.
Security and Best Practices
Use unique addresses/LNURLs: Assign a new address or LNURL per user to keep transactions separate.
Validate domain ownership: If you run your own LNURL domain.
Set Sane Limits: LNURL withdraw flows can specify maximum amounts to avoid large accidental payouts.
Track usage: Track each LNURL’s usage so a user can’t keep re-withdrawing if your logic only expects one usage.
Handle Rate Limits: LNURL-compatible wallets might re-poll your callback. Include some caching or a short TTL.
Edge Cases
User scans LNURL but never completes: Their wallet might time out or show an error. LNURL sees no invoice request, so no funds move.
Underpay: LNURL flows typically define an exact invoice. Underpayment is less common unless your system supports flexible amounts.
Lightning Address DNS issues: If your domain is offline or misconfigured, payers can’t retrieve an invoice. Provide fallback (like a direct LNURL link).
FAQ
Do I need a separate Lightning node to issue LNURL?
Can LNURL/Lightning addresses be used on mobile?
What about LNURL or Lightning addresses for stablecoins?
With LNURL and Lightning addresses, you can drastically improve your user’s payment experience—no more copying long BOLT11 invoices or manual invoice generation. Everything happens dynamically, behind easy-to-share links or email-style addresses.
