Tutorial: Send Bitcoin (On-chain or Lightning) from a Bitnob Wallet
This tutorial teaches you how to send Bitcoin from your Bitnob account to any valid Bitcoin destination — either a traditional on-chain address or a Lightning invoice. Both options use the same BTC wallet within Bitnob, meaning you don't have to manage separate balances or initiate transfers between wallets to choose your preferred payment method.
This flow is ideal if you're building:
A Bitcoin withdrawal feature for your app
A payout system to Bitcoin wallets
Merchant payment rails that support both traditional and Lightning destinations
Handle all messaging via webhooks
Prerequisites
A verified Bitnob account
A valid API key
BTC in your consolidated Bitnob wallet (funded via on-chain or Lightning)
A destination address (BTC address or Lightning invoice)
Bitnob creates a BTC wallet for you by default. You do not need to create one manually.
Key Concepts
Bitcoin can be sent in two ways:
On-chain (standard Bitcoin address)
Lightning (invoice-based)
In both cases, funds are pulled from the same BTC wallet in your Bitnob account.
Step 1: Choose the Payment Method and Collect Input
From your user interface or backend flow, collect:
The amount to send (in satoshis)
The destination: either a Bitcoin address or a Lightning invoice
A reference ID (for internal tracking)
You also need to specify which network you are sending to:
Use "bitcoin" for on-chain
Use "lightning" for Lightning invoices
Step 2: Send Bitcoin On-Chain
To send to a standard BTC address (on-chain), use the following request:
Example Request
Explanation of Fields
| FIELD | DEFINITION |
|---|---|
amount | In satoshis, must match the invoice amount. |
invoice | The full Lightning invoice string provided by the recipient. |
network | 'Lightning' identifies this as a Lightning payment. |
reference | Optional ID for internal logging. |
Step 3: Send Bitcoin via Lightning
To send Bitcoin instantly using Lightning, use the same endpoint but pass a Lightning invoice instead of a BTC address.
Example Request
Explanation of Fields
| FIELD | DEFINITION |
|---|---|
amount | In satoshis, must match the invoice amount. |
invoice | The full Lightning invoice string provided by the recipient. |
network | "lightning" identifies this as a Lightning payment. |
reference | Optional ID for internal logging. |
Handling Success and Errors
On success, Bitnob will return:
A status: success
Use "lightning" for Lightning invoices
The updated wallet balance
On success, Bitnob will return:
Insufficient funds: ensure the wallet has enough BTC to cover both the amount and network fee
Invalid address or invoice: validate input formats before calling the API
Lightning invoice expired or already paid: Lightning invoices are time-bound and must be fresh
Best Practices
Always validate that the address or invoice is well-formed before calling the API.
Use a QR code scanner or parsing library for Lightning to ensure the invoice is valid.
For on-chain payments, use an address validator to avoid common formatting issues.
Consider confirming wallet balance before initiating the send.
You should also track each transaction’s reference or returned transaction ID in your internal database for reconciliation.
If you're sending user funds, always log the recipient and destination for audit purposes.
Summary
Bitnob allows you to send Bitcoin using a single, consolidated BTC wallet. You can route payments to either the traditional blockchain or the Lightning Network depending on speed, cost, and user preference. This unified approach makes integration easier while keeping user experience flexible.
Whether you’re sending payouts, enabling peer-to-peer transfers, or integrating Bitcoin into your checkout experience, this flow gives you all the control and reliability you need to support modern Bitcoin payment rails.
