Withdraw from Credit Wallet

curl --request POST \
  --url https://api.example.com/v1/wallet/credit/withdraw \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'x-client-key: <x-client-key>' \
  --data '
{
  "amount": "<string>"
}
'

import requests

url = "https://api.example.com/v1/wallet/credit/withdraw"

payload = { "amount": "<string>" }
headers = {
    "x-client-key": "<x-client-key>",
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-client-key': '<x-client-key>',
    Authorization: '<authorization>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({amount: '<string>'})
};

fetch('https://api.example.com/v1/wallet/credit/withdraw', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/wallet/credit/withdraw",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json",
    "x-client-key: <x-client-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/wallet/credit/withdraw"

	payload := strings.NewReader("{\n  \"amount\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-client-key", "<x-client-key>")
	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/wallet/credit/withdraw")
  .header("x-client-key", "<x-client-key>")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/wallet/credit/withdraw")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-client-key"] = '<x-client-key>'
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "txHash": "0xb92de09d893e8162b0861c0f7321f68df02212efbc58f208839ae3f176d89638"
}

{
  "message": "Insufficient balance"
}

{
  "message": "Not authenticated"
}

{
  "message": "Not authorized"
}

{
  "message": "amount must be a positive number"
}

{
  "message": "Internal server error"
}

POST

wallet

credit

withdraw

Withdraw from Credit Wallet

curl --request POST \
  --url https://api.example.com/v1/wallet/credit/withdraw \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'x-client-key: <x-client-key>' \
  --data '
{
  "amount": "<string>"
}
'

import requests

url = "https://api.example.com/v1/wallet/credit/withdraw"

payload = { "amount": "<string>" }
headers = {
    "x-client-key": "<x-client-key>",
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-client-key': '<x-client-key>',
    Authorization: '<authorization>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({amount: '<string>'})
};

fetch('https://api.example.com/v1/wallet/credit/withdraw', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/wallet/credit/withdraw",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json",
    "x-client-key: <x-client-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/wallet/credit/withdraw"

	payload := strings.NewReader("{\n  \"amount\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-client-key", "<x-client-key>")
	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/wallet/credit/withdraw")
  .header("x-client-key", "<x-client-key>")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/wallet/credit/withdraw")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-client-key"] = '<x-client-key>'
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "txHash": "0xb92de09d893e8162b0861c0f7321f68df02212efbc58f208839ae3f176d89638"
}

{
  "message": "Insufficient balance"
}

{
  "message": "Not authenticated"
}

{
  "message": "Not authorized"
}

{
  "message": "amount must be a positive number"
}

{
  "message": "Internal server error"
}

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:

Check available balance with GET /v1/wallet/credit
Estimate fees with GET /v1/wallet/credit/withdraw-estimation
Initiate withdrawal with this endpoint
Monitor transaction on blockchain using returned txHash
Verify completion with GET /v1/wallet/history

Authentication

string

required

Your public API client key that identifies your environment

string

required

Bearer token obtained from OAuth flow or direct login

Query Parameters

boolean

default:false

Set to true to route request to US backend environment (if available for your client)

Request Body

string

required

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

Response

string

Blockchain transaction hash of the withdrawal. Use this to track transaction status on the Linea network.

{
  "txHash": "0xb92de09d893e8162b0861c0f7321f68df02212efbc58f208839ae3f176d89638"
}

{
  "message": "Insufficient balance"
}

{
  "message": "Not authenticated"
}

{
  "message": "Not authorized"
}

{
  "message": "amount must be a positive number"
}

{
  "message": "Internal server error"
}

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"
  }'

import requests
from decimal import Decimal

url = "https://dev.api.baanx.com/v1/wallet/credit/withdraw"
headers = {
    "x-client-key": "YOUR_CLIENT_KEY",
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}

withdrawal_amount = Decimal("10.00")
data = {
    "amount": str(withdrawal_amount)
}

response = requests.post(url, headers=headers, json=data)

if response.status_code == 200:
    result = response.json()
    tx_hash = result['txHash']
    print(f"Withdrawal initiated!")
    print(f"Transaction hash: {tx_hash}")
    print(f"Track on Linea: https://lineascan.build/tx/{tx_hash}")
else:
    error = response.json()
    print(f"Error: {error['message']}")

async function withdrawFromCredit(amount) {
  const response = await fetch(
    'https://dev.api.baanx.com/v1/wallet/credit/withdraw',
    {
      method: 'POST',
      headers: {
        'x-client-key': 'YOUR_CLIENT_KEY',
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ amount: amount.toString() })
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message);
  }

  const result = await response.json();
  return result.txHash;
}

try {
  const txHash = await withdrawFromCredit(10.00);
  console.log('Withdrawal successful:', txHash);
} catch (error) {
  console.error('Withdrawal failed:', error.message);
}

interface WithdrawalRequest {
  amount: string;
}

interface WithdrawalResponse {
  txHash: string;
}

async function withdrawFromCreditWallet(
  amount: string
): Promise<string> {
  const response = await fetch(
    'https://dev.api.baanx.com/v1/wallet/credit/withdraw',
    {
      method: 'POST',
      headers: {
        'x-client-key': 'YOUR_CLIENT_KEY',
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ amount })
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message);
  }

  const data: WithdrawalResponse = await response.json();
  return data.txHash;
}

const txHash = await withdrawFromCreditWallet('10.00');
console.log(`Transaction: ${txHash}`);

Complete Withdrawal Flow

Check Balance

Verify sufficient funds are available

const wallet = await fetch('/v1/wallet/credit');
const { balance } = await wallet.json();

Estimate Fees

Get current network fee estimate

const fees = await fetch('/v1/wallet/credit/withdraw-estimation');
const { usdc: feeAmount } = await fees.json();

Calculate Net Amount

Show user what they’ll receive

const netAmount = parseFloat(balance) - parseFloat(feeAmount);
// Display: "You will receive ~${netAmount} USDC"

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();

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

Estimate Credit Withdrawal Fees - Calculate fees before withdrawal
Get Credit Wallet Balance - Check available balance
Get External Wallets - View registered withdrawal destinations
Get Wallet History - Verify withdrawal completion

Overview

Authentication

User

Card

Orders

Wallet

Delegation

Consent

Referral

Webhooks

Withdraw from Credit Wallet

Overview

Authentication

Query Parameters

Request Body

Response

Code Examples

Complete Withdrawal Flow

Important Notes

Error Handling

Common Errors

Edge Cases

Minimum Withdrawal Amounts

Concurrent Withdrawals

Network Congestion

​Overview

​Authentication

​Query Parameters

​Request Body

​Response

​Code Examples

​Complete Withdrawal Flow

​Important Notes

​Error Handling

​Common Errors

​Edge Cases

​Minimum Withdrawal Amounts

​Concurrent Withdrawals

​Network Congestion

​Related Endpoints

Overview

Authentication

Query Parameters

Request Body

Response

Code Examples

Complete Withdrawal Flow

Important Notes

Error Handling

Common Errors

Edge Cases

Minimum Withdrawal Amounts

Concurrent Withdrawals

Network Congestion

Related Endpoints