Create Withdrawal

POST

/withdrawal/

Create a cryptocurrency withdrawal request to send funds from your merchant balance to an external address.

Authentication

Requires OAuth 2.0 authentication with read and write scopes.

Request Body

Parameter	Type	Required	Description
`amount`	decimal	Conditional	Crypto amount to withdraw. Either `amount` or `price_amount` is required, but not both
`price_amount`	decimal	Conditional	Fiat amount for conversion. Either `amount` or `price_amount` is required, but not both
`price_currency`	string	No	Fiat currency for `price_amount` conversion. Default: `"USD"`
`final_amount`	boolean	No	If `true`, `amount` is what the recipient receives (fee deducted separately). Default: `false`
`address`	string	Yes	Destination wallet address. Max 255 characters
`currency`	string	Conditional	Combined currency code (e.g., `"USDTTRC20"`, `"USDTERC20"`). Either `currency` or `blockchain` + `token` must be provided
`blockchain`	string	Conditional	Blockchain network (e.g., `"TRON"`, `"ETH"`). Use with `token` instead of `currency`
`token`	string	Conditional	Token symbol (e.g., `"USDT"`). Use with `blockchain` instead of `currency`
`memo`	string	No	Memo or tag for the transaction. Max 255 characters. Required for some blockchains (e.g., XRP, XLM)
`custom_id`	string	No	Your internal reference ID. Max 64 characters
`callback_url`	URL	No	URL for webhook notifications about withdrawal status
`account_id`	string	No	Wallet account ID. Max 255 characters. If not provided, uses default wallet

Currency Specification

You can specify the withdrawal currency in two ways:

Single currency field: Use a combined code like "USDTTRC20"
blockchain + token: Use separate fields, e.g., "blockchain": "TRON" and "token": "USDT"

Example Request

curl -X POST {{BASE_URL}}/withdrawal/ \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100.00",
    "currency": "USDTTRC20",
    "address": "TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL",
    "custom_id": "WITHDRAW-12345",
    "callback_url": "https://your-site.com/webhook/withdrawal"
  }'

Using blockchain + token

curl -X POST {{BASE_URL}}/withdrawal/ \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100.00",
    "blockchain": "TRON",
    "token": "USDT",
    "address": "TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL",
    "custom_id": "WITHDRAW-12345"
  }'

Using price_amount (fiat conversion)

curl -X POST {{BASE_URL}}/withdrawal/ \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "price_amount": "50.00",
    "price_currency": "USD",
    "currency": "USDTTRC20",
    "address": "TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL"
  }'

Response

Success Response (201 Created)

{
  "withdrawal_id": "660e8400-e29b-41d4-a716-446655440000",
  "custom_id": "WITHDRAW-12345",
  "amount": "100.00000000",
  "requested_amount": "100.00000000",
  "fee": "1.50000000",
  "platform_fee": "1.00000000",
  "network_fee": "0.50000000",
  "blockchain": "TRX",
  "token": "USDT",
  "currency": "USDTTRC20",
  "address": "TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL",
  "memo": null,
  "status": "pending",
  "transaction_hash": null,
  "confirmations": 0,
  "required_confirmations": 20,
  "batch_id": null,
  "callback_url": "https://your-site.com/webhook/withdrawal",
  "created_at": "2025-01-15T12:00:00Z",
  "updated_at": "2025-01-15T12:00:00Z",
  "completed_at": null
}

Response Fields

Field	Type	Description
`withdrawal_id`	string	Unique withdrawal identifier
`custom_id`	string	Your custom reference ID, if provided
`amount`	string	Withdrawal amount (what recipient receives)
`requested_amount`	string	Originally requested amount
`fee`	string	Total fee (platform + network)
`platform_fee`	string	Platform processing fee
`network_fee`	string	Blockchain network fee
`blockchain`	string	Blockchain network used
`token`	string	Token being withdrawn
`currency`	string	Combined currency code
`address`	string	Destination wallet address
`memo`	string	Memo or tag, if provided
`status`	string	Current withdrawal status
`transaction_hash`	string	Blockchain transaction hash (null until processed)
`confirmations`	integer	Number of blockchain confirmations
`required_confirmations`	integer	Required confirmations for completion
`batch_id`	string	Withdrawal batch ID, if part of a batch
`callback_url`	string	Webhook callback URL
`created_at`	string	ISO 8601 timestamp of creation
`updated_at`	string	ISO 8601 timestamp of last update
`completed_at`	string	ISO 8601 timestamp of completion (null until completed)

Error Responses

400 Bad Request - Invalid Address

{
  "error": {
    "code": "invalid_address",
    "message": "Invalid address format",
    "details": {
      "address": "invalid_address"
    }
  }
}

400 Bad Request - Insufficient Balance

{
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient balance for withdrawal",
    "details": {
      "available": "50.00",
      "requested": "100.00",
      "currency": "USDTTRC20"
    }
  }
}

400 Bad Request - Amount Conflict

{
  "error": {
    "code": "invalid_request",
    "message": "Provide either amount or price_amount, not both",
    "details": {}
  }
}

Withdrawal Status Values

Status	Description
`pending`	Withdrawal created, awaiting processing
`processing`	Being processed by the system
`completed`	Successfully sent to blockchain
`failed`	Withdrawal failed; funds returned to balance
`cancelled`	Cancelled; funds returned to balance

Fee Structure

Withdrawals incur two types of fees:

Network Fee: Variable blockchain gas fee (changes based on network congestion)
Platform Fee: Platform processing fee

Important Notes

Provide either amount (crypto) or price_amount (fiat), not both
Provide either currency or blockchain + token, not both
When final_amount is true, the specified amount is what the recipient gets; fees are added on top
Network fees are estimated and may vary slightly
Always verify the destination address - transactions cannot be reversed
Implement webhook handlers for real-time status updates