Create withdraw request

​

Withdrawal Scenarios Guide

​

🔹 Cryptocurrency Withdrawals

​

Scenario 1: Simple Crypto Withdrawal

• Required fields: ticker, amount, address, uniqueId
• Use when: Withdrawing to a standard blockchain address

​

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

• Required fields: Same as above + network
• Networks: ERC20 (Ethereum), TRC20 (Tron), BEP20 (BSC), OMNI, etc.
• Use when: Withdrawing tokens existing on multiple chains

​

Scenario 3: Travel Rule Compliance (EEA Users)

• 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)

​

Scenario 4: Basic Fiat Withdrawal

• 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

• 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)

• 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)

• 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

​

How it works:

• Balance: 100 USDT
• Withdrawal fee: 2 USDT
• Request amount: "100"
• Result: 100 USDT deducted from balance, recipient receives 98 USDT

• Balance: 100 USDT
• Withdrawal fee: 2 USDT
• Request amount: "98"
• Result: 102 USDT deducted from balance, recipient receives 98 USDT

​

Common Pitfalls & Best Practices

​

⚠️ Unique ID Management

{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "uniqueId": ["The unique id has already been taken."]
  }
}

• ✅ Good: "24529041", "withdrawal_1640995200_abc123"
• ❌ Bad: Reusing "12345" for multiple withdrawals

​

⚠️ Address Validation

• 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

​

⚠️ Memo/Destination Tag

• XLM (Stellar): Requires memo
• XRP (Ripple): Requires destination tag
• EOS: Requires memo

​

⚠️ Provider Selection (Fiat)

• 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

​

Step 3: Monitor Status

POST /api/v4/main-account/history

• Successful: 3, 7
• Canceled: 4, 9
• Pending: Other codes (see history endpoint for full list)

​

Network Selection Guide

​

Error Handling

​

Common validation errors (400):

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

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

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

• 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)

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

​

Security Recommendations

​

Related Endpoints

• 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