> ## 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 has two APIs. The Business API (payouts, cards, trading, virtual accounts, stablecoin and bitcoin transfers) is at https://api.bitnob.com. The Enterprise API (non-custodial wallets) is at https://api.platform.bitnob.com.
> Business API auth: sign every request with HMAC-SHA256 and send four headers: `X-Auth-Client` (your client ID), `X-Auth-Timestamp` (Unix seconds), `X-Auth-Nonce` (16 random bytes, hex), and `X-Auth-Signature`, the hex HMAC-SHA256 of `CLIENT_ID:TIMESTAMP:NONCE:BODY` keyed with your client secret. BODY is the exact request body string you send, or an empty string. A missing header, a bad signature, or a timestamp more than about 5 minutes off returns `401`.
> Enterprise API auth: send your key in the `X-API-Key` header. Write requests such as creating a transaction also need an `Idempotency-Key` header, or they fail with `idempotency_key_required` before anything happens.
> Sandbox and production share the Business API base URL. The credentials you sign with select the environment, and `GET /api/whoami` returns it in `data.environment`. Use sandbox credentials in sample code and tests, and never put live credentials in code.
> Amounts are strings unless stated otherwise. Never parse them into floats. Balances, transactions, withdrawals (`POST /api/withdrawals`) and virtual accounts use integer strings in the smallest unit: satoshis for BTC, 6 decimals for USDT and USDC, kobo for NGN, and cents for KES and UGX (100 is 1 KES or 1 UGX). A mobile money collection takes `amount` as a JSON integer in cents.
> Payouts and trading use decimal strings in major units: a payout quote `amount` of `"1"` is 1 USDT, and a trading `quantity` of `"0.0001"` is 0.0001 BTC. Payout responses also carry `cent_amount`, the settlement amount in minor units.
> Card amounts are micro-units (1 USD = 1,000,000). Send them as JSON integers. Card responses return them as integer strings, and card webhooks as integers.
> Generate a unique `reference` for each money movement before the first attempt, and reuse it on retries. A reused reference returns `409` on payout quotes (`ALREADY_EXISTS`), withdrawals (`DUPLICATE_KEY_ERROR`) and card creation (`ALREADY_EXISTS`). It returns the existing record on NGN-pair trading orders, NGN virtual accounts and active mobile money collections. On a mobile money collection that has closed or failed it returns `409` `DUPLICATE_REFERENCE`. It isn't checked on crypto-pair trading orders, so look the order up with `GET /api/trading/orders/{reference}` before resending.
> Quotes expire at `expires_at`; read it from the response instead of assuming a window. An expired trading quote returns `422` `PRECONDITION_FAILED`, and an expired payout quote returns `400` `VALIDATION_ERROR`. Create a new quote rather than retrying. A payout quote can be initialized once, and a trading quote is consumed by the order that fills it.
> Webhooks: verify the `x-bitnob-signature` header, the hex HMAC-SHA512 of the raw request body keyed with your webhook secret, before parsing JSON. Compare in constant time and de-duplicate on `event_id`. A successful API response means accepted: confirm the outcome from the webhook, such as `payouts.withdrawal.success`.
> Errors return `status`, `code` and `detail`. Branch on `code`, never on `detail`. Since the November 5, 2026 response format change, each company gets either the current or the new error codes until its cutoff date, so handle both: `PROVIDER_ERROR` or `PROCESSING_ERROR`, and `BVN_PROVIDER_UNAVAILABLE` or `BVN_VERIFICATION_UNAVAILABLE`. A body that fails to parse returns `{"error": {"code": "BAD_REQUEST"}}`.

# Payouts API integration guide

> A worked payout integration in order: signed request, quote, initialize, finalize, and webhook confirmation.

This guide walks you through everything needed to send a payout, from authenticating your first request to confirming that funds have reached your beneficiary.

A payout delivers local fiat (e.g. NGN, KES, GHS) to a beneficiary's bank or mobile-money account, funded from crypto. You create payouts through a simple, quote-based flow.

The authentication scheme on this page is a summary. [API authentication](https://www.bitnob.dev/api-reference/authentication/authentication.md) is the source of truth for the signing spec.

## Before you begin

You will need:

| What | Where to get it |
| - | - |
| Base URL | `https://api.bitnob.com` for both sandbox and production. |
| Client ID | From your dashboard, under API keys. The same value in both environments. |
| Client Secret | Shown once when you generate your API key. Sandbox and production have different secrets. |

### Test in sandbox first

Always test end-to-end in sandbox first. Sandbox lets you complete a full payout, including funding, without moving real money.

There is no separate sandbox host. Both environments use `https://api.bitnob.com`, and the secret you sign with selects the environment. To go live, swap the secret, not the URL.

```bash theme={null}
# One base URL for both environments
BASE_URL="https://api.bitnob.com"

# From your dashboard, under API keys.
# CLIENT_ID is the same in both environments; the secret is not.
CLIENT_ID="<your-client-id>"
CLIENT_SECRET="<your-sandbox-or-production-secret>"   # shown once, store it securely
```

## Authentication

Every API request is authenticated with an HMAC-SHA256 signature. You sign each request with your Client Secret and send four headers. Signatures are time-limited: a request stops being accepted about five minutes after its timestamp.

### Required headers

| Header | Value |
| - | - |
| X-Auth-Client | Your Client ID |
| X-Auth-Timestamp | Current Unix time, in seconds |
| X-Auth-Nonce | 16 cryptographically random bytes, hex-encoded |
| X-Auth-Signature | HMAC-SHA256 signature (hex-encoded): see below |

```http theme={null}
X-Auth-Client:    <your-client-id>
X-Auth-Timestamp: 1751452800
X-Auth-Nonce:     3f9a1c2e7b904d219e5a2c8f6b1d0a4e
X-Auth-Signature: 9c1f4b2e8a7d6c5f0e3b1a9d8c7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f
```

## How to build the signature

Build the payload string by joining four parts with colons, then sign it with your Client Secret using HMAC-SHA256 and hex-encode the result.

REQUEST\_BODY is the exact raw JSON body you send. For requests with no body (e.g. `GET`, or the finalize call), use an empty string.

> [!WARNING]
>
> Sign the body byte-for-byte as it is sent. If you re-serialize or reformat the JSON after signing, the signature will not match.

```
payload = CLIENT_ID + ":" + TIMESTAMP + ":" + NONCE + ":" + REQUEST_BODY
signature = HMAC-SHA256(CLIENT_SECRET, payload)   →  hex
```

## Common auth errors

| Problem | Fix |
| - | - |
| Invalid signature | Confirm the Client Secret and that the signed body exactly matches the sent body. |
| Timestamp outside acceptable range | Sync your clock; send the timestamp in seconds, not milliseconds. |
| 401 Unauthorized | A header is missing or the signature is wrong. |
| 403 Forbidden | Authenticated, but your key lacks permission for this action. |

```json theme={null}
// 401 Unauthorized: a header is missing, the signature is wrong, or the timestamp is out of range
{
  "type": "https://api.bitnob.com/errors/UNAUTHORIZED",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication failed",
  "code": "UNAUTHORIZED"
}

// 403 Forbidden: the key lacks permission for this action
{
  "type": "https://api.bitnob.com/errors/FORBIDDEN",
  "title": "Forbidden",
  "status": 403,
  "detail": "Not permitted for this action",
  "code": "FORBIDDEN"
}
```

```bash theme={null}
CLIENT_ID="your_client_id"
CLIENT_SECRET="your_client_secret"
TIMESTAMP=$(date +%s)
NONCE=$(openssl rand -hex 16)
REQUEST_BODY='{"from_asset":"BTC","to_currency":"NGN","source":"offchain","country":"NG","settlement_amount":"50000","reference":"ref-123"}'

PAYLOAD="${CLIENT_ID}:${TIMESTAMP}:${NONCE}:${REQUEST_BODY}"
SIGNATURE=$(printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "$CLIENT_SECRET" -hex | awk '{print $2}')

curl -X POST "${BASE_URL}/api/payouts/quotes" \
  -H "Content-Type: application/json" \
  -H "X-Auth-Client: ${CLIENT_ID}" \
  -H "X-Auth-Timestamp: ${TIMESTAMP}" \
  -H "X-Auth-Nonce: ${NONCE}" \
  -H "X-Auth-Signature: ${SIGNATURE}" \
  -d "$REQUEST_BODY"
```

## Understanding funding: offchain vs onchain

When you create a quote you choose a source, which decides where the funds come from:

| Source | Meaning |
| - | - |
| offchain | Your Bitnob account balance is charged directly. No external deposit. The balance must cover the payout. |
| onchain | You send a crypto deposit to a generated address to fund the payout. The deposit can be BTC (on-chain), Lightning, or stablecoins. |

Everything else in the flow is identical; only the funding step differs.

```javascript theme={null}
const crypto = require("crypto");

function signedHeaders(clientId, clientSecret, body = "") {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const nonce = crypto.randomBytes(16).toString("hex");
  const payload = `${clientId}:${timestamp}:${nonce}:${body}`;
  const signature = crypto
    .createHmac("sha256", clientSecret)
    .update(payload)
    .digest("hex");

  return {
    "Content-Type": "application/json",
    "X-Auth-Client": clientId,
    "X-Auth-Timestamp": timestamp,
    "X-Auth-Nonce": nonce,
    "X-Auth-Signature": signature,
  };
}
```

## Reference lookups (recommended first)

Use these read-only calls to build a valid request. They help you pick a supported country, the exact beneficiary fields it needs, valid bank codes, and transaction limits.

Verify a beneficiary account before paying it. The lookup returns the resolved account name.

```http theme={null}
GET {BASE_URL}/api/payouts/supported-countries          # countries you can pay out to
GET {BASE_URL}/api/payouts/supported-countries/NG       # required beneficiary fields for Nigeria
GET {BASE_URL}/api/payouts/banks/NG                      # bank names + codes for Nigeria
GET {BASE_URL}/api/payouts/limits?country=NG&currency=NGN

# Verify a beneficiary account
GET {BASE_URL}/api/payouts/account-lookup?country=NG&account_number=0123456789&bank_code=000013
```

## Step 1: create a quote

Locks in the exchange rate and fees for your payout. The response returns a `quote_id`, the rate, fees, and an expiry. Quotes expire, continue promptly.

| Field | Required | Notes |
| - | - | - |
| from\_asset | Required | The crypto asset funding the payout, e.g. BTC, USDT. |
| to\_currency | Required | Fiat the beneficiary receives, e.g. NGN. |
| source | Required | offchain (charge balance) or onchain (crypto deposit). |
| country | Required | Destination country code, e.g. NG. |
| settlement\_amount | One of | Amount the beneficiary should receive, in to\_currency. |
| amount | One of | Alternatively, the amount in from\_asset. Provide one side. |
| payment\_reason | Optional | Shown for your records. |
| reference | Optional | Your own unique reference: use it to make retries safe and to look the payout up later. |

```json theme={null}
// offchain: charge your Bitnob balance directly (no deposit)
{
  "source": "offchain"
}

// onchain: fund with a crypto deposit (BTC, Lightning, stablecoins)
{
  "source": "onchain",
  "chain": "TRON"
}
```

```http theme={null}
POST {BASE_URL}/api/payouts/quotes
Content-Type: application/json
```

## Step 2: add the beneficiary (initialize)

Attach the recipient's details to the quote. The exact `beneficiary` fields depend on the country (see Reference Lookups).

callback\_url is where we'll notify your system of status changes. Recommended.

customer\_id (optional) links the payout to a customer in your account.

```json theme={null}
{
  "beneficiary": {
    "account_number": "0123456789",
    "bank_code": "000013",
    "account_name": "Jane Doe"
  },
  "reference": "your-unique-ref-123",
  "payment_reason": "Invoice payment",
  "callback_url": "https://your-app.example.com/webhooks/payout"
}
```

```http theme={null}
POST {BASE_URL}/api/payouts/{quoteId}/initialize
Content-Type: application/json
```

## Step 3: finalize (approve and submit)

Approves the payout and submits it for processing. No request body: remember to sign with an empty body string.

For `offchain` payouts, your account balance is charged at this step.

```http theme={null}
POST {BASE_URL}/api/payouts/{quoteId}/finalize
```

## Step 4: fund the payout

**offchain**: nothing to do. Your balance was charged at finalize, and the payout proceeds automatically to settlement.

**onchain**: send a crypto deposit to the address / instruction returned from the previous step. You can fund it with BTC (on-chain), Lightning, or stablecoins. Once the deposit confirms, settlement proceeds.

> [!NOTE]
>
> Sandbox has no endpoint that simulates a crypto deposit for a payout, so an onchain payout you don't fund stays in `PENDING_ADDRESS_DEPOSIT`.

## Step 5: track to completion

We settle the fiat to the beneficiary and update the payout status. Track it by polling, or (preferred) by receiving webhooks at your `callback_url`.

## Payout statuses

A payout moves through these states:

| Status | Meaning |
| - | - |
| `INITIATED` | Created and awaiting finalize. |
| `PENDING_ADDRESS_DEPOSIT` | Waiting for the on-chain deposit. |
| `PENDING` | Finalized and queued. |
| `PROCESSING` | Funded; settlement to the beneficiary is in progress. |
| `SUCCESS` | Funds delivered to the beneficiary. |
| `FAILED` | The payout could not be completed. |
| `UNDERPAYMENT` | The deposit was less than the required amount. |
| `EXPIRED` | The quote expired before funding arrived. |

Treat `SUCCESS` as the only success state. Always confirm final status via a status lookup or webhook: don't assume success from the finalize response alone.

## Full worked example (offchain)

Use a signed-request helper that sets the `X-Auth-*` headers for each call. Create a quote with the body below, attach the beneficiary, finalize, and track by `reference`, reusing one reference throughout.

```json theme={null}
{
  "from_asset": "BTC",
  "to_currency": "NGN",
  "source": "offchain",
  "country": "NG",
  "settlement_amount": "50000",
  "payment_reason": "Invoice payment",
  "reference": "your-unique-ref-123"
}
```

## Webhooks

If you set `callback_url` when initializing, we send a notification to that URL whenever the payout's status changes. Best practices:

Respond quickly with a `2xx`. Do heavy processing asynchronously.

Be idempotent. The same event may be delivered more than once.

Use your `reference` to reconcile events against your own records.

## Error handling

Errors use standard HTTP status codes with a consistent JSON body. Include the `correlation_id` from the response when contacting support, it identifies the exact request. Responses also carry `request_id` with the same value.

| Status | Meaning |
| - | - |
| 400 | Invalid request: check the message and field details. |
| 401 | Authentication failed (missing/invalid signature or headers). |
| 403 | Authenticated but not permitted for this action. |
| 429 | Rate limited: slow down and retry with backoff. |
| 5xx | Temporary issue on our side: retry with backoff. |

## Go-live checklist

Completed a full sandbox payout end-to-end (`SUCCESS` status observed).

Signature generation verified for both bodied and empty-body requests.

Store your reference for every payout and reconcile via lookups/webhooks.

Handle `PENDING`, `PROCESSING`, `SUCCESS`, `FAILED`, and `EXPIRED` in your system.

Client Secret stored securely (never in client-side code or version control).

Switched from the sandbox secret to the production secret.

## Support

Include the `correlation_id` from the failing response and your payout `reference` when reaching out. Reach your Bitnob integration contact or the support channel provided with your account.


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