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

# Lock a naira total before you charge

> Quote NGN to USDT through the Trading API, how long the quote holds, the per-trade limits, and how to test NGN pairs in sandbox.

Use this page if you show a merchant a fixed naira total and charge them only after they accept it. It covers three questions:

1. Can you get an NGN to USDT quote before you charge?
2. How long does the quote hold, and what are the minimum and maximum per trade?
3. Where can you test NGN pairs?

## Quick answers

| Question | Answer |
| - | - |
| Quote NGN to USDT before charging? | Yes, with `POST /api/trading/quotes`. The quote is drawn on your NGN balance, though. It's refused unless that balance already covers the naira. |
| How long a quote holds | 30 seconds. Read `expires_at` on every quote. You can't extend it. |
| Single-use? | Yes. One NGN quote backs exactly one order. |
| Minimum and maximum per trade | ₦500 to ₦10,000,000, measured on the naira side. There's no daily or monthly cap on NGN pairs, but your account tier can still limit the USDT side. |
| Testing | Sandbox supports NGN pairs. Fund your sandbox NGN balance with simulated deposits first. |

## Quote the naira total

Name the amount you want fixed, and the quote computes the other side.

**The merchant receives a fixed amount of USDT.** Set `base_currency` to `USDT` and `side` to `buy`, and put the USDT amount in `quantity`. The naira total is `exchange.send_quantity`, rounded up to the kobo.

```bash theme={null}
curl --location 'https://api.bitnob.com/api/trading/quotes' \
--header 'Content-Type: application/json' \
--header 'x-auth-client: CLIENT_ID' \
--header 'x-auth-timestamp: TIMESTAMP' \
--header 'x-auth-nonce: NONCE' \
--header 'x-auth-signature: SIGNATURE' \
--data '{
    "base_currency": "USDT",
    "quote_currency": "NGN",
    "side": "buy",
    "quantity": "100"
}'
```

```json theme={null}
{
  "quote": {
    "id": "019a3b5c-81f0-7b2e-9c3d-4e5f60718293",
    "base_currency": "USDT",
    "quote_currency": "NGN",
    "side": "BUY",
    "quantity": "100",
    "price": "1563.9196",
    "expires_at": "2026-10-30T09:14:52Z",
    "created_at": "2026-10-30T09:14:22Z",
    "exchange": {
      "send_quantity": "156391.96",
      "send_currency": "NGN",
      "receive_quantity": "100",
      "receive_currency": "USDT"
    }
  }
}
```

Show `exchange.send_quantity` as the total, here ₦156,391.96. Don't recompute it from `price`, which is rounded to 8 decimal places.

**The merchant spends a fixed naira amount.** Set `base_currency` to `NGN` and `side` to `sell`, and put the naira amount in `quantity`. The USDT they get is `exchange.receive_quantity`.

To lock the rate, pass the quote's `id` as `quote_id` to [Create order](https://www.bitnob.dev/docs/trading/execute-trade.md) before `expires_at`.

## The quote is drawn on your NGN balance

When you create an NGN to USDT quote, Bitnob checks that your NGN balance covers the naira side. If it doesn't, the quote is refused with `422` `INSUFFICIENT_FUNDS`, and no quote is created.

That decides the order of your flow. You can't lock a total for naira you haven't collected. Pick one of these patterns.

**1. Collect first, then lock and convert**

While the merchant decides, show an indicative rate from [Get exchange rate](https://www.bitnob.dev/api-reference/exchange-rates/get-single-pair-rate.md). It's not a commitment. Collect the naira into your NGN balance, for example through a [virtual account](https://www.bitnob.dev/docs/fiat-collections/set-up-virtual-accounts.md). Then quote and execute straight away. Use this pattern when the merchant pays by bank transfer: a 30-second quote can't last through a transfer.

**2. Keep an NGN float**

Hold enough naira in your Bitnob NGN balance to cover the trades you expect at once. You can then quote, show the merchant the locked total, and execute within the 30 seconds. Collect from the merchant separately. You carry the gap between charging them and settling with your float.

> [!WARNING]
>
> A locked total holds for 30 seconds. If your charge can take longer than that, don't present the quote as the price the merchant pays. Show the indicative rate instead, and lock the quote once the naira is in your balance.

## How long a quote holds

* **Lifetime:** NGN quotes last 30 seconds. Drive any countdown from `expires_at`, never from a hard-coded value. Disable the confirm button when it passes.
* **Single-use:** one quote backs one order. A second order with the same `quote_id` is refused with `422`.
* **Expired quotes:** an order placed after `expires_at` is refused with `422` `PRECONDITION_FAILED`, and no money moves. Request a new quote and show the new total.
* **Rate checks at execution:** Bitnob refuses to execute a quote whose underlying rate has gone stale, or if the market has moved too far from it. You get `422` and nothing moves. Treat it like an expired quote.

## Limits per trade

| Limit | Value | Error when crossed |
| - | - | - |
| Naira side, per trade | ₦500 minimum, ₦10,000,000 maximum | `400` `INVALID_AMOUNT` when you create the quote |
| NGN pairs, daily or monthly | None | |
| Your account tier | Applies to the USDT side | `412` `TIER_LIMIT_REACHED`, with how much room is left |
| Quote requests | 10 a second and 600 an hour for each organization | `429` `RATE_LIMIT_EXCEEDED` |

When you name the USDT side, the naira amount is only known after pricing. The ₦500 to ₦10,000,000 range is then checked on the computed total. For example, a 2 USDT quote can fall under ₦500 and be refused.

Don't request a quote on every page load, or you'll hit the quote rate limit. Use the indicative rate for browsing, and request a quote when the merchant is ready to commit.

## Test NGN pairs in sandbox

Sandbox runs NGN pairs on the same endpoints and rules as production. Trades settle without real money.

**1. Fund your sandbox NGN balance**

Create a sandbox virtual account. Then call [Simulate deposit](https://www.bitnob.dev/api-reference/virtual-accounts/simulate-deposit-sandbox.md) to credit your NGN balance. Each call adds ₦10,000, up to ₦100,000 an hour. A quote for a larger total is refused with `422` `INSUFFICIENT_FUNDS` until you've deposited enough.

**2. Quote**

Send the requests above to `https://api.bitnob.com`, signed with your sandbox `CLIENT_SECRET`. The base URL and `CLIENT_ID` are the same as in production.

**3. Execute and confirm**

Place the order with the quote's `id` as `quote_id`. Then confirm the outcome with [trade webhooks](https://www.bitnob.dev/docs/trading/trade-webhooks.md).

### When an NGN quote returns a validation error

These are the requests that return `400` on NGN pairs, and how to fix each one. The error's `details` (for `Validation failed`) or `detail` names the problem.

| What you see | Cause | Fix |
| - | - | - |
| `Invalid request body` | `quantity` sent as a JSON number, such as `5000` | Send it as a string: `"5000"`. |
| `Validation failed` | `base_currency`, `quote_currency`, `side` or `quantity` is missing or malformed | Send all four. `side` is `buy` or `sell`. Currencies are letters only, such as `NGN` and `USDT`. |
| `VALIDATION_ERROR`, "amount has more decimal places than the currency supports" | Too many decimals | Use at most 2 decimals for NGN, 6 for USDT and USDC, and 8 for BTC. |
| `VALIDATION_ERROR`, "provide exactly one of from\_amount or to\_amount" | `quantity` is `"0"` | Send a positive amount. |
| `INVALID_AMOUNT`, "amount below configured minimum" | The naira side is under ₦500. This includes a small USDT amount whose naira total comes to less than ₦500. | Raise the amount. |
| `INVALID_AMOUNT`, "amount above configured maximum" | The naira side is over ₦10,000,000 | Split the trade across several quotes. |
| `Invalid quote_currency: NGN` or `Invalid base_currency: NGN` | NGN is on both sides, or paired with an asset other than USDT, USDC or BTC, so the request was treated as a crypto pair | Put NGN on exactly one side, and USDT, USDC or BTC on the other. |

If you get a validation error that isn't in this table, send support the `metadata.request_id` from the response.


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