> ## Documentation Index
> Fetch the complete documentation index at: https://www.bitnob.dev/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Bitnob API requests authenticate with an `X-Auth-Client` API key header against https://api.bitnob.com.
> Always use the sandbox environment for testing. Never put live API keys in sample code.
> Money amounts are integers in the smallest unit of the currency (satoshis for BTC, cents for fiat). Never use floats.
> Every state-changing request takes a client-supplied `reference` and must be treated as idempotent on retry.
> Quotes expire. Re-quote rather than reusing a stale quote id.

# Send bitcoin on-chain or over Lightning

> Outbound BTC from a single wallet balance, on-chain or over Lightning, with the API calls in order.

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](https://www.bitnob.dev/docs/getting-started/quickstart.md).
* 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](https://www.bitnob.dev/api-reference/withdrawals/initiate-withdrawal.md) | [Send payment](https://www.bitnob.dev/api-reference/lightning/send-payment.md) |

Funds come from the same wallet either way.

**1. 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.

**2. Send on-chain**

```bash theme={null}
POST /api/withdrawals
```

```json theme={null}
{
  "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.

**3. Or send over Lightning**

```bash theme={null}
POST /api/lightning/pay
```

```json theme={null}
{
  "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. |

```json theme={null}
{
  "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.

> [!TIP]
>
> To read an invoice before paying it, for example to show the user the amount and fee, call [Decode BOLT11](https://www.bitnob.dev/api-reference/lightning/decode-bolt11.md) or [Preview payment](https://www.bitnob.dev/api-reference/lightning/preview-payment.md).

**4. 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](https://www.bitnob.dev/api-reference/transactions/get-transaction-by-id.md), and check the balance with [Get balances](https://www.bitnob.dev/api-reference/balances/list-balances.md).

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](https://www.bitnob.dev/docs/bitcoin/confirmations-and-webhook-events.md).

## Next

> [card] [Confirmations and webhook events](https://www.bitnob.dev/docs/bitcoin/confirmations-and-webhook-events.md)
>
> When a payment is safe to treat as final.

> [card] [Fees and confirmation strategy](https://www.bitnob.dev/docs/bitcoin/fee-market-and-transaction-strategies.md)
>
> Choosing a fee rate, and rescuing a stuck transaction.

> [card] [Issue addresses and invoices](https://www.bitnob.dev/docs/bitcoin/issuing-bitcoin-addresses-and-lightning-invoices.md)
>
> The inbound direction.

> [card] [Custody models](https://www.bitnob.dev/docs/bitcoin/custody-models.md)
>
> Who holds the keys, and what that changes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.