Trading
The Trading APIs allow you to exchange between supported currencies and crypto assets. This includes converting fiat to crypto (e.g., USD to BTC) or vice versa.
Initialize Trading
This endpoint allows you to initialize a crypto-fiat trade by specifying the asset to be traded, the amount, and the trade direction (buy/sell). It is commonly used to lock in a rate before executing the final trade using a separate finalize endpoint.
Body Parameters
The amount in USD to be converted into BTC.
Headers
Expected response type. Should be 'application/json'.
Media type of the request body. Must be 'application/json'.
Initialize Trading Response
Indicates if the trade quote was successfully generated. true means the quote was created without errors.
A short, human-readable message describing the outcome of the quote request.
The unique identifier for the quote. This ID is used later when finalizing the trade.
The amount in USD (or your selected base currency) that the quote was generated for.
The estimated volume of BTC you will receive for the quoted amount, based on the current market rate.
The BTC/USD price at the moment the quote was generated. This is used to calculate the volume from the amount.
A description of the quote, usually indicating the type of trade or context (e.g., 'quote for buying $10 of BTC').
An ISO 8601 timestamp specifying when the quote will expire. After this time, the quote is no longer valid for finalizing a trade.
Number of seconds until the quote expires. Useful for countdowns in UI or retry logic.
Internal versioning property, often used by the backend for concurrency or schema tracking. Usually not required by clients.
A convenient alias for quoteId. This value is also required when finalizing the trade using a quote.
Optional server-side timestamp when the quote was created. Can be used for logging or request tracking (if returned).
Describes the type of quote being generated. For example, 'buy' or 'sell'. May be returned depending on the system setup.
The cryptocurrency asset being quoted for conversion (e.g., BTC).
The fiat currency from which the asset is being bought or sold (e.g., USD).
Finalize Trade: USD to BTC
This endpoint is used to complete a trade from USD to BTC using a previously generated quote. You must provide the quoteId received from the initialize trade endpoint, and optionally specify the amount and a reference.
Body Parameters
The quote ID received from the initialize trade response.
The amount in USD to finalize in the trade.
A custom identifier for the transaction.
Headers
Expected response format. Set to application/json.
Content type of the request payload. Set to application/json.
Response Fields
Indicates whether the trade was successful. A value of true means the operation completed without error.
Message confirming the result of the trade. Useful for debugging or displaying user feedback.
Unique identifier of the finalized trade transaction. This can be used to retrieve the transaction later.
ISO 8601 timestamp indicating when the trade was created and finalized.
Timestamp of the most recent update to the trade record, typically the same as createdAt unless changes occurred.
A custom or auto-generated reference string used to uniquely tag the trade transaction. Useful for reconciliation or tracking.
A human-readable string describing the nature of the transaction (e.g., 'sell usd', 'swap to BTC').
The user’s or company’s wallet balance after the trade was completed. Helps in tracking post-trade account state.
The actual amount involved in the trade, expressed in the major currency unit (e.g., 10 for $10).
Amount in the smallest currency unit (e.g., cents for USD), typically amount * 100.
Total fees charged for the trade operation, expressed in major units (e.g., dollars).
Total trade fee in the smallest unit (e.g., cents). Useful for precision accounting.
The exact exchange rate applied at the time the trade was executed. This is crucial for pricing transparency.
Indicates the type of trade action executed, such as 'swap_usd_btc' or 'trade_usd_ngn'. This can be used for filtering or audit trails.
Type of wallet operation — commonly 'debit' or 'credit'. It reflects the nature of value movement.
The final status of the trade operation. Expected values include 'success', 'failed', or 'pending'.
The processing channel or interface through which the trade occurred (e.g., 'trade', 'api', or 'dashboard').
UUID of the company account that initiated the trade. This is useful in multi-tenant systems to identify the context of the operation.
The currency used for the transaction (e.g., USD, NGN). Important when supporting multiple currencies.
The crypto asset traded against (e.g., BTC, USDT). Helps determine what was received in exchange.