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.

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 instead.

Check current fees via Get Fees endpoint 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:

{
  "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.

⚠️ Provider Selection (Fiat)

Fiat withdrawals require the correct provider:

Check available providers via Asset Status endpoint
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 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:

{
  "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:

{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "ticker": ["The selected ticker is invalid."]
  }
}

KYC required:

{
  "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:

{
  "code": 5,
  "message": "Inner validation failed",
  "errors": {
    "amount": ["Not enough money, Ethereum balance = 1"]
  }
}

Security Recommendations

Always verify withdrawal requests:

Double-check the destination address
Verify the network (for multi-network currencies)
Confirm the amount and fee calculation
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)

Create withdraw request with specific amount (fee not included) - Alternative endpoint where fee is added on top
Get deposit/withdraw history - Monitor withdrawal status
Get fees - Check current withdrawal fees
Main balance - Check available balance before withdrawal
Asset Status endpoint - Verify currency can be withdrawn and get network/provider info

Authorizations

X-TXC-APIKEY

string

header

required

API key authentication using signed requests

Body

application/json

ticker

string

required

Currency's ticker. Example: BTC

⚠️ Currencies ticker must have "can_deposit" status equal to "true". Use Asset Status endpoint to know more about currency.

Example:

"ETH"

amount

string

required

Withdraw amount (including fee). To add the fee to the specified amount, use the /main-account/withdraw-pay request.

Example:

"0.9"

address

string

required

Target address (wallet address for cryptocurrencies, identifier/card token for fiat currencies)

Example:

"0x0964A6B8F794A4B8d61b62652dB27ddC9844FB4c"

uniqueId

string

required

Unique transaction identifier.

⚠️ Generate a new unique ID for each withdrawal request.

Example:

"24529041"

request

string

required

Request signature

nonce

string

required

Unique request identifier

memo

string

Memo.

⚠️ Required if currency is memoable.

provider

string

Fiat currency provider. Example: VISAMASTER

⚠️ Required for fiat currencies. Currency provider should be taken from Asset Status endpoint response.

network

string

Cryptocurrency network. Available for multi network currencies. Example: OMNI

⚠️ Currency network should be taken from Asset Status endpoint response. Default for USDT is ERC20

Example:

"ERC20"

partialEnable

boolean

Optional parameter for 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.

beneficiary

object

Beneficiary information data array.

⚠️ Required if currency ticker is one of: UAH_IBAN, USD_VISAMASTER, EUR_VISAMASTER, USD, EUR

Show child attributes

travelRule

object

Travel Rule information data array.

⚠️ Required if currency is crypto and the account is from EEA

Show child attributes

paymentDescription

string

Description of withdrawal destination

⚠️ Required if currency is crypto and withdrawal from whitebit-tr.com

Response

Validation succeeded and withdraw creation process is started. Check the request status by uniqueId in deposit/withdraw history.

Market Data

Spot Trading

Collateral Trading

Convert

Account & Wallet

Sub-Accounts

OAuth

Create withdraw request

Withdrawal Scenarios Guide

🔹 Cryptocurrency Withdrawals

Scenario 1: Simple Crypto Withdrawal

Scenario 2: Multi-Network Crypto (USDT, USDC)

Scenario 3: Travel Rule Compliance (EEA Users)

🔹 Fiat Withdrawals (KYC Required)

Scenario 4: Basic Fiat Withdrawal

Scenario 5: Fiat with Partial Enable

Scenario 6: IBAN Transfers (UAH_IBAN)

Scenario 7: International Fiat (USD/EUR VISAMASTER)

Amount and Fee Calculation

How it works:

Common Pitfalls & Best Practices

⚠️ Unique ID Management

⚠️ Address Validation

⚠️ Memo/Destination Tag

⚠️ Provider Selection (Fiat)

Workflow: Complete Withdrawal Process

Step 1: Pre-Withdrawal Checks

Step 2: Create Withdrawal

Step 3: Monitor Status

Network Selection Guide

Error Handling

Common validation errors (400):

Inner validation errors (422):

Security Recommendations

Authorizations

Body

Response

Market Data

Spot Trading

Collateral Trading

Convert

Account & Wallet

Sub-Accounts

OAuth

​Withdrawal Scenarios Guide

​🔹 Cryptocurrency Withdrawals

​Scenario 1: Simple Crypto Withdrawal

​Scenario 2: Multi-Network Crypto (USDT, USDC)

​Scenario 3: Travel Rule Compliance (EEA Users)

​🔹 Fiat Withdrawals (KYC Required)

​Scenario 4: Basic Fiat Withdrawal

​Scenario 5: Fiat with Partial Enable

​Scenario 6: IBAN Transfers (UAH_IBAN)

​Scenario 7: International Fiat (USD/EUR VISAMASTER)

​Amount and Fee Calculation

​How it works:

​Common Pitfalls & Best Practices

​⚠️ Unique ID Management

​⚠️ Address Validation

​⚠️ Memo/Destination Tag

​⚠️ Provider Selection (Fiat)

​Workflow: Complete Withdrawal Process

​Step 1: Pre-Withdrawal Checks

​Step 2: Create Withdrawal

​Step 3: Monitor Status

​Network Selection Guide

​Error Handling

​Common validation errors (400):

​Inner validation errors (422):

​Security Recommendations

​Related Endpoints

Authorizations

Body

Response

Withdrawal Scenarios Guide

🔹 Cryptocurrency Withdrawals

Scenario 1: Simple Crypto Withdrawal

Scenario 2: Multi-Network Crypto (USDT, USDC)

Scenario 3: Travel Rule Compliance (EEA Users)

🔹 Fiat Withdrawals (KYC Required)

Scenario 4: Basic Fiat Withdrawal

Scenario 5: Fiat with Partial Enable

Scenario 6: IBAN Transfers (UAH_IBAN)

Scenario 7: International Fiat (USD/EUR VISAMASTER)

Amount and Fee Calculation

How it works:

Common Pitfalls & Best Practices

⚠️ Unique ID Management

⚠️ Address Validation

⚠️ Memo/Destination Tag

⚠️ Provider Selection (Fiat)

Workflow: Complete Withdrawal Process

Step 1: Pre-Withdrawal Checks

Step 2: Create Withdrawal

Step 3: Monitor Status

Network Selection Guide

Error Handling

Common validation errors (400):

Inner validation errors (422):

Security Recommendations

Related Endpoints