Issuing Bitcoin Addresses & Lightning Invoices
Your application can issue both on-chain Bitcoin addresses and Lightning invoices to help customers receive BTC quickly and reliably. In this subsection, you’ll learn how these addresses are generated, how Bitnob notifies you of incoming payments, and the recommended way to handle confirmations and user balances.
On-Chain Addresses
What They Are
An on-chain address is a standard Bitcoin address on the main blockchain. When a user wants to receive BTC, you can generate a new address via the Bitnob API and display it to the user. Once the user sends BTC to that address, Bitnob listens for the transaction and fires a webhook event (btc.onchain.received.success) once the transaction is detected.
Generating Addresses
When creating an address, you can specify:
| FIELD | DEFINITION |
|---|---|
| label | A string to identify the address in your logs. |
| Optional if you want to tie it to a user’s account. | |
| address type | (taproot, segwit), legacy. If you don’t specify, Bitnob defaults to segwit (bech32). |
Avoiding Address Reuse
For privacy and good security hygiene, we strongly recommend generating a new address whenever you or your users want to receive BTC. This prevents multiple payments from appearing on the same address, making it harder for third parties to chain-analyze your transactions.
If payments still arrive on an old address, Bitnob will still fire the incoming BTC webhook. However, re-using addresses can create confusion and undermine user privacy.
Webhook Event: btc.onchain.received.success
When BTC arrives, Bitnob sends a webhook with at least one confirmation. You’ll receive an event payload similar to:
This helps guard against potential chain reorganizations. You can also re-query the transaction endpoint to see the current number of confirmations.
Lightning Invoices
Why Lightning
Lightning invoices allow near-instant BTC payments on top of Bitcoin’s second-layer protocol. They’re ideal for tipping, micropayments, or any scenario where you want quick finality without waiting for on-chain confirmations.
Creating a Lightning Invoice
Similar to on-chain addresses, you generate a Lightning invoice via the Bitnob API. The invoice is a BOLT11 string that starts with ln. This is what you display or provide to the payer.
Displaying the Invoice
We recommend two user-interface options:
QR Code: Let users scan the invoice quickly with their mobile wallets.
Copy Invoice: Provide an easy “Copy” button so they can paste it into a Lightning wallet.
Receiving Payment
Once the payer sends sats to this invoice, Bitnob checks the Lightning network. When the payment is confirmed, you’ll receive a webhook notification (e.g., lightning.payment.success) along with relevant info (like amount, invoice, label ).
LNURL and Lightning Addresses
Beyond basic BOLT11 invoices, Bitnob also supports:
LNURL: A more user-friendly way for payers to fetch an invoice from you.
Lightning Addresses: Email-style addresses (like john@lightning.example) that automatically generate an invoice behind the scenes.
These methods simplify the user experience, letting them pay to a static handle rather than copying a BOLT11 invoice.
Safety and Best Practices
Unique Addresses/Invoices:
Issue a fresh address or invoice each time you expect new funds. This ensures better privacy and easier bookkeeping.
Labeling and Email:
Attach a label or email to every address/invoice you create. This helps you track which user or scenario the funds are meant for.
Confirmation Threshold:
For on-chain BTC, wait 3 confirmations or more before crediting user balances. Lightning payments are effectively instant once the invoice is paid, so no block confirmations are required.
Webhook Handling:
Ensure your webhook endpoint is idempotent. If Bitnob retries or you receive the same event, don’t double-credit the user. Store a reference to track which transaction has already been processed.
Address Reuse:
It’s still possible to receive BTC on older addresses, and we’ll notify you if that happens. However, generating new addresses for each incoming transaction is strongly advised.
Taproot and SegWit:
Bitnob supports Taproot addresses if you choose addressType: 'taproot'. This can yield lower fees and potentially improved privacy on the network. Use it if your customers want the latest Bitcoin features.
Example Flows
On-Chain Payment to a SegWit Address
Your app requests a new address from Bitnob, specifying "segwit".
You display that address (bc1q...) to the customer.
Customer sends BTC from an external wallet.
Bitnob detects the payment and sends a btc.onchain.received.success webhook with confirmations: 1.
Your system checks if there are at least 3 confirmations before crediting the user.
Lightning Payment for Tipping
User wants to receive a 15,000 sat tip quickly.
You create a Lightning invoice for 15,000 sats and display a QR code.
The payer scans and sends with a Lightning wallet.
Bitnob triggers lightning.payment.success webhook once the payment is settled.
You instantly credit the user in your app.
Issuing on-chain addresses and Lightning invoices through Bitnob allows your customers to receive BTC in their preferred way.
With each invoice or address labeled properly, you can easily correlate incoming payments to the correct user. Always enforce good security hygiene (avoid address reuse, wait for confirmations on on-chain, handle Lightning webhooks idempotently) to maintain trust and reliability in your service.
