> ## 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"}}`.

# HMAC generator

> Generate and verify HMAC-SHA256 signatures in your browser, including the exact signing scheme Bitnob API v2 uses.

Hash-based message authentication codes (HMAC) provide both data integrity and authenticity: only a holder of the secret key can produce a valid signature, and any change to the message invalidates it. Bitnob API v2 signs every request with HMAC-SHA256, see [Authentication](https://www.bitnob.dev/api-reference/authentication/authentication.md) for the full scheme.

HMAC generator

Computed locally in your browser with the Web Crypto API. Nothing you type leaves this page.

Secret key

Algorithm

Message to sign

Generate HMAC

Clear

HMAC signature (hex)

## Generate an HMAC-SHA256 signature

Pick your tool and run it locally. All three produce the same hex-encoded output for the same key and message.

```bash openssl theme={null}
echo -n 'message-to-sign' | openssl dgst -sha256 -hmac 'your-secret-key'
```

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

const signature = crypto
  .createHmac("sha256", "your-secret-key")
  .update("message-to-sign")
  .digest("hex");

console.log(signature);
```

```python Python theme={null}
import hmac, hashlib

signature = hmac.new(
    b"your-secret-key",
    b"message-to-sign",
    hashlib.sha256,
).hexdigest()

print(signature)
```

## Sign a Bitnob API v2 request

Bitnob's canonical message is `CLIENT_ID:TIMESTAMP:NONCE:PAYLOAD`, signed with your client secret:

```bash theme={null}
CLIENT_ID="your-client-id"
CLIENT_SECRET="your-client-secret"
TIMESTAMP=$(date +%s)
NONCE=$(openssl rand -hex 16)
PAYLOAD='{"amount":100}'   # empty string for GET requests

STRING_TO_SIGN="$CLIENT_ID:$TIMESTAMP:$NONCE:$PAYLOAD"
SIGNATURE=$(echo -n "$STRING_TO_SIGN" | openssl dgst -sha256 -hmac "$CLIENT_SECRET" | awk '{print $2}')

echo "X-Auth-Client:    $CLIENT_ID"
echo "X-Auth-Timestamp: $TIMESTAMP"
echo "X-Auth-Nonce:     $NONCE"
echo "X-Auth-Signature: $SIGNATURE"
```

Sign the exact bytes you send. If your HTTP client re-serializes the JSON body (reorders keys, changes whitespace), the signature will not match: send the same string you signed.

## Verify a webhook signature

Bitnob signs webhook deliveries with the `x-bitnob-signature` header. Recompute the HMAC over the raw request body and compare in constant time:

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

function verifyWebhook(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac("sha512", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(signatureHeader, "hex"),
  );
}
```

See [Verifying events](https://www.bitnob.dev/api-reference/webhooks.md#verify-every-delivery) for the full webhook reference.

## Security practices

* Keep secret keys confidential and server-side.
* Use strong, random secret keys.
* Prefer HMAC-SHA256 or stronger over HMAC-SHA1.
* Compare signatures with a constant-time function, never `==`.


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