Skip to main content
POST
/
v1
/
wallet
/
credit
/
withdraw
{
  "txHash": "0xb92de09d893e8162b0861c0f7321f68df02212efbc58f208839ae3f176d89638"
}

​
Overview

This endpoint initiates a withdrawal from the authenticated user’s credit wallet to their registered external wallet address. The withdrawal is processed on-chain on the Linea network, and the net amount received equals the requested amount minus network gas fees. Prerequisites:
  • User must have a registered external wallet (completed delegation flow)
  • Credit wallet must have sufficient balance to cover withdrawal amount + fees
  • User must be verified and in good standing
Process Flow:
  1. Check available balance with GET /v1/wallet/credit
  2. Estimate fees with GET /v1/wallet/credit/withdraw-estimation
  3. Initiate withdrawal with this endpoint
  4. Monitor transaction on blockchain using returned txHash
  5. Verify completion with GET /v1/wallet/history

​
Authentication

​
x-client-key
string
required
Your public API client key that identifies your environment
​
Authorization
string
required
Bearer token obtained from OAuth flow or direct login

​
Query Parameters

​
x-us-env
boolean
default:false
Set to true to route request to US backend environment (if available for your client)

​
Request Body

​
amount
string
required
Amount to withdraw in USDC (decimal string). Must not exceed available balance.

​
Response

​
txHash
string
Blockchain transaction hash of the withdrawal. Use this to track transaction status on the Linea network.
{
  "txHash": "0xb92de09d893e8162b0861c0f7321f68df02212efbc58f208839ae3f176d89638"
}

​
Code Examples

curl -X POST "https://dev.api.baanx.com/v1/wallet/credit/withdraw" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "10.00"
  }'

​
Complete Withdrawal Flow

1

Check Balance

Verify sufficient funds are available
const wallet = await fetch('/v1/wallet/credit');
const { balance } = await wallet.json();
2

Estimate Fees

Get current network fee estimate
const fees = await fetch('/v1/wallet/credit/withdraw-estimation');
const { usdc: feeAmount } = await fees.json();
3

Calculate Net Amount

Show user what they’ll receive
const netAmount = parseFloat(balance) - parseFloat(feeAmount);
// Display: "You will receive ~${netAmount} USDC"
4

Initiate Withdrawal

Execute the withdrawal
const result = await fetch('/v1/wallet/credit/withdraw', {
  method: 'POST',
  body: JSON.stringify({ amount: '10.00' })
});
const { txHash } = await result.json();
5

Monitor Transaction

Track blockchain confirmation
// Poll blockchain or use webhook
const txUrl = `https://lineascan.build/tx/${txHash}`;
// Wait for confirmations (typically 1-3 minutes on Linea)

​
Important Notes

Insufficient Balance: The withdrawal amount plus estimated fees must not exceed available balance. Always validate balance before calling this endpoint.
Network Fees: Fees are deducted from the withdrawal amount. If withdrawing 10 USDC with 0.02 USDC fee, user receives 9.98 USDC.
Transaction Monitoring: Use the returned txHash to track transaction status on Linea block explorer. Typical confirmation time is 1-3 minutes.

​
Error Handling

​
Common Errors

Insufficient Balance 
{
  "message": "Insufficient balance for withdrawal"
}
Solution: Check balance with GET /v1/wallet/credit and ensure amount + fees < balance. No External Wallet 
{
  "message": "No external wallet registered"
}
Solution: User must complete delegation flow to register an external wallet first. Invalid Amount 
{
  "message": "amount must be a positive number"
}
Solution: Validate amount format and ensure it’s a positive decimal string. Withdrawal Not Allowed 
{
  "message": "Withdrawals are not allowed for this wallet"
}
Solution: Check isWithdrawable flag on GET /v1/wallet/credit before attempting withdrawal.

​
Edge Cases

​
Minimum Withdrawal Amounts

Gas fees make very small withdrawals uneconomical: 
const minViableWithdrawal = 1.00;
if (parseFloat(amount) < minViableWithdrawal) {
  alert('Minimum withdrawal is 1.00 USDC due to network fees');
}

​
Concurrent Withdrawals

Only one withdrawal can be processed at a time per wallet: 
let withdrawalInProgress = false;

async function safeWithdraw(amount) {
  if (withdrawalInProgress) {
    throw new Error('Withdrawal already in progress');
  }

  withdrawalInProgress = true;
  try {
    return await withdrawFromCredit(amount);
  } finally {
    withdrawalInProgress = false;
  }
}

​
Network Congestion

During high traffic, transactions may take longer:
  • Implement retry logic with exponential backoff
  • Display estimated confirmation time to users
  • Consider queuing withdrawals for later processing