> ## 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.
# Transfer between balances
> Transfer funds between main, trade, and collateral balances on WhiteBIT via the V4 API.
## OpenAPI
````yaml /openapi/private/main_api_v4.yaml POST /api/v4/main-account/transfer
openapi: 3.0.3
info:
title: WhiteBIT Private HTTP API V4
description: |
WhiteBIT Private HTTP API V4 for Main balance changes.
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.
version: 4.0.0
contact:
name: WhiteBIT Support
email: support@whitebit.com
url: https://whitebit.com
servers:
- url: https://whitebit.com
description: WhiteBIT Global Server
- url: https://whitebit.eu
description: WhiteBIT EU Server
security:
- ApiKeyAuth: []
PayloadAuth: []
SignatureAuth: []
tags:
- name: Main Account
description: Main account balance and operations
- name: Deposit
description: Cryptocurrency and fiat deposit operations
- name: Withdraw
description: Cryptocurrency and fiat withdrawal operations
- name: Transfer
description: Balance transfer operations
- name: Codes
description: WhiteBIT codes operations
- name: Crypto Lending - Fixed
description: Fixed crypto lending plans
- name: Crypto Lending - Flex
description: Flexible crypto lending plans
- name: Fees
description: Fee information
- name: Sub-Account
description: Sub-account management
- name: Sub-Account API Keys
description: Sub-account API key management
- name: Mining Pool
description: Mining pool operations
- name: Credit Line
description: Credit line information
- name: JWT
description: JWT token management
paths:
/api/v4/main-account/transfer:
post:
tags:
- Transfer
summary: Transfer between balances
description: >
The endpoint transfers the specified amount between
[main](/glossary#balance-main),
[trade](/glossary#balance-spotbalance-trade) and
[collateral](/glossary#balance-collateral) balances.
Rate limit: 1000 requests/10 sec.
The API does not cache the response.
Also, fiat currencies can't be transferred without KYC verification.
operationId: transferBetweenBalances
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- ticker
- amount
- request
- nonce
properties:
method:
type: string
description: >
Transfer method.
⚠️ We highly recommend to use **from** and **to** fields,
which provides more flexibility. This way will be deprecated
in future.
Example: **deposit** to transfer from
[main](/glossary#balance-main) to
[trade](/glossary#balance-spotbalance-trade) / **withdraw**
to transfer from
[trade](/glossary#balance-spotbalance-trade) balance to
[main](/glossary#balance-main). For [collateral
balances](/glossary#balance-collateral) use
**collateral-deposit** to transfer from main to collateral
and **collateral-withdraw** to transfer from collateral to
main
**Not required** if **from** and **to** are set.
enum:
- deposit
- withdraw
- collateral-deposit
- collateral-withdraw
example: deposit
from:
type: string
description: >
Balance FROM which funds will move to. Acceptable values:
[**main**](/glossary#balance-main),
[**spot**](/glossary#balance-spotbalance-trade),
[**collateral**](/glossary#balance-collateral)
**Not required** if **method** is set.
enum:
- main
- spot
- collateral
example: main
to:
type: string
description: >
Balance TO which funds will move to. Acceptable values:
[**main**](/glossary#balance-main),
[**spot**](/glossary#balance-spotbalance-trade),
[**collateral**](/glossary#balance-collateral)
**Not required** if **method** is set.
enum:
- main
- spot
- collateral
example: spot
ticker:
type: string
description: 'Currency''s [ticker](/glossary#ticker). Example: BTC'
example: XLM
amount:
type: string
description: >-
Amount to transfer. Max [precision](/glossary#precision) =
8, value must be greater than zero and less than or equal to
the available balance.
example: '0.9'
request:
type: string
description: Request signature
example: '{{request}}'
nonce:
type: integer
description: Unique request identifier
example: 1594297865000
examples:
usingMethod:
summary: Using method field (deprecated)
value:
ticker: XLM
amount: '0.9'
method: deposit
request: '{{request}}'
nonce: 1594297865000
usingFromTo:
summary: Using from/to fields (recommended)
value:
ticker: XLM
amount: '0.9'
from: main
to: spot
request: '{{request}}'
nonce: 1594297865000
responses:
'201':
description: All validations succeeded and creating transaction is started
content:
application/json:
schema:
type: array
items: {}
description: Empty array indicates success
example: []
'400':
description: Request validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
missingFields:
summary: Missing required fields
value:
code: 0
message: Validation failed
errors:
amount:
- The amount field is required.
method:
- The method field is required.
ticker:
- The ticker field is required.
invalidTicker:
summary: Invalid ticker
value:
code: 0
message: Validation failed
errors:
ticker:
- The selected ticker is invalid.
unconfirmedUser:
summary: Unconfirmed user (without KYC)
value:
code: 0
message: Validation failed
errors:
amount:
- >-
This currency has no active pairs or it may have been
delisted. Its rate cannot be calculated at the moment.
- Current limit exceeded
accountVerification:
summary: Account must be verified for fiat currencies
value:
code: 0
message: Validation failed
errors:
amount:
- Your account must be verified
invalidMethod:
summary: Invalid method
value:
code: 0
message: Validation failed
errors:
method:
- The selected method is invalid.
invalidFromTo:
summary: Invalid from/to balance type
value:
code: 0
message: Validation failed
errors:
from:
- The selected from is invalid.
to:
- The selected to is invalid.
sameFromTo:
summary: Source and destination balance are the same
value:
code: 0
message: Validation failed
errors:
to:
- The to and from must be different.
amountTooSmall:
summary: Amount too small
value:
code: 0
message: Validation failed
errors:
amount:
- The amount must be at least 0.00000001.
invalidAmount:
summary: Invalid amount format
value:
code: 0
message: Validation failed
errors:
amount:
- The amount must be a number.
- Invalid number
throttling:
summary: Rate limiting/throttling
value:
message: Too Many Attempts.
code: 0
'422':
description: >
Inner validation failed
Response error codes:
- 1 - transfers from [trade](/glossary#balance-spotbalance-trade) to
[main](/glossary#balance-main) are disabled, or withdraw of this
currency is disabled
- 2 - transfers from [main](/glossary#balance-main) to
[trade](/glossary#balance-spotbalance-trade) are disabled, or
deposit of this currency is disabled
- 3 - not enough balance
Additional account-state outcomes are returned here with `code: 0`
(the message is
localized — match on the condition, not the exact string):
- **Collateral transfer unavailable** — the
[collateral](/glossary#balance-collateral)
(margin) feature is not available to this account; on field `error`, e.g.
`Unavailable for legal reasons`.
- **Operation not permitted for a sub-account** — on field `error`,
e.g.
`Not permitted for sub-account`.
- **Maximum collateral balance exceeded** — the transfer would push
the
[collateral balance](/glossary#balance-collateral) past its cap; on field `form`.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInner'
examples:
notEnoughBalance:
summary: Not enough balance
value:
code: 3
message: Inner validation failed
errors:
amount:
- >-
You don't have such amount for transfer (available
34.68, in amount: 1000000)
currencyWithdrawDisabled:
summary: Withdraw of this currency is disabled
value:
code: 1
message: Inner validation failed
errors:
currency:
- Withdraw from this currency is disabled
currencyDepositDisabled:
summary: Deposit to this currency is disabled
value:
code: 2
message: Inner validation failed
errors:
currency:
- Deposit to this currency is disabled
components:
schemas:
Error:
type: object
properties:
code:
type: integer
message:
type: string
errors:
type: object
additionalProperties:
type: array
items:
type: string
ErrorInner:
type: object
properties:
code:
type: integer
message:
type: string
errors:
type: object
additionalProperties:
type: array
items:
type: string
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)).
````