> ## 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. # Changelog > Dated entries for API changes, new products, and documentation updates. **November 5, 2026** ## Business API: new response format We're simplifying Business API responses and error codes. The API reference shows the new format. Field and error code changes reach your integration on your cutoff date, which we'll send you by email. A smaller set of changes applies to every integration straight away, and they're listed below. **Renamed error codes** | Current | New | | - | - | | `PROVIDER_ERROR` | `PROCESSING_ERROR` | | `BVN_PROVIDER_UNAVAILABLE` | `BVN_VERIFICATION_UNAVAILABLE` | | `provider_auth_config` (reason) | `service_auth_config` | The `type` URL in these errors changes to match, and the `feature_key` for card KYC errors becomes `card_kyc_enabled`. Three internal card `failure_code` values (`retry_declined`, `V1_NEGATIVE_FROZEN`, and `SUPERSEDED_BY_LINKED_TERMINATION_CREDIT`) become `OPERATION_FAILED`. **Renamed field** On virtual account transactions, `ledger_transaction_id` is replaced by `transaction_id`, which works with [Get a transaction](https://www.bitnob.dev/api-reference/transactions/get-transaction-by-id.md). The `virtual_account.deposit.success` webhook keeps all its current fields. **Removed fields** | Endpoint | Removed | | - | - | | Payouts | `provider_settlement_id` | | Card transactions | `provider_transaction_id`, `provider_reference` | | Virtual account transactions | `provider_transaction_id` | | Conversions | `debit_ledger_tx_id`, `credit_ledger_tx_id`, `reverse_ledger_tx_id` | | LNURL withdrawals | `ledger_tx_id` | **Metadata** `metadata` stays on transactions and virtual account transactions, but internal keys are removed from it, including ledger ID keys, `account_id`, `company_id`, `hold_stage`, `source_wallet`, and `idempotency_key_basis`. All other keys stay the same. [Proxy a JSON-RPC call to a node](https://www.bitnob.dev/api-reference/nodes/proxy-a-json-rpc-call-to-a-node.md) errors will contain only `code` and `message`. Card `termination_reason` text that mentions a partner is replaced with a general message. **Applies straight away** These changes don't wait for your cutoff date: * `metadata` keys starting with `provider`, and internal staff and repair keys, are removed. * `transaction_id` is added to virtual account transactions and the `virtual_account.deposit.success` webhook. * Several messages are clearer, including `failure_reason` on payout webhooks and card transactions. Raw internal text is replaced with a safe message. * Conversion `failure_reason` only appears on failed conversions. * Internal repair notes are removed from card transaction descriptions, and a description naming a partner is removed. * The `PROVIDER_ERROR` title becomes `Processing Error`, and `extensions.provider` is removed. Don't match on message wording: use error codes and statuses instead. **November 5, 2026** ## Deprecated endpoints left the API reference Deprecated endpoints are no longer in the API reference. They still work, and their old pages redirect to the replacement where there is one. If you still call one, move to its replacement. Create a lite card and Get a payout by reference have no replacement yet. **November 1, 2026** ## Business API reference: full endpoint coverage The Business API reference now covers all 129 endpoints in the published spec, up from 69. These are newly documented: | Group | Endpoints | | - | - | | [LNURL](https://www.bitnob.dev/api-reference/lnurl/pay-a-lightning-address-or-lnurl.md): lightning addresses, domains, withdraw links, and encode, decode, resolve and pay | 17 | | Virtual cards: [card KYC status](https://www.bitnob.dev/api-reference/cards/get-card-kyc-status.md), [corporate KYB](https://www.bitnob.dev/api-reference/cards/start-corporate-kyb.md), deposit addresses, funding details, team-member cards and encryption keys | 13 | | Exchange rates: [conversions](https://www.bitnob.dev/api-reference/exchange-rates/execute-a-conversion.md) | 3 | | [Transfer to another organization](https://www.bitnob.dev/api-reference/transfers/transfer-to-another-organisation.md) | 1 | | [Proxy a JSON-RPC call to a node](https://www.bitnob.dev/api-reference/nodes/proxy-a-json-rpc-call-to-a-node.md) | 1 | | Others: delete a customer, delete a beneficiary, get a payout quote, list supported chains, simulate an invoice payment, and `POST /api/whoami` | 6 | The reference also lists 19 deprecated aliases, marked as deprecated on their pages, each pointing to the endpoint that replaces it. Three endpoints that were already documented are now deprecated: | Deprecated | Use instead | | - | - | | `POST /api/cards/lite` | No replacement yet | | `GET /api/customers/{customerId}/cards` | [List cards](https://www.bitnob.dev/api-reference/cards/list-cards.md) with `customer_id` | | `GET /api/stablecoins/supported-chains` | [List supported chains](https://www.bitnob.dev/api-reference/addresses/supported-chains.md) | Most endpoint pages have new titles. Their URLs haven't changed. **October 17, 2026** ## Enterprise reference: full endpoint coverage The Enterprise API reference now covers all 86 endpoints in the published spec, up from 42. These groups are newly documented: | Group | Endpoints | | - | - | | Policies | 15 | | Consolidation | 11 | | KYT risk profiles and categories | 6 | | Sponsored transfers | 4 | | Insights (network fee estimates) | 1 | | Users (approver candidates) | 1 | Existing groups also gained endpoints: wallet signing and sign logs, UTXOs and per-asset balances, transaction fee estimates, and webhook event types. Gas station pages moved to `/api-reference/platform/gasstations/`, and the old URLs redirect. **October 14, 2026** ## Choose the bank for virtual accounts [Create virtual account](https://www.bitnob.dev/api-reference/virtual-accounts/create-virtual-account.md) takes an optional `bank` field: `nomba` (Nombank MFB) or `globus` (Globus Bank). Leave it out and the account opens at the default bank, currently Nomba. A customer can hold accounts at both banks, or several at one bank, as long as each request uses a new `reference`. `bank_name` returns the issuing bank, and is always `Sandbox Bank` in sandbox. Any other value fails with `bank must be one of: nomba, globus`. **October 9, 2026** ## Lite cards require Card KYC Create lite card now requires approved Card KYC for the cardholder. Verify the customer with [Card KYC](https://www.bitnob.dev/api-reference/cards/card-kyc.md) first, then pass the returned `customer_id`. Three new fields are also required: `card_brand`, `swipe_count`, and `terminate_date`. Requests without approved KYC or these fields are rejected. **August 23, 2026** ## Card KYC Cardholders are verified through the new [Card KYC](https://www.bitnob.dev/api-reference/cards/card-kyc.md) endpoint before a card can be issued. Submit the customer to `POST /api/cards/kyc` first. Approval returns a `customer_id`, which you then pass to [Create card](https://www.bitnob.dev/api-reference/cards/create-card.md). Card KYC is enabled per account. **August 9, 2026** ## Virtual Accounts API Virtual accounts are dedicated Nigerian bank account numbers issued against one of your customers. Deposits credit your NGN balance, which Get Balances already returns. | Operation | Endpoint | | - | - | | Create an account | `POST /api/virtual-accounts` | | List accounts | `GET /api/virtual-accounts` | | Get one account | `GET /api/virtual-accounts/:id` | | List transactions | `GET /api/virtual-accounts/:id/transactions` | | Update the alias | `PATCH /api/virtual-accounts/:id/alias` | | Simulate a deposit (sandbox) | `POST /api/virtual-accounts/:id/simulate-deposit` | Two requirements before you call create: * The customer must already carry a BVN, meaning an `id_type` of `bvn`, plus date of birth and contact details. * `reference` acts as the idempotency key, so reuse it when you retry. **July 23, 2026** ## Webhook source IPs published The webhook reference pages for addresses, virtual cards, payouts, withdrawals, and beneficiaries now list the addresses Bitnob sends webhooks from, `18.171.51.218` and `13.134.154.133`, with an nginx allow and deny example on each page. These addresses can change. Treat the allowlist as a network convenience rather than a security boundary, and verify the `x-bitnob-signature` header on every event. **July 20, 2026** ## Payout webhooks reference The events emitted across the payout flow of quote, initialize, and finalize are now documented. | Event | Meaning | | - | - | | `payouts.initialized` | The payout was accepted and is queued. | | `payouts.processing` | The settlement rail picked up the payout. This is an in-flight update, not a terminal state. | | `payouts.withdrawal.success` | Funds were delivered. Wait for this before crediting the recipient. | | `payouts.withdrawal.expired` | The payout was not completed in time. | Two things to note when you handle these events: * Each event carries the payout record itself, so field names match the payouts API response, including `quote_id`, `settlement_amount`, `from_asset`, and the nested `beneficiary` object. This replaces the legacy `payout.transfer.*` shape. * `data.status` is the event outcome in lower case, one of `initiated`, `processing`, `success`, or `expired`. It is not the payout record's upper case lifecycle status returned by Get Payout, so branch on the `event` field. **July 15, 2026** ## Interactive API playground Supported API reference sections now include a Try it out panel that sends real, HMAC-signed requests and shows the live response. * As you fill in the path, query, and body fields, the panel builds a syntax-highlighted cURL command you can copy and run as is. * For POST, PUT, and PATCH endpoints, a Raw body tab accepts your own JSON payload. The exact bytes you paste are signed and sent verbatim, and they persist across page refreshes. * You enter your API credentials once. Timestamps, nonces, and signatures are generated on each run. **July 15, 2026** ## Page assistance menu API reference pages now carry a Page Assistance menu with four actions. | Action | What it does | | - | - | | Open in Claude | Launches Claude with a prompt to read the current page. | | Open in ChatGPT | Launches ChatGPT with the same prompt. | | Copy for LLM | Copies the page as clean Markdown. | | View as Markdown | Opens the raw Markdown source in a new tab. | Every action operates on the whole page. **June 12, 2026** ## Stablecoin webhooks reference New stablecoin webhook pages under the Addresses and Withdrawal sections document the `deposit.success`, `transfer.success`, and `transfer.failed` events. Each page covers signature verification with HMAC SHA512 through the `x-bitnob-signature` header, notification retries, local testing, and the full payload field reference with sample payloads. **May 19, 2026** ## Card webhooks v2 Every outbound virtual card webhook moved to a new payload shape. | Before | After | | - | - | | `virtualcard.topup.complete` | `virtualcard.topup.completed` | | `virtualcard.created.complete` | `virtualcard.created.completed` | | `virtualcard.withdrawal.complete` | `virtualcard.withdrawal.completed` | | snake\_case JSON keys | camelCase keys, such as `cardId`, `companyId`, and `createdStatus` | | Float amounts | Integers in micro-units, where 1 USD is 1,000,000, with a sibling `displayAmount` float on transaction events | | Envelope of `eventId`, `event`, and `data` | Same fields plus `companyId` | | No merchant context | Transaction events add `transactionType`, `merchantName`, `merchantMcc`, `merchantCountry`, and `timestamp` | Cross-border transactions emit two variants, `cross_border_pending` for the company wallet fee debit and `cross_border_settled` for the card balance principal debit. Both are `transactionType` values, which stay snake\_case. Contactless and refund events also fire with several `transactionType` values under one `event` string, so branch on `event` first and then on `transactionType`. **May 15, 2026** ## Webhook payloads: top-level event\_id Webhook payloads for card top-up, card withdrawal, stablecoin transfer, and stablecoin deposit events now include a top-level `event_id`, which makes de-duplication and tracing easier. The `transfer.success` event also includes `transaction_id` in its `data` payload. **February 28, 2026** ## Card Issuing API v2 beta New card creation endpoints are available, with support for physical cards, custom BIN ranges, and 3D Secure. **January 30, 2026** ## Virtual Cards API v2 The Virtual Cards API is now resource-oriented. | Before | After | | - | - | | `/api/virtualcards/*` | `/api/cards` and `/api/customers` namespaces | | Implicit card context | Explicit `:cardId` and `:customerId` path parameters | | Operations spread across routes | Card operations under `/api/cards/:cardId/*` | New endpoints cover extended card details, spending limit controls, and customer cards lookup. **January 30, 2026** ## Legacy Virtual Cards endpoints removed Everything under `/api/virtualcards` is no longer supported. Card operations require an explicit `cardId` path parameter instead of implicit context, and the user-based model is replaced by a customer-centric model keyed on `customerId`. Update your integration to the new namespaces before upgrading. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.