Skip to main content
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

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.
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 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. It’s not a commitment. Collect the naira into your NGN balance, for example through a virtual account. 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.
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

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

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. If you get a validation error that isn’t in this table, send support the metadata.request_id from the response.