Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.oumla.com/llms.txt

Use this file to discover all available pages before exploring further.

This guide explains how to withdraw funds from Oumla addresses. Withdrawal behavior differs significantly between Bitcoin and Ethereum networks.
Two Ways to Use Oumla: This guide uses the TypeScript SDK. You can also accomplish the same tasks using direct REST API calls - see the API Reference for endpoint details.

​
Overview

Withdrawals work differently depending on the network:
  • Bitcoin (BTC/tBTC): Multi-address withdrawal - can withdraw from multiple addresses in one transaction
  • Ethereum (ETH/tETH): Single-address withdrawal - withdraws from one address at a time
Withdrawals are async operations that return a status immediately. Check transaction status on the blockchain explorer for final confirmation.

​
Prerequisites

Before starting, ensure you have:
  • An initialized SDK client
  • Addresses with sufficient balance
  • Your client share (for signing transactions)
  • Recipient address ready

​
Bitcoin Withdrawal (BTC/tBTC)

Bitcoin withdrawals support multi-address withdrawal, meaning you can withdraw from multiple addresses in a single transaction.

​
Step 1: Create Bitcoin Withdrawal

import { OumlaSdkApiClient, OumlaSdkApiEnvironment } from '@oumla/sdk';

const client = new OumlaSdkApiClient({
  environment: OumlaSdkApiEnvironment.Sandbox,
  apiKey: 'your-api-key-here'
});

// Withdraw from multiple addresses
const withdrawal = await client.withdraw.createWithdraw({
  networkId: 'your-btc-network-id', // Get from getNetworks()
  from: [
    'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh', // Address 1
    'bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4'  // Address 2
  ],
  to: 'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh', // Recipient
  amount: '0.001', // Total amount to withdraw
  clientShare: 'your-client-share'
});

console.log('Withdrawal ID:', withdrawal.data.data?.id);
console.log('Status:', withdrawal.data.data?.status); // 'pending'

​
Bitcoin Withdrawal Response

Bitcoin withdrawals return: 
{
  "data": {
    "data": {
      "id": "withdrawal-id",
      "status": "pending"
    }
  }
}
Bitcoin withdrawals return a withdrawal ID immediately. The transaction is processed asynchronously. Check the blockchain explorer or transaction status for final confirmation.

​
Ethereum Withdrawal (ETH/tETH)

Ethereum withdrawals work with single addresses only. To withdraw from multiple addresses, make separate withdrawal requests.

​
Step 1: Create Ethereum Withdrawal

// Withdraw from a single address
const withdrawal = await client.withdraw.createWithdraw({
  networkId: 'your-eth-network-id', // Get from getNetworks()
  from: [
    '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb' // Single address only
  ],
  to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb', // Recipient
  amount: '0.1', // Amount in ETH
  clientShare: 'your-client-share'
});

console.log('Transaction Hash:', withdrawal.data.data?.id);
console.log('Status:', withdrawal.data.data?.status); // 'pending'

​
Ethereum Withdrawal Response

Ethereum withdrawals return: 
{
  "data": {
    "data": {
      "id": "0x...",
      "status": "pending"
    }
  }
}
For Ethereum withdrawals, data.id contains the transaction hash.
Ethereum Limitation: You can only withdraw from one address per withdrawal request. If you need to withdraw from multiple addresses, make separate requests.

​
Network-Specific Considerations

​
Bitcoin Networks (BTC/tBTC)

Multi-Address Support:
  • Can combine funds from multiple addresses
  • More efficient for consolidating funds
  • Uses UTXO (Unspent Transaction Output) model
Requirements:
  • All addresses must belong to your organization
  • Sufficient balance across all addresses
  • Network fees deducted from total
Example: 
// Withdraw 0.001 BTC from two addresses
const withdrawal = await client.withdraw.createWithdraw({
  networkId: 'your-btc-network-id',
  from: [
    'address1', // Has 0.0005 BTC
    'address2'  // Has 0.0006 BTC
  ],
  to: 'recipient-address',
  amount: '0.001', // Total from both addresses
  clientShare: 'your-client-share'
});

​
Ethereum Networks (ETH/tETH)

Single-Address Only:
  • One address per withdrawal
  • Simpler transaction model
  • Account-based model
Requirements:
  • Address must have sufficient balance
  • Gas fees deducted from balance
  • Recipient address must be valid Ethereum address
Example: 
// Withdraw from single address
const withdrawal = await client.withdraw.createWithdraw({
  networkId: 'your-eth-network-id',
  from: ['0x...'], // Single address
  to: '0x...',
  amount: '0.1',
  clientShare: 'your-client-share'
});

// For multiple addresses, make separate requests
for (const address of addresses) {
  await client.withdraw.createWithdraw({
    networkId: 'your-eth-network-id',
    from: [address],
    to: recipientAddress,
    amount: '0.1',
    clientShare: 'your-client-share'
  });
}

​
Complete Examples

​
Bitcoin Withdrawal Example

import { OumlaSdkApiClient, OumlaSdkApiEnvironment } from '@oumla/sdk';

const client = new OumlaSdkApiClient({
  environment: OumlaSdkApiEnvironment.Sandbox,
  apiKey: process.env.OUMLA_API_KEY
});

async function withdrawBitcoin() {
  try {
    const withdrawal = await client.withdraw.createWithdraw({
      networkId: 'your-btc-network-id', // Use testnet network ID
      from: [
        'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
        'bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4'
      ],
      to: 'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
      amount: '0.001',
      clientShare: process.env.CLIENT_SHARE
    });

    console.log('Withdrawal ID:', withdrawal.data.data?.id);
    console.log('Status:', withdrawal.data.data?.status);
    
    // Note: Check blockchain explorer for transaction confirmation
    // Withdrawal ID can be used to track the transaction
    
  } catch (error) {
    console.error('Withdrawal failed:', error);
  }
}

withdrawBitcoin();

​
Ethereum Withdrawal Example

async function withdrawEthereum() {
  try {
    const withdrawal = await client.withdraw.createWithdraw({
      networkId: 'your-eth-network-id', // Use testnet network ID
      from: ['0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'],
      to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
      amount: '0.1',
      clientShare: process.env.CLIENT_SHARE
    });

    console.log('Transaction Hash:', withdrawal.data.data?.id);
    console.log('Status:', withdrawal.data.data?.status);
    
    // Check transaction on blockchain explorer
    console.log(`View on explorer: https://sepolia.etherscan.io/tx/${withdrawal.data.data?.id}`);
    
  } catch (error) {
    console.error('Withdrawal failed:', error);
  }
}

withdrawEthereum();

​
Checking Withdrawal Status

​
Bitcoin Withdrawals

Bitcoin withdrawals return a withdrawal ID. Check status by:
  1. Blockchain Explorer: Use the withdrawal ID or check addresses on blockchain explorer
  2. Transaction Monitoring: Monitor the from addresses for outgoing transactions

​
Ethereum Withdrawals

Ethereum withdrawals return a transaction hash. Check status: 
// Use the transaction hash to check status
const txHash = withdrawal.data.data?.id;

// Check on blockchain explorer
console.log(`View transaction: https://etherscan.io/tx/${txHash}`);

// Or use contract interactions to check receipt (if applicable)
const receipt = await client.contractInteractions.getTransactionReceipt('your-eth-network-id', txHash);

console.log('Transaction Status:', receipt.data.receipt?.status);

​
Common Issues

​
Insufficient Balance

Error: ERR_236 - Not enough balance Causes:
  • Address doesn’t have sufficient funds
  • Balance doesn’t cover amount + fees
Solutions:
  • Check address balance before withdrawal
  • Account for network fees in calculations
  • For Bitcoin: Ensure total across all addresses is sufficient

​
Invalid Address Format

Error: ERR_176 - Invalid contract address or validation error Causes:
  • Invalid recipient address format
  • Address doesn’t match network
Solutions:
  • Verify address format matches network (Bitcoin vs Ethereum)
  • Use valid blockchain addresses
  • Test addresses on testnet first

​
Bitcoin: No Unspent Transactions

Error: ERR_226 - No unspent transactions Causes:
  • Address has no UTXOs
  • All funds already spent
Solutions:
  • Ensure address has received funds
  • Wait for transaction confirmations
  • Check address balance

​
Ethereum: Single Address Limitation

Issue: Trying to withdraw from multiple addresses Solution:
  • Make separate withdrawal requests for each address
  • Or consolidate funds to one address first

​
Best Practices

  1. Check balances before withdrawal
  2. Account for fees - network fees are deducted automatically
  3. Use testnet first to test withdrawal flow
  4. Verify addresses before sending
  5. Monitor transactions on blockchain explorer
  6. Handle errors gracefully - withdrawals can fail
  7. For Bitcoin: Leverage multi-address withdrawal for efficiency
  8. For Ethereum: Make separate requests for multiple addresses

​
Network Comparison

FeatureBitcoin (BTC/tBTC)Ethereum (ETH/tETH)
Multi-address✅ Yes❌ No (single address only)
ResponseWithdrawal IDTransaction Hash
ModelUTXO-basedAccount-based
Fee ModelDeducted from totalDeducted from balance
ConfirmationCheck blockchainCheck transaction hash

​
Next Steps