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.withdrawals.create({
network: 'BTC', // or 'tBTC' for testnet
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.id);
console.log('Status:', withdrawal.data.status); // 'pending'
Bitcoin Withdrawal Response
Bitcoin withdrawals return:
{
"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.withdrawals.create({
network: 'ETH', // or 'tETH' for testnet
from: [
'0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb' // Single address only
],
to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb', // Recipient
amount: '0.1', // Amount in ETH
clientShare: 'your-client-share'
});
console.log('Transaction Hash:', withdrawal.data.hash);
console.log('Status:', withdrawal.data.status); // 'pending'
Ethereum Withdrawal Response
Ethereum withdrawals return:
{
"data": {
"hash": "0x...",
"status": "pending"
}
}
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.withdrawals.create({
network: 'BTC',
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.withdrawals.create({
network: 'ETH',
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.withdrawals.create({
network: 'ETH',
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.withdrawals.create({
network: 'tBTC', // Testnet
from: [
'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
'bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4'
],
to: 'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
amount: '0.001',
clientShare: process.env.CLIENT_SHARE
});
console.log('Withdrawal ID:', withdrawal.data.id);
console.log('Status:', withdrawal.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.withdrawals.create({
network: 'tETH', // Testnet
from: ['0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'],
to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
amount: '0.1',
clientShare: process.env.CLIENT_SHARE
});
console.log('Transaction Hash:', withdrawal.data.hash);
console.log('Status:', withdrawal.data.status);
// Check transaction on blockchain explorer
console.log(`View on explorer: https://sepolia.etherscan.io/tx/${withdrawal.data.hash}`);
} catch (error) {
console.error('Withdrawal failed:', error);
}
}
withdrawEthereum();
Checking Withdrawal Status
Bitcoin Withdrawals
Bitcoin withdrawals return a withdrawal ID. Check status by:
- Blockchain Explorer: Use the withdrawal ID or check addresses on blockchain explorer
- 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.hash;
// 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({
network: 'ETH',
txId: txHash
});
console.log('Transaction Status:', receipt.data.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
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
- Check balances before withdrawal
- Account for fees - network fees are deducted automatically
- Use testnet first to test withdrawal flow
- Verify addresses before sending
- Monitor transactions on blockchain explorer
- Handle errors gracefully - withdrawals can fail
- For Bitcoin: Leverage multi-address withdrawal for efficiency
- For Ethereum: Make separate requests for multiple addresses
Network Comparison
| Feature | Bitcoin (BTC/tBTC) | Ethereum (ETH/tETH) |
|---|
| Multi-address | ✅ Yes | ❌ No (single address only) |
| Response | Withdrawal ID | Transaction Hash |
| Model | UTXO-based | Account-based |
| Fee Model | Deducted from total | Deducted from balance |
| Confirmation | Check blockchain | Check transaction hash |
Next Steps
