Cross-Chain Withdrawals

This guide covers withdrawing assets from your EVM smart account.

Overview

The SDK provides two withdrawal methods:

Method	Destination	Gas	Use Case
`withdrawToEVM()`	EVM address	Sponsored (Free)	Transfer USDC to your personal wallet
`withdrawToBitcoin()`	Bitcoin address	Paid via bridge	Convert to BTC

Gasless EVM Withdrawals (Recommended)

Withdraw USDC from your smart account to any EVM address with zero gas fees. The SDK prepares the platform smart wallet address/signature automatically if needed.

How It Works

Your borrowed USDC is in your smart account (platform wallet)
SDK executes transfer via ZeroDev paymaster
Gas is sponsored - you pay nothing
USDC arrives in your personal wallet

Basic Usage

const transactionId = await sdk.withdrawToEVM({
  chain: ChainType.ARBITRUM,
  amount: '100',                    // 100 USDC
  destinationAddress: '0x742d...'   // Your wallet
});

const status = await sdk.getWithdrawStatus(transactionId);
console.log('Status:', status.data.status);
console.log('Transaction:', status.data.transactionDetails?.transactionHash);

Complete Example

import { BorrowSDK, ChainType } from '@satsterminal-sdk/borrow';

async function withdrawToMyWallet() {
  const sdk = new BorrowSDK({
    apiKey: process.env.API_KEY!,
    wallet: walletProvider
  });

  await sdk.setup();

  // Check available balance
  const positions = await sdk.getWalletPositions();
  const usdcBalance = positions.data.find(
    p => p.attributes.fungible_info?.symbol === 'USDC'
  )?.attributes.quantity.float || 0;

  console.log('Available USDC:', usdcBalance);

  if (usdcBalance < 10) {
    console.log('Insufficient balance');
    return;
  }

  // Withdraw to your personal wallet (gasless!)
  const myWallet = '0x742d35Cc6634C0532925a3b844Bc9e7595f...';

  const transactionId = await sdk.withdrawToEVM({
    chain: ChainType.ARBITRUM,
    amount: usdcBalance.toString(),
    destinationAddress: myWallet
  });

  console.log('Withdrawal created:', transactionId);
  const status = await sdk.getWithdrawStatus(transactionId);
  console.log('Status:', status.data.status);
}

Supported Chains

Chain	Status
Arbitrum	✅ Supported
Base	✅ Supported

Bitcoin Withdrawals

For withdrawing to a Bitcoin address, use withdrawToBitcoin(). The SDK prepares the platform smart wallet address/signature automatically if needed.

How It Works

Assets are transferred from your smart account
Bridge protocol swaps to BTC
BTC is sent to your Bitcoin address

Basic Withdrawal

const txId = await sdk.withdrawToBitcoin({
  chain: ChainType.ARBITRUM,  // Source chain
  amount: '100',               // Amount to withdraw
  assetSymbol: 'USDC',        // Asset to withdraw
  btcAddress: 'bc1q...'       // Destination BTC address
});

console.log('Withdrawal initiated:', txId);

Tracking Withdrawal Status

// Get status
const status = await sdk.getWithdrawStatus(txId);

console.log('Success:', status.success);
console.log('Stage:', status.data.workflowState?.stage);
console.log('Redeem TX:', status.data.workflowState?.redeemTxHash);

// Full transaction details
console.log('Details:', status.data);

Supported Assets

Asset	Chains
USDC	Arbitrum, Base, Ethereum
USDT	Arbitrum, Base, Ethereum

Withdrawal Parameters

interface WithdrawToBitcoinRequest {
  chain: ChainType;     // Source chain
  amount: string;       // Amount to withdraw (as string)
  assetSymbol: string;  // 'USDC' or 'USDT'
  btcAddress: string;   // Destination BTC address
}

Chain Selection

import { ChainType } from '@satsterminal-sdk/borrow';

// Withdraw from Arbitrum
await sdk.withdrawToBitcoin({
  chain: ChainType.ARBITRUM,
  // ...
});

// Withdraw from Base
await sdk.withdrawToBitcoin({
  chain: ChainType.BASE,
  // ...
});

Checking Balance Before Withdrawal

// Get available balance
const positions = await sdk.getWalletPositions();
const usdcPosition = positions.data.find(
  p => p.attributes.fungible_info?.symbol === 'USDC'
);

const availableBalance = usdcPosition?.attributes.quantity.float || 0;
console.log('Available USDC:', availableBalance);

// Validate withdrawal amount
const withdrawAmount = 100;
if (withdrawAmount > availableBalance) {
  throw new Error(`Insufficient balance. Available: ${availableBalance} USDC`);
}

Withdrawal Status Response

interface WithdrawStatusResponse {
  success: boolean;
  data: {
    transactionId: string;
    status: string;
    workflowState?: {
      stage: string;
      transactionHash?: string;
      redeemTxHash?: string;  // BTC transaction hash
      error?: string;
    };
    transactionDetails?: {
      transactionHash?: string;
    };
  };
}

Status Stages

Bitcoin withdrawals use the following bridge stages:

Stage	Description
`INITIALIZING`	Withdrawal initialized
`QUOTE_READY`	Bridge quote prepared
`SWAP_CREATED`	Bridge order created
`EXECUTING_APPROVAL`	Token approval being submitted, when required
`APPROVAL_CONFIRMED`	Token approval confirmed
`EXECUTING_INITIATE`	Bridge transaction being submitted
`INITIATE_CONFIRMED`	Bridge transaction confirmed
`AWAITING_BRIDGE_COMPLETION`	Waiting for destination settlement
`BRIDGE_COMPLETED`	Bridge settlement complete
`COMPLETED`	BTC sent
`FAILED`	Withdrawal failed
`CANCELLED`	Withdrawal cancelled

Direct EVM transfers use INITIALIZING, VALIDATING, CHECKING_BALANCE, EXECUTING_TRANSFER, and COMPLETED, with FAILED and CANCELLED as terminal error states.

Polling for Completion

async function waitForWithdrawal(sdk: BorrowSDK, txId: string): Promise<string> {
  const maxAttempts = 60; // 30 minutes with 30s intervals
  let attempts = 0;

  while (attempts < maxAttempts) {
    const status = await sdk.getWithdrawStatus(txId);
    const state = status.data.workflowState;

    if (state?.stage === 'COMPLETED') {
      return status.data.transactionDetails?.transactionHash
        ?? state.redeemTxHash!;
    }

    if (state?.stage === 'FAILED') {
      throw new Error(state.error || 'Withdrawal failed');
    }

    console.log(`Status: ${state?.stage ?? status.data.status}...`);
    await new Promise(r => setTimeout(r, 30000)); // Wait 30s
    attempts++;
  }

  throw new Error('Withdrawal timed out');
}

// Usage
const btcTxHash = await waitForWithdrawal(sdk, txId);
console.log('BTC Transaction:', btcTxHash);

Fee Estimation

Get estimated fees before withdrawal:

const fees = await sdk.getFees({
  chain: ChainType.ARBITRUM,
  collateralAmount: '0.1' // Amount in BTC equivalent
});

console.log('Fee Breakdown:');
console.log('  Garden Fee:', fees.gardenFeePercent, '%');
console.log('  Bridge Fee:', fees.totalBridgeFeePercentage, '%');
console.log('  Estimated Gas:', fees.estimatedGasFee);
console.log('  Total Fee (USD):', fees.totalBridgeFeeUSD);

Error Handling

try {
  const txId = await sdk.withdrawToBitcoin({
    chain: ChainType.ARBITRUM,
    amount: '100',
    assetSymbol: 'USDC',
    btcAddress: 'bc1q...'
  });
} catch (error) {
  if (error instanceof Error) {
    if (error.message.includes('insufficient balance')) {
      console.error('Not enough balance to withdraw');
    } else if (error.message.includes('invalid address')) {
      console.error('Invalid BTC address');
    } else if (error.message.includes('minimum')) {
      console.error('Amount below minimum withdrawal');
    } else {
      console.error('Withdrawal error:', error.message);
    }
  }
}

Overview

Suite

UI Components

Swaps

Borrow

Bridge

Earn

Cross chain withdrawals

Cross-Chain Withdrawals

Overview

Gasless EVM Withdrawals (Recommended)

How It Works

Basic Usage

Complete Example

Supported Chains

Bitcoin Withdrawals

How It Works

Basic Withdrawal

Tracking Withdrawal Status

Supported Assets

Withdrawal Parameters

Chain Selection

Checking Balance Before Withdrawal

Withdrawal Status Response

Status Stages

Polling for Completion

Fee Estimation

Error Handling

​Cross-Chain Withdrawals

​Overview

​Gasless EVM Withdrawals (Recommended)

​How It Works

​Basic Usage

​Complete Example

​Supported Chains

​Bitcoin Withdrawals

​How It Works

​Basic Withdrawal

​Tracking Withdrawal Status

​Supported Assets

​Withdrawal Parameters

​Chain Selection

​Checking Balance Before Withdrawal

​Withdrawal Status Response

​Status Stages

​Polling for Completion

​Fee Estimation

​Error Handling

Cross-Chain Withdrawals

Overview

Gasless EVM Withdrawals (Recommended)

How It Works

Basic Usage

Complete Example

Supported Chains

Bitcoin Withdrawals

How It Works

Basic Withdrawal

Tracking Withdrawal Status

Supported Assets

Withdrawal Parameters

Chain Selection

Checking Balance Before Withdrawal

Withdrawal Status Response

Status Stages

Polling for Completion

Fee Estimation

Error Handling