Withdrawals API

Withdrawals

The Withdrawals service (client.withdrawals) allows you to withdraw USDC funds either to a SUI wallet or to a connected bank account. The service supports both direct cryptocurrency transfers and fiat off-ramping through banking partners.

Create a Withdrawal

Create a new withdrawal request:

import { WithdrawDestinationType } from '@suipay/api';

// Withdraw to SUI wallet
const walletWithdrawal = await client.withdrawals.create({
  amount_usdc: 50,
  destination_type: WithdrawDestinationType.WALLET,
  wallet_address: '0x1234567890abcdef1234567890abcdef12345678'
});

console.log(`Withdrawal created: ${walletWithdrawal.id}`);
console.log(`Status: ${walletWithdrawal.status}`);

Method Signature

client.withdrawals.create(request: CreateWithdrawalRequest): Promise<Withdrawal>

Request Parameters

Field	Type	Required	Description
amount_usdc	number	Yes	The amount in USDC to withdraw
destination_type	WithdrawDestinationType	Yes	Where to send the funds (WALLET or BANK_ACCOUNT)
wallet_address	string	Conditional	Required when destination_type is WALLET. Must be a valid SUI address
bank_account_id	string	Conditional	Required when destination_type is BANK_ACCOUNT. Must be a valid bank account ID

Response Type

interface Withdrawal {
  id: string;
  amount_usdc: number;
  destination_type: WithdrawDestinationType;
  status: WithdrawStatus;
  created_at: string;
  transaction_hash: string;
  bridge_transfer_id: string;
  error_message: string;
}

List Withdrawals

Retrieve all withdrawals for your account:

const withdrawals = await client.withdrawals.list();
console.log(`Found ${withdrawals.length} withdrawal(s)`);

withdrawals.forEach(withdrawal => {
  console.log(`${withdrawal.amount_usdc} USDC to ${withdrawal.destination_type}`);
  console.log(`Status: ${withdrawal.status}`);
  if (withdrawal.transaction_hash) {
    console.log(`Transaction: ${withdrawal.transaction_hash}`);
  }
});

Method Signature

client.withdrawals.list(): Promise<WithdrawalSummary[]>

Response Type

interface WithdrawalSummary {
  id: string;
  amount_usdc: number;
  destination_type: WithdrawDestinationType;
  status: WithdrawStatus;
  created_at: string;
  transaction_hash?: string;
  bridge_transfer_id?: string;
  error_message?: string;
}

Get Withdrawal

Retrieve detailed information about a specific withdrawal:

const withdrawalId = 'withdrawal_id_here';
const withdrawal = await client.withdrawals.get(withdrawalId);

console.log(`Withdrawal: ${withdrawal.amount_usdc} USDC`);
console.log(`Destination: ${withdrawal.destination_type}`);
console.log(`Status: ${withdrawal.status}`);

if (withdrawal.status === 'COMPLETED') {
  console.log('✅ Withdrawal completed!');
  if (withdrawal.transaction_hash) {
    console.log(`Transaction: ${withdrawal.transaction_hash}`);
  }
  if (withdrawal.completed_at) {
    console.log(`Completed at: ${new Date(withdrawal.completed_at).toLocaleString()}`);
  }
} else if (withdrawal.status === 'FAILED') {
  console.log('❌ Withdrawal failed:', withdrawal.error_message);
}

Method Signature

client.withdrawals.get(id: string): Promise<Withdrawal>

Response Type

interface Withdrawal {
  id: string;
  user_id: string;
  amount_usdc: number;
  destination_type: WithdrawDestinationType;
  bank_account_id?: string;
  wallet_address?: string;
  status: WithdrawStatus;
  error_message?: string;
  transaction_hash?: string;
  bridge_transfer_id?: string;
  created_at: string;
  updated_at: string;
  completed_at?: string;
}

Withdrawal Fields

Field	Type	Description
id	string	Unique withdrawal identifier
user_id	string	Associated user identifier
amount_usdc	number	Withdrawal amount in USDC
destination_type	WithdrawDestinationType	Where funds are sent (WALLET or BANK_ACCOUNT)
bank_account_id	string?	Bank account ID (for BANK_ACCOUNT destinations)
wallet_address	string?	SUI wallet address (for WALLET destinations)
status	WithdrawStatus	Current withdrawal status
error_message	string?	Error description if withdrawal failed
transaction_hash	string?	SUI transaction hash (for wallet withdrawals)
bridge_transfer_id	string?	Bridge service transfer ID (for bank withdrawals)
created_at	string	Withdrawal creation timestamp
updated_at	string	Last update timestamp
completed_at	string?	Completion timestamp

Withdrawal Status

Status Enum

enum WithdrawStatus {
  PENDING = 'PENDING',
  PROCESSING = 'PROCESSING',
  COMPLETED = 'COMPLETED',
  FAILED = 'FAILED'
}

Status Monitoring

Monitor withdrawal status changes:

async function monitorWithdrawal(withdrawalId: string) {
  const withdrawal = await client.withdrawals.get(withdrawalId);
  
  console.log(`Withdrawal Status: ${withdrawal.status}`);
  
  switch (withdrawal.status) {
    case 'PENDING':
      console.log('⏳ Withdrawal request received');
      break;
    case 'PROCESSING':
      console.log('🔄 Processing withdrawal...');
      break;
    case 'COMPLETED':
      console.log('✅ Withdrawal completed!');
      if (withdrawal.transaction_hash) {
        console.log(`Transaction: ${withdrawal.transaction_hash}`);
      }
      break;
    case 'FAILED':
      console.log('❌ Withdrawal failed:', withdrawal.error_message);
      break;
  }
}

State Transitions

• Normal: PENDING → PROCESSING → COMPLETED

• Failure: PENDING → PROCESSING → FAILED

Destination Types

WALLET

Withdraw USDC directly to a SUI wallet address:

const walletWithdrawal = await client.withdrawals.create({
  amount_usdc: 25,
  destination_type: WithdrawDestinationType.WALLET,
  wallet_address: '0x1234567890abcdef1234567890abcdef12345678'
});

Requirements:

• Valid SUI address starting with "0x"

• Address format is validated

Processing:

• Direct USDC transfer on SUI blockchain

• Generally faster than bank withdrawals

• Transaction hash available after completion

BANK_ACCOUNT

Withdraw USD to your connected bank account:

// First, ensure you have a verified bank account
const user = await client.user.get();
if (!user.kyc_complete) {
  console.log('KYC verification required for bank withdrawals');
  return;
}

const bankAccounts = await client.user.getBankAccounts();
const primaryAccount = bankAccounts[0]; // Use first available bank account

if (primaryAccount) {
  const bankWithdrawal = await client.withdrawals.create({
    amount_usdc: 100,
    destination_type: WithdrawDestinationType.BANK_ACCOUNT,
    bank_account_id: primaryAccount.id
  });
  console.log('Bank withdrawal initiated');
} else {
  console.log('No bank account available');
}

Requirements:

• KYC verification completed

• Bank account connected via Bridge service

• Valid bank account ID

Processing:

• USD conversion and ACH transfer via Bridge service

• Takes 1-3 business days for settlement

• Bridge transfer ID tracked for status

Error Handling

Handle common withdrawal errors:

import { 
  SuiPayValidationError, 
  SuiPayAuthenticationError 
} from '@suipay/api';

try {
  const withdrawal = await client.withdrawals.create({
    amount_usdc: 1000, // More than available balance
    destination_type: WithdrawDestinationType.WALLET,
    wallet_address: '0x1234567890abcdef1234567890abcdef12345678'
  });
} catch (error) {
  if (error instanceof SuiPayValidationError) {
    console.error('Validation error:', error.response?.error);
    // Common issues: insufficient balance, invalid wallet address
  } else if (error instanceof SuiPayAuthenticationError) {
    console.error('Authentication failed');
  } else {
    console.error('Unexpected error:', error);
  }
}

Complete Example

Here's a comprehensive withdrawal example:

import { WithdrawDestinationType, WithdrawStatus } from '@suipay/api';

async function processWithdrawal() {
  try {
    // Check balance first
    const user = await client.user.get();
    console.log(`Current balance: ${user.polar_balance_usdc} USDC`);
    
    const withdrawAmount = 50;
    if (user.polar_balance_usdc < withdrawAmount) {
      console.log('Insufficient balance for withdrawal');
      return;
    }
    
    // Create withdrawal
    const withdrawal = await client.withdrawals.create({
      amount_usdc: withdrawAmount,
      destination_type: WithdrawDestinationType.WALLET,
      wallet_address: '0x1234567890abcdef1234567890abcdef12345678'
    });
    
    console.log(`Withdrawal created: ${withdrawal.id}`);
    console.log(`Status: ${withdrawal.status}`);
    
    // Monitor status (in production, use webhooks instead of polling)
    const checkStatus = async () => {
      const updated = await client.withdrawals.get(withdrawal.id);
      
      if (updated.status === WithdrawStatus.COMPLETED) {
        console.log('✅ Withdrawal completed!');
        console.log(`Transaction: ${updated.transaction_hash}`);
        return true;
      } else if (updated.status === WithdrawStatus.FAILED) {
        console.log('❌ Withdrawal failed:', updated.error_message);
        return true;
      } else {
        console.log(`⏳ Status: ${updated.status}`);
        return false;
      }
    };
    
    // Poll every 30 seconds
    const pollInterval = setInterval(async () => {
      const completed = await checkStatus();
      if (completed) {
        clearInterval(pollInterval);
      }
    }, 30000);
    
  } catch (error) {
    console.error('Error processing withdrawal:', error);
  }
}

Important Notes

• Minimum withdrawal: 0.01 USDC

• Balance check: Verify sufficient balance before creating withdrawals

• Status monitoring: Use webhooks or polling to track progress

• Bank settlements: Bank account withdrawals take 1-3 business days

• Transaction hashes: Available for wallet withdrawals for blockchain verification

• Error handling: Always handle validation and authentication errors