Create Quote

Retrieve a real-time conversion quote between any two supported currencies: USDT, USDC, Bitcoin, and NGN.

This endpoint allows you to preview the expected rate, amount received, and validity period for a trade between any supported pair (for example USDT ↔ BTC, or NGN ↔ USDT). Quotes can be used to show customers live pricing or to execute a trade with a locked rate.

Endpoint

Full request and response schema: Quotes in the API reference.

Endpoint

For the full request and response schema, see the Create Quote API Reference.

Purpose

Use this endpoint to:

Display current pricing before executing a trade

Evaluate exact cost or return amount for conversions

Fetch trade metadata (fees, expiry, reference) before committing

Re-read a quote you already created with Get Quote by ID, or skip the quote entirely and read indicative pricing from Get Prices

Create Quote Request

parameter	type	required	description
base_currency	string	Yes	The base currency for the trade. One of: BTC, USDT, USDC, or NGN
quote_currency	string	Yes	The quote currency for the trade. One of: BTC, USDT, USDC, or NGN. For naira trades, one side of the pair must be NGN
side	string	Yes	The side of the trade. One of: buy or sell
quantity	string	Yes	The amount of base currency to trade, in major units. Example: 0.0001 (BTC) or 5000 (₦5,000)

Example Request

Example Request (NGN pair)

To quote a naira trade, set base_currency to what you are spending and use side: "sell". Here, 5000 means ₦5,000.

Example Request (NGN)

Successful Response (200 OK)

Response Body

Response Fields

field	type	description
id	string	Unique ID for this quote. Use it when executing the trade
base_currency	string	The base currency for the trade (e.g., BTC)
quote_currency	string	The quote currency for the trade (e.g., USDT)
side	string	The side of the trade: BUY or SELL
quantity	string	The amount of base currency to trade
price	string	The quoted price per unit of base currency in terms of quote currency
expires_at	string	ISO 8601 timestamp after which this quote is no longer valid
created_at	string	ISO 8601 timestamp when the quote was created
original_quantity	string	The original quantity requested when the quote was created
consumed_quantity	string	The amount of the quote already used in executed trades
remaining_quantity	string	The amount still available to trade (original minus consumed)
is_exhausted	boolean	Whether the quote has been fully consumed. If true, no more trades can use this quote
exchange	object	Summary of what will be sent and received if the quote is executed
send_quantity	string	The amount you will send to execute the trade (e.g., 6.91)
send_currency	string	The currency you will send (e.g., USDT for a BUY order)
receive_quantity	string	The amount you will receive after the trade (e.g., 0.00010000)
receive_currency	string	The currency you will receive (e.g., BTC for a BUY order)

Notes

Quotes are valid for a short, fixed time: about 10 seconds in production. In sandbox, NGN quotes last 30 seconds and crypto quotes about 5 minutes. The window cannot be extended, so always drive your timer from the quote's expires_at, never a hard-coded value

Pass the quote's id as quote_id to POST /api/trading/orders to lock the price

Use the price from the quote when creating the order.

Without a quote_id, a crypto-pair trade executes at the current market rate. NGN pairs cannot do this

Fees depend on your integration tier (default is 0)

For NGN pairs, one side of the pair must be NGN, amounts are in major units (naira, not kobo), and a quote_id is required at execution — the rate must be locked before funds move

NGN conversions are limited to ₦500–₦10,000,000 per trade, with no daily or monthly limit. An amount outside the range is rejected when you create the quote, with 400 and code INVALID_AMOUNT

NGN quotes are single-use: one quote backs one order. Crypto quotes can back several orders until remaining_quantity reaches zero

NGN quotes are checked against your balance: if the wallet you are spending from cannot cover the amount, the quote is refused with 422 and "insufficient balance". Check Get Balances before you create the quote

Errors

code	message	fix
400	Invalid quote_currency: ETH. Expected BTC, USDT, or USDC	Use a supported pair (USDT, USDC, BTC, NGN). Naira trades must have NGN on one side
400	Quote quantity must be greater than zero	Send a positive quantity in major units
400	Validation failed	A required field is missing or malformed. The error's details object names each field
400	amount below configured minimum / amount above configured maximum	NGN trades must be between ₦500 and ₦10,000,000. Code is INVALID_AMOUNT
400	Quote quantity too large: maximum 50 BTC	Reduce the quantity or split it across quotes
403	NGN not enabled	Ask Bitnob to enable naira trading on your account. Match on the 403 status, not the message text
422	insufficient balance	NGN pairs only: the wallet you are spending from cannot cover the quote. Code is PRECONDITION_FAILED
500	Quote service unavailable	Retry or contact support if persistent