Execute Trade

Convert between stablecoins, Bitcoin, and NGN.

This endpoint allows you to perform a real-time asset conversion between supported assets. You can execute at current market rate or lock pricing using a previously generated quote ID.

Endpoint

Full request and response schema: Create Order in the API reference.

Endpoint

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

Purpose

Use this endpoint to:

Execute a trade between supported currencies (USDT, USDC, Bitcoin, NGN) for a user or system wallet

Lock in pricing using a valid quote (quoteId)

Route funds directly to your Bitnob wallet for the destination asset

Track every trade via reference ID, Get Order By ID, and webhooks

Request Body Parameters

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)
price	string	Yes	The same price from the quote creation. Example: 88989.119625
quote_id	string	Conditional	The quote ID from the create quote response. Required for NGN pairs; optional for crypto pairs (omit to execute at the live market rate)
reference	string	No	Optional reference for your own tracking and logs

Example Request

Example Request (NGN pair) Preview

Preview — enabled per account

NGN (naira) trading is being rolled out gradually and is not enabled for all companies yet.

For a naira trade, set base_currency to what you are spending and use side: "sell". quote_id is required — carry over the price and id from the quote.

Example Request (NGN)

Successful Response (200 OK)

Response Body

Response Fields

field	type	description
id	string	Unique ID of the order
base_currency	string	The base currency for the trade (e.g., USDT)
quote_currency	string	The quote currency for the trade (e.g., BTC)
side	string	The side of the trade (BUY or SELL)
order_type	string	The type of order (e.g., limit)
quantity	string	The quantity of base currency ordered
price	string	The price at which the order was placed
order.status	string	Status of the order (filled, pending, cancelled)
created_at	string	ISO 8601 timestamp when order was created
updated_at	string	ISO 8601 timestamp when order was last updated
filled_quantity	string	The quantity that has been filled
remaining_quantity	string	The quantity remaining to be filled
quote_id	string	The quote ID used to lock the trade rate
id	string	Unique ID of the fill
order_id	string	The order ID this fill belongs to
counterparty_order_id	string	The counterparty order ID matched against this fill
quantity	string	The quantity filled
created_at	string	ISO 8601 timestamp when fill was executed
quote_id	string	The quote ID that was consumed by this trade
consumed_quantity	string	The quantity consumed from the quote
remaining_quantity	string	The quantity remaining on the quote
is_exhausted	boolean	Whether the quote has been fully consumed

Trade Behavior

If quoteId is provided:

The rate is locked

If the quote is expired, trade will fail (quote_expired)

If quoteId is omitted:

The trade is executed at live market rate

Final output may vary slightly depending on real-time pricing

For NGN pairs: quote_id is always required — naira trades cannot execute at a live market rate, so the rate must be locked with a quote first.

Idempotency

You must submit a unique reference for each trade attempt. Reusing the same reference will return the original trade object — preventing accidental double execution.

Webhooks

On completion, Bitnob will emit:

event	when it fires
trade.completed	When trade is successfully executed
trade.failed	If the trade fails due to quote, balance, or system errors

Errors

code	message	description
400	Quote expired	quoteId is no longer valid.
400	Invalid asset pair	Use a supported pair (USDT, USDC, BTC, NGN); naira trades need NGN on one side.
400	Quote required	quote_id is mandatory for NGN pairs.
403	NGN not enabled	Naira trading is not enabled on your account.
400	Missing or invalid amount	Must be > 0 and in proper unit.
409	Duplicate reference	Trade with that reference already exists.
422	Insufficient balance	Source wallet doesn’t have enough funds.
500	Execution failed	Internal issue; retry or contact support.