Convert

Convert provides instant currency conversion at a quoted rate. Unlike spot trading, Convert requires no orderbook interaction — request a quote, confirm within 10 seconds, and the conversion executes immediately.

When to use Convert

Feature	Convert	Spot Trading
Execution	Instant at quoted rate	Depends on orderbook liquidity
Orderbook	No orderbook interaction	Orders placed on the orderbook
Order types	Single quote-and-confirm flow	6 order types (limit, market, stop-limit, stop-market, OCO, bulk)
Best for	Quick conversions, price estimation	Advanced trading strategies, precise price control

Convert also serves as a price estimation tool. Call the estimate endpoint before placing a market order to preview the approximate execution price.

Conversion flow

The conversion flow has two steps: estimate and confirm.

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.

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.

Conversion quotes expire after 10 seconds. If the quote expires before confirmation, request a new estimate.

API endpoints

Convert uses 3 authenticated endpoints. All require HMAC-SHA512 signing.

Endpoint	Purpose	Rate limit
`POST /api/v4/convert/estimate`	Request a conversion quote	10,000 req / 10 sec
`POST /api/v4/convert/confirm`	Confirm and execute a quote	10,000 req / 10 sec
`POST /api/v4/convert/history`	Retrieve conversion history (max 6 months)	10,000 req / 10 sec

Estimate parameters

Parameter	Type	Required	Description
`from`	string	Yes	Source currency ticker (e.g., `BTC`)
`to`	string	Yes	Destination currency ticker (e.g., `USDT`)
`direction`	string	Yes	`"from"` = amount is in source currency; `"to"` = amount is in destination currency
`amount`	string	Yes	Amount to convert or receive

Code example

Estimate a BTC-to-USDT conversion and confirm the quote.

cURL
Python

# Step 1: Request a conversion estimate
curl -X POST https://whitebit.com/api/v4/convert/estimate \
  -H "X-TXC-APIKEY: YOUR_API_KEY" \
  -H "X-TXC-PAYLOAD: YOUR_PAYLOAD" \
  -H "X-TXC-SIGNATURE: YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "BTC",
    "to": "USDT",
    "direction": "from",
    "amount": "1",
    "request": "/api/v4/convert/estimate",
    "nonce": 1
  }'

{
  "id": "123",
  "from": "BTC",
  "to": "USDT",
  "give": "1",
  "receive": "34299.76831549",
  "rate": "34299.76831549",
  "expireAt": 1699016476
}

# Step 2: Confirm the quote using the id from the estimate response
curl -X POST https://whitebit.com/api/v4/convert/confirm \
  -H "X-TXC-APIKEY: YOUR_API_KEY" \
  -H "X-TXC-PAYLOAD: YOUR_PAYLOAD" \
  -H "X-TXC-SIGNATURE: YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": "123",
    "request": "/api/v4/convert/confirm",
    "nonce": 2
  }'

{
  "finalGive": "1",
  "finalReceive": "34299.76831549"
}

import time
import json
import hmac
import hashlib
import base64
import requests

API_KEY = "YOUR_API_KEY"
SECRET = "YOUR_SECRET"
BASE_URL = "https://whitebit.com"

def send_request(path, data):
    data["request"] = path
    data["nonce"] = int(time.time() * 1000)
    payload = base64.b64encode(json.dumps(data).encode())
    signature = hmac.new(
        SECRET.encode(), payload, hashlib.sha512
    ).hexdigest()
    headers = {
        "X-TXC-APIKEY": API_KEY,
        "X-TXC-PAYLOAD": payload.decode(),
        "X-TXC-SIGNATURE": signature,
        "Content-Type": "application/json",
    }
    return requests.post(BASE_URL + path, headers=headers, json=data)

# Step 1: Request a conversion estimate
estimate = send_request("/api/v4/convert/estimate", {
    "from": "BTC",
    "to": "USDT",
    "direction": "from",
    "amount": "1",
})
estimate_data = estimate.json()
print("Quote ID:", estimate_data["id"])
print("Rate:", estimate_data["rate"])

# Step 2: Confirm the quote
confirm = send_request("/api/v4/convert/confirm", {
    "quoteId": estimate_data["id"],
})
confirm_data = confirm.json()
print("Final give:", confirm_data["finalGive"])
print("Final receive:", confirm_data["finalReceive"])

For Go and PHP examples, see SDKs.

History filters

The history endpoint supports filtering by fromTicker, toTicker, quoteId, and time range (from/to timestamps). The default limit is 100 records. The maximum history depth is 6 months from the current month.

Convert in payment flows

Convert is commonly used as part of the withdrawal flow when the currency held in Main balance differs from the currency an end user needs to withdraw. The pattern is: transfer Main → Trade, convert, transfer Trade → Main, then withdraw. 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.

Integration Guides

Products

Platform Features

Core Concepts

Institutional & B2B

Best Practices

AI Hub

Resources

When to use Convert

Conversion flow

API endpoints

Estimate parameters

Code example

History filters

Convert in payment flows

What’s next

Payment Integration

Spot Trading

WhiteBIT Codes

Integration Guides

Products

Platform Features

Core Concepts

Institutional & B2B

Best Practices

AI Hub

Resources

​When to use Convert

​Conversion flow

​API endpoints

​Estimate parameters

​Code example

​History filters

​Convert in payment flows

​What’s next

Payment Integration

Spot Trading

WhiteBIT Codes

When to use Convert

Conversion flow

API endpoints

Estimate parameters

Code example

History filters

Convert in payment flows

What’s next