Send bitcoin on-chain or over Lightning

In this tutorial you send BTC from your Bitnob account to any valid destination: a traditional on-chain address, or a Lightning invoice. Both draw on the same BTC wallet, so you do not manage separate balances or move funds between wallets to pick a rail. This flow suits a withdrawal feature, a payout system that pays to Bitcoin wallets, or merchant rails that accept both destination types.

Prerequisites

A verified Bitnob account.
API credentials, and a working signed request. See Quickstart.
BTC in your Bitnob wallet, funded on-chain or over Lightning.
A destination: a BTC address or a BOLT11 invoice.

Bitnob creates the BTC wallet for you. You do not need to create one manually.

The two rails

	On-chain	Lightning
Settles in	Roughly 10 to 60 minutes, depending on congestion and fee rate	Seconds
Destination	A Bitcoin address	A BOLT11 invoice
Best for	Larger amounts, where a wait is acceptable	Small amounts, tipping, checkout
Endpoint	Initiate withdrawal	Send payment

Funds come from the same wallet either way.

Collect the input

From your interface or backend, gather the amount, the destination, and your own reference for tracking. The destination format decides the rail: an address means on-chain, a string beginning lnbc (lntb in sandbox) means Lightning.Validate the destination before you call the API. A malformed address is the most common cause of a failed send, and it is cheaper to catch client-side.

Send on-chain

POST /api/withdrawals

{
  "to_address": "bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4",
  "amount": "5000",
  "currency": "BTC",
  "chain": "bitcoin",
  "reference": "GNT_Ty12334z",
  "description": "Withdrawal for user 4821"
}

Field	Description
`to_address`	The recipient’s address on the specified chain.
`amount`	The amount to send, in the base unit of the currency: satoshis for BTC.
`currency`	The asset to send, for example `BTC`.
`chain`	The network to send on, for example `bitcoin`.
`reference`	Your unique reference, used for tracking and idempotency.
`description`	Optional note describing the transfer.

The response confirms the withdrawal was accepted, not that it confirmed on-chain. Wait for the transfer.success webhook before telling the user it is done.

Or send over Lightning

POST /api/lightning/pay

{
  "reference": "LT_PT25000900130010051104509",
  "request": "lnbc10n1p4q0y0gpp59lset56yg8eckd0wqu5j5jy8xsm5mjq6t256rm7h7rwxrsnuygtqdqu2pshjmt9de6zqen0wgsx7unyv4eqcqzzsxqrrsssppwuxvs8qyuvx5kl3xtd6lqttl4acj6qtf3673vqvlpr2sze39s6vm0xxq8ljfq334sfpaqweemp3h62ekneec4m887g9g0vvlwt3sq33d5k9"
}

Field	Description
`reference`	Your unique idempotency key. Prevents a duplicate payment if the request is retried.
`request`	The full BOLT11 invoice from the recipient. It already carries the destination, amount, and expiry.

{
  "success": true,
  "message": "Lightning payment sent successfully",
  "data": {
    "id": "4b89cdf8-7590-4428-84b4-a55b4767ceb4",
    "payment_hash": "2fe195d34441f38b35ee07292a488734374dc81a5aa9a1efd7f0dc61c27c2216",
    "preimage": "d2241ac699ded9078ae5bcf3c5e3a8d8bc906ab5d83cef03eb4c303a6e40c299",
    "amount_sat": "1",
    "fee_sat": "20",
    "status": "paid",
    "created_at": "2026-05-15T21:37:05Z",
    "reference": "LT_PT25000900130010051104509",
    "transaction_id": "4b89cdf8-7590-4428-84b4-a55b4767ceb4"
  }
}

Because the invoice carries the amount, you do not pass one. If the invoice is valid and the node is reachable, the payment completes and is confirmed in the response. preimage is the cryptographic proof of payment: store it.

To read an invoice before paying it, for example to show the user the amount and fee, call Decode BOLT11 or Preview payment.

Confirm the outcome

On success you get a transaction id and your reference back, and the wallet balance updates. Resolve either identifier later with Get transaction by id or reference, and check the balance with Get balances.Record the reference and the returned transaction id against the user in your own database. If you are moving user funds, log the destination too, for audit.

When it fails

Cause	What to do
Insufficient funds	The wallet must cover the amount and the network fee. Check the balance before sending.
Invalid address or invoice	Validate the format before calling the API.
Invoice expired or already paid	Lightning invoices are time-bound and single-use. Request a fresh one.

Handle all outcome messaging through webhooks rather than the synchronous response, and make the handler idempotent. See Confirmations and webhook events.

Confirmations and webhook events

When a payment is safe to treat as final.

Fees and confirmation strategy

Choosing a fee rate, and rescuing a stuck transaction.

Issue addresses and invoices

The inbound direction.

Custody models

Who holds the keys, and what that changes.

Get started

Bitcoin

Stablecoins

Trading

Payouts

Card issuing

Virtual accounts

Send bitcoin on-chain or over Lightning

Prerequisites

The two rails

When it fails

Next

Confirmations and webhook events

Fees and confirmation strategy

Issue addresses and invoices

Custody models

​Prerequisites

​The two rails

​When it fails

​Next

Confirmations and webhook events

Fees and confirmation strategy

Issue addresses and invoices

Custody models

Prerequisites

The two rails

When it fails

Next