Execute Trade

Convert stablecoins to Bitcoin or Bitcoin to stablecoins.

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

Purpose

Use this endpoint to:

Execute a USDT ↔ Bitcoin trade 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 and webhooks

Request Body Parameters

parameter	type	required	description
base_currency	string	Yes	The base currency for the trade. Example: BTC
quote_currency	string	Yes	The quote currency for the trade. Example: USDT
side	string	Yes	The side of the trade. One of: buy or sell
quantity	string	Yes	The amount of base currency to trade. Example: 0.0001
price	string	Yes	The same price from the quote creation. Example: 88989.119625
quote_id	string	Yes	The quote ID from the create quote response
metadata.reference	string	No	Optional reference for your own tracking and logs

Example Request

Successful Response (200 OK)

Response Body

Response Fields

field	type	description
order.id	string	Unique ID of the order
order.base_currency	string	The base currency for the trade (e.g., BTC)
order.quote_currency	string	The quote currency for the trade (e.g., USDT)
order.side	string	The side of the trade (BUY or SELL)
order.order_type	string	The type of order (e.g., limit)
order.quantity	string	The quantity of base currency ordered
order.price	string	The price at which the order was placed
order.status	string	Status of the order (filled, pending, cancelled)
order.created_at	string	ISO 8601 timestamp when order was created
order.updated_at	string	ISO 8601 timestamp when order was last updated
order.filled_quantity	string	The quantity that has been filled
order.remaining_quantity	string	The quantity remaining to be filled
fills.id	string	Unique ID of the fill
fills.order_id	string	The order ID this fill belongs to
fills.quantity	string	The quantity filled
fills.price	string	The price at which the fill was executed
fills.created_at	string	ISO 8601 timestamp when fill was executed

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

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	Only usdt ↔ bitcoin supported.
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.