Create Withdrawal

POST

/withdrawal/

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

Authentication

Requires OAuth 2.0 authentication with read and write scopes.

Request Body

Parameter	Type	Required	Description
amount	decimal	Yes	Amount to withdraw in the specified currency
currency	string	Yes	Currency code (e.g., "USDTERC20", "USDCERC20", "DAIERC20")
address	string	Yes	Destination EVM address (0x format, 42 characters)
account_id	uuid	No	Source wallet ID. If not provided, uses default wallet
custom_id	string	No	Your internal reference ID. Max 64 characters
callback_url	string	No	URL for webhook notifications about withdrawal status

Example Request

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

Response

Success Response (201 Created)

{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "amount": "100.00",
  "currency": "USDTERC20",
  "address": "0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE",
  "blockchain": "ETH",
  "token": "USDT",
  "network_fee": "3.50",
  "transaction_fee": "1.00",
  "total_fee": "4.50",
  "total_deducted": "104.50",
  "transaction_hash": null,
  "custom_id": "WITHDRAW-12345",
  "callback_url": "https://your-site.com/webhook/withdrawal",
  "account_id": null,
  "created_at": "2025-01-15T12:00:00Z",
  "updated_at": "2025-01-15T12:00:00Z"
}

Response Fields

Field	Type	Description
id	uuid	Unique withdrawal identifier
status	string	Current withdrawal status
amount	string	Withdrawal amount (what recipient receives)
network_fee	string	Blockchain network fee
transaction_fee	string	Platform processing fee
total_deducted	string	Total amount deducted from balance
transaction_hash	string	Blockchain transaction hash (null until processed)

Error Responses

400 Bad Request - Invalid Address

{
  "error": {
    "code": "invalid_address",
    "message": "Invalid EVM address format",
    "details": {
      "address": "0xinvalid",
      "expected_format": "0x followed by 40 hexadecimal characters"
    }
  }
}

400 Bad Request - Insufficient Balance

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

422 Unprocessable Entity - Below Minimum

{
  "error": {
    "code": "below_minimum",
    "message": "Withdrawal amount below minimum",
    "details": {
      "minimum": "10.00",
      "requested": "5.00",
      "currency": "USDTERC20"
    }
  }
}

Withdrawal Status Values

Status	Description	Next Steps
pending	Withdrawal created, awaiting processing	Will be processed in next batch
processing	Being processed by the system	Transaction will be broadcast soon
completed	Successfully sent to blockchain	Check transaction hash for confirmation
failed	Withdrawal failed	Funds returned to balance, check error
cancelled	Cancelled by user	Funds returned to balance

Fee Structure

Withdrawals incur two types of fees:

1. Network Fee: Variable blockchain gas fee (changes based on network congestion)
2. Transaction Fee: Fixed platform processing fee (1% or minimum amount)

Example Fee Calculation

Withdrawal Amount: 100.00 USDT
Network Fee: 3.50 USDT (current gas price)
Transaction Fee: 1.00 USDT (1%)
Total Fees: 4.50 USDT
Total Deducted: 104.50 USDT

Address Validation

EVM addresses must:

• Start with "0x"
• Be exactly 42 characters long
• Contain only hexadecimal characters (0-9, a-f, A-F)
• Pass checksum validation (mixed case)

Valid Address Examples

0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE  ✓ Checksummed
0x95ad61b0a150d79219dcf64e1e6cc01f0b64c4ce  ✓ Lowercase
0x0000000000000000000000000000000000000000  ✓ Null address (warning)

Minimum Withdrawal Amounts

Currency	Minimum Amount	Network
USDTERC20	10.00	Ethereum
USDCERC20	10.00	Ethereum
DAIERC20	10.00	Ethereum

Processing Times

• Pending → Processing: Usually within 5 minutes
• Processing → Completed: 1-5 minutes after broadcast
• Blockchain Confirmations: Varies by network (Ethereum ~12 confirmations)

Important Notes

• Withdrawals are processed in batches for efficiency
• Network fees are estimated and may vary slightly
• Always verify the destination address - transactions cannot be reversed
• The null address (0x000...000) will trigger a warning
• Contract addresses are supported but use at your own risk
• Implement webhook handlers for real-time status updates

Code Examples

JavaScript

async function createWithdrawal(amount, address) {
  const withdrawal = {
    amount: amount,
    currency: 'USDTERC20',
    address: address,
    custom_id: `WITHDRAW-${Date.now()}`,
    callback_url: 'https://your-site.com/webhook/withdrawal'
  };

  const response = await fetch('https://api.cryptofuse.io/withdrawal/', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(withdrawal)
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error.message);
  }

  const result = await response.json();
  console.log(`Withdrawal created: ${result.id}`);
  console.log(`Total deducted: ${result.total_deducted} ${result.currency}`);
  
  return result;
}

Python

import requests
from decimal import Decimal

def create_withdrawal(amount: Decimal, address: str, currency: str = "USDTERC20"):
    """Create a withdrawal request."""
    
    withdrawal_data = {
        "amount": str(amount),
        "currency": currency,
        "address": address,
        "custom_id": f"WITHDRAW-{int(time.time())}",
        "callback_url": "https://your-site.com/webhook/withdrawal"
    }
    
    response = requests.post(
        "https://api.cryptofuse.io/withdrawal/",
        json=withdrawal_data,
        headers={
            "Authorization": f"Bearer {access_token}",
            "Content-Type": "application/json"
        }
    )
    
    if response.status_code == 201:
        result = response.json()
        print(f"Withdrawal {result['id']} created")
        print(f"Amount: {result['amount']} {result['currency']}")
        print(f"Fees: {result['total_fee']} {result['currency']}")
        print(f"Total deducted: {result['total_deducted']} {result['currency']}")
        return result
    else:
        error = response.json()
        raise Exception(f"Withdrawal failed: {error['error']['message']}")

# Example usage
try:
    withdrawal = create_withdrawal(
        amount=Decimal("100.00"),
        address="0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE"
    )
except Exception as e:
    print(f"Error: {e}")

Testing

In the staging environment:

• Use small amounts for testing (minimum amounts apply)
• Withdrawals to address 0x0000000000000000000000000000000000000001 will auto-complete
• Withdrawals to address 0x0000000000000000000000000000000000000002 will auto-fail

Next Steps

• Check withdrawal status
• List all withdrawals
• Handle withdrawal webhooks