When to use Convert
Convert also serves as a price estimation tool. Call the estimate endpoint before placing a market order to preview the approximate execution price. The estimate checks the Trade balance first, so the amount must be available on the Trade balance.
Balances
Convert through the API uses the Trade balance for both legs: the conversion takes the source currency from the Trade balance and puts the converted amount on the Trade 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 source currency from Main to Trade with Transfer between balances before converting (in the transfer request, the Trade balance isspot in the from and to fields), and request the estimate after the transferred amount shows on the Trade balance. The withdrawal endpoints debit the Main balance, so transfer the converted amount back to Main and withdraw after the amount shows on the Main balance (POST /api/v4/main-account/balance).
A transfer returns 201 with an empty array ([]). The 201 means the platform accepted the transfer, not that the funds moved, so read the Trade balance (POST /api/v4/trade-account/balance) until the amount shows.
The transfer request takes no idempotency key, and a transfer can still complete after a timeout or a 5xx. A matching record in Get transfer history means the transfer completed. No record can also mean the transfer is still queued, so repeat the check and do not resend automatically. A transfer that never shows is a manual check, as the between-balances row in Retry strategy by error type describes.
Conversion flow
The quoted-rate flow has two steps: estimate and confirm.1
Request a quote
Send a
POST request to /api/v4/convert/estimate with the following parameters: from (source ticker), to (destination ticker), direction ("from" or "to"), and amount. The response includes id (quote identifier), give, receive, rate, and expireAt.2
Confirm the quote
Send a
POST request to /api/v4/convert/confirm with quoteId set to the id returned by the estimate. The response returns finalGive and finalReceive.Each estimate response includes an
expireAt timestamp in Unix seconds — confirm before that moment. Honor the value returned per quote rather than hard-coding a fixed window. If the quote expires before confirmation, request a new estimate.quoteId round-trip is needed. The endpoint accepts an optional idempotency key that makes a retry safe within the limits in Convert Auto Confirm; see also Results and retries.
Results and retries
A200 response means the conversion executed, and a request that fails never returns 200. When two conversions compete for the same funds, only one executes; the other returns the insufficient-balance error. Two 200 responses with the same id come only from two auto-confirm requests with the same idempotency key, and describe one conversion. Key the partner’s ledger on the quote ID: the id from Auto Confirm, or the quoteId sent to Confirm.
A quote executes in full at the quoted amounts or not at all. With direction: "to", the amount received equals the requested amount exactly, because the platform builds the fee into the amount given. Rarely, the platform refuses a confirm when the price moves after the estimate. The platform then converts nothing; request a new estimate.
The following responses leave the outcome open, and the conversion may have executed:
A resend with an idempotency key follows these rules:
- Within 24 hours, the endpoint returns the original response, or
409while the conversion is still running; retry later with the same key. - If processing stops without recording an outcome, the claim on the key lapses after 60 seconds, and a retry with the same key can then convert a second time.
- A resend that comes more than 60 seconds after the first request needs a Convert History check by time window, pair, and amounts first.
- After 24 hours, a resend with the same key can convert a second time.
24, so look up the quoteId before requesting a new estimate.
Convert Auto Confirm describes how long the platform holds a key.
API endpoints
Convert uses 4 authenticated endpoints. All require HMAC-SHA512 signing. Before the first conversion, the account owner accepts the Convert terms once on whitebit.com; sub-accounts do not accept the terms separately. Until then, the estimate and auto-confirm endpoints returnTerms of exchange are not accepted.
Estimate parameters
Code example
Estimate a BTC-to-USDT conversion and confirm the quote.- cURL
- Python
History filters
The history endpoint supports filtering byfromTicker, toTicker, quoteId, and time range (from/to timestamps). The default limit is 100 records. The maximum history depth is 180 days, counted back from the time of the request. Each request covers at most 30 days between from and to, and from defaults to 30 days before the request. The endpoint rejects a wider range with 422. Reading the full 180 days takes consecutive requests of up to 30 days each.
Convert in payment flows
Withdrawal flows commonly use Convert when the currency held in Main balance differs from the currency an end user needs to withdraw. The pattern has five steps:- Transfer the source currency from Main to Trade, and wait until the amount shows on the Trade balance.
- Request an estimate.
- Confirm the quote.
- Transfer the converted amount from Trade to Main, and wait until the amount shows on the Main balance.
- Submit the withdrawal in the destination currency.
uniqueId (up to 255 characters), and map that reference to the quote IDs of the conversions the withdrawal spends.
For the full step-by-step withdrawal-with-conversion flow including code examples, see Payment Integration.
What’s next
Payment Integration
Deposit and withdrawal flows including conversion.
Spot Trading
Place orders on the orderbook with 6 order types.
WhiteBIT Codes
Transfer funds between accounts using fee-free digital vouchers.