> ## 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.

# How payouts settle

> Fund payouts from a pre-funded Bitnob balance or per transaction on the fly. The choice sets how much float you hold and how much work each payout takes.

Bitnob funds payouts two ways. The difference is whether you hold a balance in advance or pay for each payout as you create it.

| Model | How it funds | Suits |
| - | - | - |
| Wallet-funded | Deducted from a balance you top up in advance. | High volume, and teams that already manage float. |
| On the fly | Each payout is funded individually by paying a generated address or invoice. | Lower volume, and teams that would rather not hold idle balances. |

Both models reach every supported country and channel. Both can run side by side in the same account.

## Wallet-funded

You top up your Bitnob balance with bitcoin, USDT, USDC, or naira (NGN). Each payout debits that balance.

```mermaid theme={null}
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E6F7F2','primaryTextColor':'#004233','primaryBorderColor':'#00A57F','lineColor':'#00A57F','secondaryColor':'#CCEEE5','tertiaryColor':'#F2FCF9','fontFamily':'inherit'}}}%%
flowchart TD
    A[Top up your Bitnob balance] --> B[Create quote]
    B --> C[Initialize payout<br/>with beneficiary]
    C --> D[Finalize payout<br/>balance debited]
    D --> E[Bitnob dispatches to the local rail]
    E --> F[payouts.withdrawal.success]
```

1. Top up the balance. Check it with [List balances](https://www.bitnob.dev/api-reference/balances/list-balances.md).
2. Create a quote, initialize with the beneficiary, then finalize. The amount is debited at finalize.
3. Bitnob validates compliance and liquidity, then dispatches to the rail.

Payouts execute as soon as validation passes, so there is no funding wait. Finalize before `expires_at`, because an expired quote is refused. The cost is that you carry float, and a payout fails if the balance is short.

## On the fly

You hold no balance. Each payout generates its own payment address or invoice, which you pay before the payout settles.

```mermaid theme={null}
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E6F7F2','primaryTextColor':'#004233','primaryBorderColor':'#00A57F','lineColor':'#00A57F','secondaryColor':'#CCEEE5','tertiaryColor':'#F2FCF9','fontFamily':'inherit'}}}%%
flowchart TD
    A[Create quote] --> B[Initialize payout]
    B --> C[Bitnob returns a payment<br/>address or invoice]
    C --> D[You pay it before expiry]
    D --> E[Bitnob confirms funding]
    E --> F[Bitnob dispatches to the local rail]
    F --> G[payouts.withdrawal.success]
    C -.->|nothing paid in time| H[payouts.withdrawal.expired]
```

1. Call [Create quote](https://www.bitnob.dev/api-reference/payouts/create-quote.md). You get a quote ID, the amount to fund, and an expiry timestamp.
2. Call [Initialize payout](https://www.bitnob.dev/api-reference/payouts/initialize-payout.md) with the quote ID and beneficiary details. Bitnob returns a Bitcoin address, Lightning invoice, or stablecoin deposit address, depending on the `from_asset` and `chain` on your quote.
3. Pay it before the quote expires.
4. Bitnob confirms receipt, then dispatches the fiat payout.
5. `payouts.withdrawal.success`, `payouts.withdrawal.expired`, or `payouts.withdrawal.failed` tells you the outcome.

No float, and reconciliation is one payment per payout. The cost is that every payout has a funding deadline you have to meet.

### Funding sources

| Source | Notes |
| - | - |
| Bitcoin (BTC) | Send the full `deposit_amount` on-chain, or pay the invoice over Lightning. |
| USDT | Send the full `deposit_amount` on a supported chain. |
| USDC | Send the full `deposit_amount` on a supported chain. |

`deposit_amount` is returned by initialize. It is the quoted amount plus fees.

### Things that will bite you

| Case | Behavior |
| - | - |
| Quote expiry | Every quote carries an `expires_at` timestamp, and the window is short, minutes rather than hours. After expiry, request a new quote at the current rate. |
| Underpayment | A deposit short of the required amount is refused, except for a shortfall of up to 0.0001 on stablecoins. Bitcoin has no tolerance. The payout does not process and later expires. The funds stay in your Bitnob balance. |
| Overpayment | The excess is credited to your Bitnob balance. |
| Timeout | If nothing arrives before expiry, the payout is invalidated and `payouts.withdrawal.expired` fires. |

## Choosing

Pick wallet-funded if payout volume is steady enough that holding float costs less than the operational overhead of per-payout funding, or if you cannot tolerate a funding step between the user's request and settlement.

Pick on the fly if volume is low or spiky, if you are still in early integration, or if idle balance is the thing you are trying to avoid.

The models are not exclusive. A common pattern is wallet-funded for recurring payroll and on the fly for one-off disbursements.


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