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

# Confirmations and webhook events

> Confirmation thresholds for on-chain BTC, the difference Lightning makes, and the webhook events that carry every bitcoin outcome.

A single reference for when a bitcoin payment is safe to credit, and which events tell you about it. For the flow that produces them, see [Issue addresses and Lightning invoices](https://www.bitnob.dev/docs/bitcoin/issuing-bitcoin-addresses-and-lightning-invoices.md).

## Confirmation thresholds

| Rail | `deposit.success` arrives | Credit the user |
| - | - | - |
| On-chain BTC | After 1 confirmation under 1 BTC, 2 at 1 BTC or more | On `deposit.success` |
| Lightning | On invoice payment | On `deposit.success` |

Bitnob waits for the confirmations above, then sends `deposit.success`. Credit the user when it arrives, and treat earlier signals on a block explorer as pending.

Lightning payments settle off-chain and require no block confirmations, so an invoice marked paid is final. That is what makes Lightning suited to tipping and micropayments, where waiting for blocks is not acceptable.

To check a deposit later, use [Get transaction by id or reference](https://www.bitnob.dev/api-reference/transactions/get-transaction-by-id.md). It returns the transaction state, not a confirmation count.

## Webhook events

| Event | Fires when | Act on it |
| - | - | - |
| `deposit.success` | An inbound payment is confirmed. | Credit the user. |
| `transfer.success` | An outbound send completed. | Mark the withdrawal settled. |
| `transfer.failed` | An outbound send failed. | Release the hold and surface the reason. |

Deliveries are HTTPS POSTs signed with the `x-bitnob-signature` header. Verify the signature on every event before acting on it, and make handlers idempotent, de-duplicating on `event_id`. The full verification walkthrough and source IP list are on the [Addresses webhooks reference](https://www.bitnob.dev/docs/stablecoins/address-webhook-events.md).

### `deposit.success` payload fields

| Field | Description |
| - | - |
| `event` | The event name. Branch on this first. |
| `event_id` | Unique per delivery. Use it to de-duplicate retries. |
| `data.address` | The address that received the payment. On-chain only. |
| `data.amount` | Amount received, in satoshis for BTC. |
| `data.chain` | The chain, for example `bitcoin`. |
| `data.currency` | The asset, for example `BTC`. |
| `data.fee` | Fee attributed to the transaction. |
| `data.hash` | The on-chain transaction hash. On-chain only. |
| `data.invoice` | The paid BOLT11 invoice. Lightning only. |
| `data.reference` | The reference for this receipt. |
| `data.transaction_id` | Bitnob's transaction identifier, for lookups. |
| `data.timestamp` | When the deposit was observed. |

## Address reuse

Generate a new address for each receipt. Bitnob still fires `deposit.success` for a payment to a previously used address, so reuse does not break delivery, but it lets third parties link payments together through chain analysis and makes reconciliation ambiguous when several payments share one address.

See [Address and privacy practices](https://www.bitnob.dev/learn/playbooks/bitcoin/address-and-privacy-best-practices.md) for the fuller treatment.


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