Convert Estimate
The endpoint creates a quote for converting one currency to another. Quote lifetime is 10 seconds, then quote will be expired.
Convert through the API takes the source currency from the trade (spot) balance and puts the converted amount on the same balance. When the source currency is not on the trade balance, the request fails with the insufficient-balance error and no funds move. Transfer the funds to the trade balance first with Transfer between balances, and transfer the converted amount back to the main balance before a withdrawal. A transfer returns 201 with an empty array. The 201 means the platform accepted the transfer, not that the funds moved, so request the estimate after the amount shows on the trade balance.
A quote executes in full at the quoted amounts or not at all. With direction: "to", the amount received equals the requested amount exactly: the platform builds the fee into the amount given, so the fee never reduces the amount received.
The minimum convert size is derived from the resulting proceeds, not a fixed per-pair floor: a request is rejected as too small when rate × amount rounds to zero in the target currency. The endpoint checks the trade balance at estimate time, and Convert Confirm checks the trade balance again at confirm time, because the balance can change within the 10-second quote window. An amount above the absolute server-side maximum is rejected with 422.
An amount outside 0.00000001–100000000000 returns 422 with code 30 under errors.amount. Send amount as a string. The endpoint currently tolerates a JSON number for amount but can lose precision beyond approximately 15 significant digits; do not rely on the tolerance. The endpoint can still reject an amount inside the allowed range as too small for the pair when the amount converts to zero.
from and to must differ. A request with the same currency in both fields returns 422 with code 30 under errors.from.
An amount that the conversion engine cannot fill returns 400 with code 32 under errors.request, for one of two reasons: the amount exceeds the engine’s amount limit (amountTooHigh example) or liquidity is insufficient (amountNotProcessable example). When the trade balance is insufficient, the endpoint returns the insufficient-balance error (400, code 37, insufficientBalance example) before either of these checks.
The endpoint validates the request in stages. An empty body reports only from and to under errors; the endpoint checks direction and amount once from and to are present, so a request that fixes an empty-body 422 can receive a second 422 for the remaining parameters.
The endpoint can be used to obtain a pre-execution price estimate for a market order. Call the endpoint with the desired amount before placing a market order to see the approximate execution price. The endpoint checks the trade balance first, so the amount must be available on the trade balance.
Error text is not part of the contract and may change. Treat the HTTP status, the code, and the field name under errors as the stable contract.
Rate limit: 10000 requests/10 sec.
Used in these guides
- Payment Integration — crypto deposits, withdrawals, conversion, WhiteBIT Codes, and Express Withdraw.
Authorizations
Body
Response
Successful response
Was this page helpful?