> ## Documentation Index
> Fetch the complete documentation index at: https://whitebit-mintlify-fix-broken-links-1774051868.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Create withdraw request
## Withdrawal Scenarios Guide
The endpoint supports **8 different withdrawal scenarios**. Each scenario requires different fields depending on the currency type, destination, and regulatory requirements. Use the example selector above to switch between scenarios.
### 🔹 Cryptocurrency Withdrawals
#### **Scenario 1: Simple Crypto Withdrawal**
For standard cryptocurrencies like BTC, ETH, LTC, etc.
* **Required fields**: `ticker`, `amount`, `address`, `uniqueId`
* **Use when**: Withdrawing to a standard blockchain address
#### **Scenario 2: Multi-Network Crypto (USDT, USDC)**
For cryptocurrencies existing on multiple blockchains.
* **Required fields**: Same as above + `network`
* **Networks**: ERC20 (Ethereum), TRC20 (Tron), BEP20 (BSC), OMNI, etc.
* **Use when**: Withdrawing tokens existing on multiple chains
**Critical**: Ensure the `network` matches the destination address type. Sending ERC20 USDT to a TRC20 address will result in **permanent loss of funds**. Verify the network on [Asset Status endpoint](/api-reference/market-data/asset-status-list).
#### **Scenario 3: Travel Rule Compliance (EEA Users)**
Required for crypto withdrawals when the account is registered in the European Economic Area (EEA).
* **Required fields**: Standard crypto fields + `travelRule` object
* **Travel rule types**:
* `individual` - Personal withdrawals (requires first name / last name)
* `entity` - Business withdrawals (requires company name / address)
* **Use when**: The account is registered in EEA countries
### 🔹 Fiat Withdrawals (KYC Required)
All fiat withdrawals require KYC verification. Ensure the account is verified before attempting fiat withdrawals.
#### **Scenario 4: Basic Fiat Withdrawal**
Standard fiat withdrawal via VISAMASTER provider.
* **Required fields**: `ticker`, `amount`, `provider`, `uniqueId`
* **Currencies**: UAH, USD, EUR, etc.
* **Use when**: Standard fiat withdrawal within normal limits
#### **Scenario 5: Fiat with Partial Enable**
For withdrawals exceeding standard limits with "partially successful" status support.
* **Required fields**: Same as basic + `partialEnable: true` + `address` (encrypted card token)
* **Use when**: Withdrawing larger amounts eligible for partial processing
* **Important**: The application must handle "Partially successful" withdrawal status
#### **Scenario 6: IBAN Transfers (UAH\_IBAN)**
Bank transfer withdrawals to IBAN accounts.
* **Required fields**: Standard fields + `beneficiary` object with:
* `firstName`, `lastName` (max 40 symbols, latin letters)
* `tin` (Tax Identification Number, 10 digits)
* **Use when**: Withdrawing UAH to Ukrainian bank accounts via IBAN
#### **Scenario 7: International Fiat (USD/EUR VISAMASTER)**
Withdrawals with extended beneficiary information.
* **Required fields**: Standard fields + `beneficiary` object with:
* `firstName`, `lastName`, `phone`, `email`, `birthDate` (YYYY-MM-DD)
* **Use when**: Withdrawing USD or EUR via VISAMASTER\_PAYCORE provider
* **Currencies**: USD\_VISAMASTER, EUR\_VISAMASTER
***
## Amount and Fee Calculation
The `amount` field in the request **includes** the withdrawal fee. The recipient receives `amount - fee`.
### How it works:
**Example request** (`/withdraw`):
* Balance: 100 USDT
* Withdrawal fee: 2 USDT
* Request `amount: "100"`
* **Result**: 100 USDT deducted from balance, recipient receives **98 USDT**
**Alternative approach** (use `/withdraw-pay` instead):
* Balance: 100 USDT
* Withdrawal fee: 2 USDT
* Request `amount: "98"`
* **Result**: 102 USDT deducted from balance, recipient receives **98 USDT**
To specify the exact amount the recipient should receive (with fee added on top), use the [withdraw-pay endpoint](/api-reference/account-wallet/create-withdraw-request-with-specific-amount) instead.
Check current fees via [Get Fees endpoint](/api-reference/account-wallet/get-fees) before creating withdrawals.
***
## Common Pitfalls & Best Practices
### ⚠️ Unique ID Management
**Critical**: Generate a **NEW** `uniqueId` for each withdrawal request.
Reusing the same `uniqueId` will result in:
```json theme={null}
{
"code": 0,
"message": "Validation failed",
"errors": {
"uniqueId": ["The unique id has already been taken."]
}
}
```
**Best practice**: Use a timestamp-based or UUID generator:
* ✅ Good: `"24529041"`, `"withdrawal_1640995200_abc123"`
* ❌ Bad: Reusing `"12345"` for multiple withdrawals
### ⚠️ Address Validation
Different currencies have different address formats:
* **Bitcoin**: Starts with `1`, `3`, or `bc1` (SegWit)
* **Ethereum/ERC20**: Starts with `0x`, 42 characters
* **Tron/TRC20**: Starts with `T`, 34 characters
* **Fiat**: Card token or IBAN format
The platform validates addresses, but double-check addresses before sending.
### ⚠️ Memo/Destination Tag
Some currencies require a memo (destination tag):
* **XLM (Stellar)**: Requires memo
* **XRP (Ripple)**: Requires destination tag
* **EOS**: Requires memo
Missing a required memo will result in **permanent loss of funds** or significant delays in recovery. Check currency requirements on [Asset Status endpoint](/api-reference/market-data/asset-status-list).
### ⚠️ Provider Selection (Fiat)
Fiat withdrawals require the correct provider:
* Check available providers via [Asset Status endpoint](/api-reference/market-data/asset-status-list)
* Common providers: `VISAMASTER`, `VISAMASTER_PAYCORE`, `UAH_IBAN`
* Provider availability depends on currency and region
***
## Workflow: Complete Withdrawal Process
### Step 1: Pre-Withdrawal Checks
```
1. Check balance: GET /api/v4/main-account/balance
2. Get withdrawal fees: POST /api/v4/main-account/fee
3. Verify currency is withdrawable: GET /api/v4/public/assets
- Check "can_withdraw" status is "true"
- Get available networks/providers
- Check minimum/maximum amounts
```
### Step 2: Create Withdrawal
```
POST /api/v4/main-account/withdraw
```
**Success response**: `[]` (empty array)
Validation succeeded and the withdrawal process has started. The withdrawal is now queued for processing.
### Step 3: Monitor Status
```
POST /api/v4/main-account/history
```
Search by `uniqueId` to track the transaction.
**Withdrawal status codes**:
* **Successful**: 3, 7
* **Canceled**: 4, 9
* **Pending**: Other codes (see [history endpoint](/api-reference/account-wallet/get-deposit-withdraw-history) for full list)
Cryptocurrency withdrawals are typically processed within 15-60 minutes depending on network congestion. Fiat withdrawals may take 1-5 business days depending on the payment provider.
***
## Network Selection Guide
For multi-network currencies (USDT, USDC, etc.), choosing the right network is critical:
| Network | Speed | Fee | Use When |
| -------------------- | --------- | -------- | ------------------------------------ |
| **ERC20** (Ethereum) | Slow | High | Large amounts, highest security |
| **TRC20** (Tron) | Fast | Very Low | Small/medium amounts, fastest option |
| **BEP20** (BSC) | Fast | Low | Good balance of speed and cost |
| **OMNI** | Very Slow | High | Legacy, rarely used |
**Default network**: If the `network` parameter is omitted, the default network is used (typically ERC20 for USDT). Always specify the network explicitly to avoid confusion.
***
## Error Handling
### Common validation errors (400):
**Missing required fields**:
```json theme={null}
{
"code": 0,
"message": "Validation failed",
"errors": {
"address": ["The address field is required."],
"amount": ["The amount field is required."],
"ticker": ["The ticker field is required."],
"uniqueId": ["The unique id field is required."]
}
}
```
**Invalid ticker**:
```json theme={null}
{
"code": 0,
"message": "Validation failed",
"errors": {
"ticker": ["The selected ticker is invalid."]
}
}
```
**KYC required**:
```json theme={null}
{
"code": 0,
"message": "Validation failed",
"errors": {
"amount": [
"This currency has no active pairs or it may have been delisted.",
"Current limit exceeded"
]
}
}
```
### Inner validation errors (422):
**Error codes**:
* `1` - Currency is not withdrawable
* `2` - Specified address is invalid
* `3` - Amount is too small
* `4` - Amount is too small for the payment system
* `5` - Not enough balance
* `6` - Amount is less than or equals fee
* `7` - Amount should be integer (zero precision currencies like NEO)
* `8` - Target withdraw amount without fee equals zero
* `9` - Address is unavailable (withdrawal to own address blocked)
**Example**:
```json theme={null}
{
"code": 5,
"message": "Inner validation failed",
"errors": {
"amount": ["Not enough money, Ethereum balance = 1"]
}
}
```
***
## Security Recommendations
**Always verify withdrawal requests**:
1. Double-check the destination address
2. Verify the network (for multi-network currencies)
3. Confirm the amount and fee calculation
4. Test with a small amount first for new addresses
**Withdrawal safety checklist**:
* ✅ Address is correct and copied without errors
* ✅ Network matches the destination (ERC20, TRC20, etc.)
* ✅ Memo/tag included if required
* ✅ Amount is within the available balance minus fees
* ✅ Unique ID is newly generated
* ✅ Provider is correct (for fiat)
***
## Related Endpoints
* [Create withdraw request with specific amount (fee not included)](/api-reference/account-wallet/create-withdraw-request-with-specific-amount) - Alternative endpoint where fee is added on top
* [Get deposit/withdraw history](/api-reference/account-wallet/get-deposit-withdraw-history) - Monitor withdrawal status
* [Get fees](/api-reference/account-wallet/get-fees) - Check current withdrawal fees
* [Main balance](/api-reference/account-wallet/main-balance) - Check available balance before withdrawal
* [Asset Status endpoint](/api-reference/market-data/asset-status-list) - Verify currency can be withdrawn and get network/provider info
## OpenAPI
````yaml /openapi/private/main_api_v4.yaml POST /api/v4/main-account/withdraw
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: []
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/withdraw:
post:
tags:
- Withdraw
summary: Create withdraw request
description: |
The endpoint creates withdraw for the specified ticker.
Rate limit: 1000 requests/10 sec.
The API does not cache the response.
Also, fiat currencies can't be withdrawn without KYC verification.
operationId: createWithdraw
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- ticker
- amount
- address
- unique_id
- request
- nonce
properties:
ticker:
type: string
description: >
Currency's [ticker](/glossary#ticker). Example: BTC
⚠️ Currencies ticker must have "can_deposit" status equal to
"true". Use [Asset Status
endpoint](/public/http-v4/asset-status-list) to know more
about currency.
example: ETH
amount:
type: string
description: >
Withdraw amount (including [fee](/glossary#fee)). To add the
fee to the specified amount, use the
/main-account/withdraw-pay request.
example: '0.9'
address:
type: string
description: >-
Target address (wallet address for cryptocurrencies,
identifier/[card token](/glossary#card-token) for
[fiat](/glossary#fiat) currencies)
example: '0x0964A6B8F794A4B8d61b62652dB27ddC9844FB4c'
memo:
type: string
description: |
[Memo](/glossary#memodestination-tag).
⚠️ Required if currency is memoable.
example: '48565488244493'
unique_id:
type: string
description: |
Unique transaction identifier.
⚠️ Generate a new unique ID for each withdrawal request.
example: '24529041'
provider:
type: string
description: >
[Fiat](/glossary#fiat) currency
[provider](/glossary#provider). Example: VISAMASTER
⚠️ Required for fiat currencies. Currency provider should be
taken from [Asset Status
endpoint](/public/http-v4/asset-status-list) response.
example: VISAMASTER
network:
type: string
description: >
Cryptocurrency network. Available for multi network
currencies. Example: OMNI
⚠️ Currency network should be taken from [Asset Status
endpoint](/public/http-v4/asset-status-list) response.
Default for USDT is ERC20
example: ERC20
partialEnable:
type: boolean
description: >-
Optional parameter for [FIAT](/glossary#fiat) withdrawals
with increased Maximum Limit if set as "true". To use this
parameter, the application must support "Partially
successful" withdrawal status and latest updates in
deposit/withdrawal history.
example: false
beneficiary:
type: object
description: >
Beneficiary information data array.
⚠️ Required if currency [ticker](/glossary#ticker) is one
of: UAH_IBAN, USD_VISAMASTER, EUR_VISAMASTER, USD, EUR
properties:
firstName:
type: string
description: >
Beneficiary first name. Max length: 40 symbols, latin
letters and special characters.
⚠️ Required if currency [ticker](/glossary#ticker) is
one of: UAH_IBAN, USD_VISAMASTER, USD, EUR
example: Firstname
lastName:
type: string
description: >
Beneficiary last name. Max length: 40 symbols, latin
letters and special characters.
⚠️ Required if currency [ticker](/glossary#ticker) is
one of: UAH_IBAN, USD_VISAMASTER, USD, EUR
example: Lastname
tin:
type: integer
description: |
Beneficiary TAX payer number. Integer, 10 digits.
⚠️ Required if currency is UAH_IBAN.
example: 1000000000
phone:
type: string
description: >
Beneficiary phone number.
⚠️ Required if currency [ticker](/glossary#ticker) is
one of: USD_VISAMASTER, EUR_VISAMASTER
example: '1234567891'
email:
type: string
description: >
Beneficiary email.
⚠️ Required if currency [ticker](/glossary#ticker) is
one of: USD_VISAMASTER, EUR_VISAMASTER
example: john_doe@email.com
birthDate:
type: string
format: date
description: >
Beneficiary birth date. Format: YYYY-MM-DD.
⚠️ Required if currency [ticker](/glossary#ticker) is
one of: USD_VISAMASTER, EUR_VISAMASTER
example: '1990-01-01'
travelRule:
type: object
description: >
Travel Rule information data array.
⚠️ Required if currency is crypto and the account is from
[EEA](/glossary#european-economic-area-eea)
properties:
type:
type: string
enum:
- individual
- entity
description: >
Travel rule receiver type. Values: "individual" or
"entity"
⚠️ Required if currency is crypto and the account is
from [EEA](/glossary#european-economic-area-eea)
example: individual
vasp:
type: string
description: >
Travel rule destination platform (VASP) name.
⚠️ Required if currency is crypto and the account is
from [EEA](/glossary#european-economic-area-eea)
example: Binance
name:
type: string
description: >
Travel rule. If individual - first_name ; if entity -
entity_name
⚠️ Required if currency is crypto and the account is
from [EEA](/glossary#european-economic-area-eea)
example: John
address:
type: string
description: >
Travel rule. If individual - last_name ; if entity -
entity_address
⚠️ Required if currency is crypto and the account is
from [EEA](/glossary#european-economic-area-eea)
example: 123 Business Street, London, UK
paymentDescription:
type: string
description: >
Description of withdrawal destination
⚠️ Required if currency is crypto and withdrawal from
whitebit-tr.com
example: Payment description
request:
type: string
description: Request signature
example: '{{request}}'
nonce:
type: string
description: Unique request identifier
example: '{{nonce}}'
examples:
crypto:
summary: Crypto withdrawal
value:
ticker: ETH
amount: '0.9'
address: '0x0964A6B8F794A4B8d61b62652dB27ddC9844FB4c'
unique_id: '24529041'
request: '{{request}}'
nonce: '{{nonce}}'
multiNetwork:
summary: Multinetwork currency (USDT)
value:
ticker: USDT
amount: '0.9'
address: '0x0964A6B8F794A4B8d61b62652dB27ddC9844FB4c'
unique_id: '24529042'
network: ERC20
request: '{{request}}'
nonce: '{{nonce}}'
fiat:
summary: Fiat withdrawal
value:
ticker: UAH
amount: '100'
provider: VISAMASTER
unique_id: '24529043'
request: '{{request}}'
nonce: '{{nonce}}'
fiatPartial:
summary: Fiat with partial enable
value:
ticker: UAH
amount: '50000'
address: t6XIpyirkiLP+I++XHWfSeGrn5p38g==
provider: VISAMASTER_PAYCORE
partialEnable: true
unique_id: '24529045'
request: '{{request}}'
nonce: '{{nonce}}'
fiatIban:
summary: Fiat IBAN currency
value:
ticker: UAH
amount: '50000'
address: UA213223130000026007233566001
beneficiary:
firstName: Firstname
lastName: Lastname
tin: 1000000000
provider: UAH_IBAN
unique_id: '24529045'
request: '{{request}}'
nonce: '{{nonce}}'
fiatVisamaster:
summary: Fiat USD/EUR VISAMASTER
value:
ticker: USD
amount: '30000'
address: t6XIpyirkiLP+I++XHWfSeGrn5p38g==
beneficiary:
firstName: Firstname
lastName: Lastname
phone: '1234567891'
email: john_doe@email.com
provider: USD_VISAMASTER
unique_id: '24529045'
request: '{{request}}'
nonce: '{{nonce}}'
travelRuleIndividual:
summary: Travel rule (individual)
value:
ticker: BTC
amount: '0.5'
address: bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh
unique_id: '24529046'
travelRule:
type: individual
vasp: Binance
name: John
address: 123 Business Street, London, UK
request: '{{request}}'
nonce: '{{nonce}}'
travelRuleEntity:
summary: Travel rule (entity)
value:
ticker: BTC
amount: '1.2'
address: bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh
unique_id: '24529047'
travelRule:
type: entity
vasp: Kraken
name: Acme Corp
address: 123 Business Street, London, UK
request: '{{request}}'
nonce: '{{nonce}}'
responses:
'201':
description: >-
Validation succeeded and withdraw creation process is started. Check
the request status by uniqueId in deposit/withdraw history.
content:
application/json:
schema:
type: array
items: {}
description: Empty array indicates success
example: []
'400':
description: >
Request validation failed
Response error codes:
- 1 - currency is not withdrawable
- 2 - specified address is invalid
- 3 - amount is too small
- 4 - amount is too small for the payment system
- 5 - not enough balance
- 6 - amount is less than or equals [fee](/glossary#fee)
- 7 - amount should be integer (can happen for currencies with zero
[precision](/glossary#precision) like Neo)
- 8 - target withdraw amount without [fee](/glossary#fee) equals
zero
- 9 - address is unavailable (occurs for withdraws to own address)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
missingFields:
summary: Missing required fields
value:
code: 0
message: Validation failed
errors:
address:
- The address field is required.
amount:
- The amount field is required.
ticker:
- The ticker field is required.
unique_id:
- The unique id field is required.
duplicateUniqueId:
summary: Duplicate uniqueId
value:
code: 0
message: Validation failed
errors:
unique_id:
- The unique id has already been taken.
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
invalidTicker:
summary: Invalid ticker
value:
code: 0
message: Validation failed
errors:
ticker:
- The selected ticker is invalid.
providerRequired:
summary: Provider required for fiat currency
value:
code: 0
message: Validation failed
errors:
provider:
- Provider is required for fiat currency
memoRequired:
summary: Memo required for memoable currency
value:
code: 0
message: Validation failed
errors:
memo:
- The memo field is required.
invalidPartialEnable:
summary: Invalid partialEnable value
value:
code: 0
message: Validation failed
errors:
partialEnable:
- The partial enable field must be true or false.
throttling:
summary: Rate limiting/throttling
value:
message: Too Many Attempts.
code: 0
'422':
description: >
Inner validation failed
Response error codes:
- 1 - currency is not withdrawable
- 2 - specified address is invalid
- 3 - amount is too small
- 4 - amount is too small for the payment system
- 5 - not enough balance
- 6 - amount is less than or equals [fee](/glossary#fee)
- 7 - amount should be integer (can happen for currencies with zero
[precision](/glossary#precision) like Neo)
- 8 - target withdraw amount without [fee](/glossary#fee) equals
zero
- 9 - address is unavailable (occurs for withdraws to own address)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInner'
examples:
invalidAddress:
summary: Invalid address
value:
code: 2
message: Inner validation failed
errors:
address:
- The address is invalid
notEnoughBalance:
summary: Not enough balance
value:
code: 5
message: Inner validation failed
errors:
amount:
- Not enough money, Ethereum balance = 1
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: API key authentication using signed requests
````