> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whitebit.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Convert Estimate
> Get a price estimate for converting between two currencies on WhiteBIT via the V4 API.
## OpenAPI
````yaml /openapi/private/http-trade-v4.yaml POST /api/v4/convert/estimate
openapi: 3.0.3
info:
title: Private HTTP API V4 - Collateral Trading
description: |
WhiteBIT Private HTTP API V4 for collateral/margin trading operations.
Base URL: https://whitebit.com
All endpoints return time in Unix-time format.
All endpoints return either a JSON object or array.
For receiving responses from API calls please use http method POST.
Authentication required for all endpoints.
version: 4.0.0
license:
name: WhiteBIT Terms of Service
url: https://whitebit.com/terms
servers:
- url: https://whitebit.com
description: WhiteBIT Global Server
- url: https://whitebit.eu
description: WhiteBIT EU Server
security:
- ApiKeyAuth: []
PayloadAuth: []
SignatureAuth: []
tags:
- name: Collateral Trading
description: Endpoints for collateral/margin trading operations
- name: Spot Trading
description: Endpoints for spot trading operations
- name: Market Fee
description: Endpoints for querying trading fees
paths:
/api/v4/convert/estimate:
post:
summary: Convert Estimate
description: >
The endpoint creates a quote for converting one currency to another.
Quote lifetime is 10 seconds, then quote will be expired.
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. Account balance is
pre-checked at estimate time and re-checked at confirm time, because
balance can change within the 10-second quote window. There is an
absolute server-side maximum on the conversion amount.
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.
Error `message` values may be returned as translation keys (for example
`validation.required`) rather than finalized English strings. Treat the
`code` and the field name under `errors` as the stable contract.
Rate limit: 10000 requests/10 sec.
operationId: convertEstimate
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- from
- to
- direction
- amount
properties:
from:
type: string
description: 'From currency. Example: BTC'
example: BTC
to:
type: string
description: 'To currency. Example: USDT'
example: USDT
direction:
type: string
description: >-
Convert amount direction, defines in which currency
corresponding "amount" field is populated. Use "to" in case
amount is in "to" currency, use "from" if amount is in
"from" currency
enum:
- from
- to
example: to
amount:
type: string
description: >-
Amount to convert or receive. The value is silently
truncated to 8 decimal places before evaluation; excess
decimals do not raise an error.
example: 35,103.1
nonce:
type: integer
description: Nonce for request
example: 1699260637
request:
type: string
description: Request path
example: '{{request}}'
examples:
estimateReceive:
summary: Estimate convert of BTC to receive 35,103.1 USDT
value:
amount: 35,103.1
direction: to
from: BTC
to: USDT
estimateGive:
summary: Estimate convert of 1 BTC to USDT
value:
amount: '1'
direction: from
from: BTC
to: USDT
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Quote ID
example: '123'
from:
type: string
description: From currency
example: BTC
to:
type: string
description: To currency
example: USDT
give:
type: string
description: Amount to give
example: '50'
receive:
type: string
description: Amount to receive
example: '1714988.41577452'
rate:
type: string
description: >-
Conversion rate expressed in the from→to direction: units
of the 'to' currency received per one unit of the 'from'
currency. Example: if from=BTC and to=USDT, a rate of
"34299.76" means 1 BTC is worth approximately 34 299.76
USDT at the time of the quote.
example: '34299.76831549'
expireAt:
type: integer
description: Quote expiration timestamp
example: 1699016476
'400':
description: Inner validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
amountTooBig:
summary: Amount Above Maximum
value:
code: 32
message: Validation failed
errors:
amount:
- frontendServerSide.converter.amountIsTooBig
insufficientBalance:
summary: Insufficient Balance
value:
code: 37
message: Validation failed
errors:
amount:
- validation.balance
'422':
description: Validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
termsNotAccepted:
summary: Terms Not Accepted
value:
code: 0
message: Validation failed
errors:
user:
- Terms of exchange are not accepted
directionInvalid:
summary: Direction Invalid
value:
code: 30
message: Validation failed
errors:
direction:
- Direction field does not exist in [from,to].
marketsNotAvailable:
summary: Markets Not Available
value:
code: 0
message: Validation failed
errors:
from:
- Conversion markets not available
amountTooSmall:
summary: Amount Below Minimum
value:
code: 0
message: Validation failed
errors:
amount:
- validation.amount_too_small
missingRequiredField:
summary: Missing Required Field
value:
code: 30
message: Validation failed
errors:
amount:
- validation.required
security:
- ApiKeyAuth: []
PayloadAuth: []
SignatureAuth: []
components:
schemas:
ErrorResponse:
type: object
properties:
code:
type: integer
description: Error code
example: 30
message:
type: string
description: Error message
example: Validation failed
errors:
type: object
additionalProperties:
type: array
items:
type: string
description: Detailed error information
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-TXC-APIKEY
description: The public WhiteBIT API key.
PayloadAuth:
type: apiKey
in: header
name: X-TXC-PAYLOAD
description: Base64-encoded JSON request body.
SignatureAuth:
type: apiKey
in: header
name: X-TXC-SIGNATURE
description: >-
HMAC-SHA512 signature of the payload, hex-encoded. Computed as
hex(HMAC-SHA512(payload, api_secret)).
````