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 |
|---|---|---|---|
| from | string | Yes | Asset to convert from (usdt or bitcoin) |
| to | string | Yes | Asset to convert to (usdt or bitcoin) |
| amount | integer | Yes | Amount to convert (in cents if from USDT, sats if from BTC) |
| reference | string | Yes | Unique ID for idempotency and traceability |
| quoteId | string | No | Optional. If provided, the rate is locked; otherwise, market rate is used |
| description | string | No | Optional description for your own logs or ledger |
Example Request
Successful Response (200 OK)
Response Fields
| Field | Type | Description |
|---|---|---|
| tradeId | string | Unique ID of the executed trade |
| reference | string | Your submitted reference ID |
| from | string | Source asset type |
| to | string | Destination asset type |
| inputAmount | integer | Amount converted (input) |
| outputAmount | integer | Resulting amount received (output) |
| rate | integer | Executed exchange rate |
| walletId | string | Wallet where the resulting funds were deposited |
| status | string | Status of trade (completed, failed, pending) |
| createdAt | string | ISO 8601 timestamp of execution |
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. |
