Skip to main content

​
Overview

Whitelist management provides an additional security layer for withdrawals from internal (custodial) wallets. Whitelisted addresses are pre-approved withdrawal destinations that have been verified and saved for secure fund transfers. Security Benefits:
  • Pre-approve trusted addresses before withdrawal
  • Prevent withdrawal to unauthorized addresses
  • Maintain audit trail of approved destinations
  • Track usage history of whitelisted addresses
Use Cases:
  • Add frequently used exchange addresses
  • Pre-approve personal wallet addresses
  • Manage beneficiary addresses for business accounts
  • Implement security policies requiring address approval

​
GET - Retrieve Whitelisted Addresses

Get all whitelisted addresses for a specific currency.

​
Authentication

​
x-client-key
string
required
Your public API client key
​
Authorization
string
required
Bearer token for authentication

​
Query Parameters

​
currency
string
required
Currency of the desired whitelisted addresses (e.g., “xrp”, “usdc”, “eth”)
​
x-us-env
boolean
default:false
Route to US backend environment

​
Response

​
id
string
Unique whitelist entry identifier
​
name
string
Friendly name or label for the address
​
beneficiaryFirstName
string
Beneficiary’s first name
​
beneficiaryLastName
string
Beneficiary’s last name
​
walletAddress
string
Blockchain address
​
walletMemo
string
Memo/destination tag (for XRP, Stellar, etc.)
​
currency
string
Currency code
​
lastUsedAt
string
ISO 8601 timestamp of last withdrawal to this address
​
createdAt
string
ISO 8601 timestamp of when address was whitelisted
[
  {
    "id": "d7ed0d12-270c-4491-b1a4-bebf2cc42b5c",
    "name": "Binance Account | Primary",
    "beneficiaryFirstName": "John",
    "beneficiaryLastName": "Doe",
    "walletAddress": "rNxp4h8apvRis6mJf9Sh8C6iRxfrDWN7AA",
    "walletMemo": "66",
    "currency": "xrp",
    "lastUsedAt": "2025-08-12T13:44:47.287Z",
    "createdAt": "2025-08-11T13:44:47.287Z"
  },
  {
    "id": "a3f2e1d4-c5b6-47a8-9e0f-1d2c3b4a5e6f",
    "name": "Kraken Exchange",
    "beneficiaryFirstName": "John",
    "beneficiaryLastName": "Doe",
    "walletAddress": "rPEPPER7kfTD9w2To4CQk6UCfuHM9c6GDY",
    "walletMemo": "12345",
    "currency": "xrp",
    "lastUsedAt": null,
    "createdAt": "2025-08-10T10:30:22.123Z"
  }
]

curl -X GET "https://dev.api.baanx.com/v1/wallet/whitelist?currency=xrp" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
POST - Add Addresses to Whitelist

Add one or more external wallet addresses to the whitelist. Multiple addresses can be added in a single request.

​
Request Body

​
wallets
array
required
Array of addresses to whitelist

​
Response

​
success
boolean
Whether whitelisting was successful
{
  "success": true
}

curl -X POST "https://dev.api.baanx.com/v1/wallet/whitelist" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wallets": [
      {
        "currency": "xrp",
        "name": "Binance Account | Primary",
        "beneficiaryFirstName": "John",
        "beneficiaryLastName": "Doe",
        "walletAddress": "rNxp4h8apvRis6mJf9Sh8C6iRxfrDWN7AA",
        "walletMemo": "66"
      }
    ]
  }'

​
DELETE - Remove Addresses from Whitelist

Remove previously whitelisted addresses. Provide one or more whitelist entry IDs to remove.

​
Request Body

​
walletIds
array
required
Array of whitelist entry IDs to remove (obtained from GET response)

​
Response

​
success
boolean
Whether removal was successful
{
  "success": true
}

curl -X DELETE "https://dev.api.baanx.com/v1/wallet/whitelist" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "walletIds": [
      "d7ed0d12-270c-4491-b1a4-bebf2cc42b5c"
    ]
  }'

​
Complete Whitelist Management

async function manageWhitelist(currency) {
  const current = await fetch(
    `/v1/wallet/whitelist?currency=${currency}`
  ).then(r => r.json());

  console.log(`Current whitelist: ${current.length} addresses`);

  const newAddress = {
    currency,
    name: 'New Exchange Account',
    beneficiaryFirstName: 'John',
    beneficiaryLastName: 'Doe',
    walletAddress: 'rNewAddress123456789',
    walletMemo: '999'
  };

  const exists = current.some(
    w => w.walletAddress === newAddress.walletAddress &&
         w.walletMemo === newAddress.walletMemo
  );

  if (!exists) {
    await fetch('/v1/wallet/whitelist', {
      method: 'POST',
      body: JSON.stringify({ wallets: [newAddress] })
    });
    console.log('Address added to whitelist');
  } else {
    console.log('Address already whitelisted');
  }

  const unusedAddresses = current.filter(w => !w.lastUsedAt);
  if (unusedAddresses.length > 0) {
    console.log(`${unusedAddresses.length} addresses never used`);
  }

  return await fetch(`/v1/wallet/whitelist?currency=${currency}`)
    .then(r => r.json());
}

​
Important Notes

Memo Requirements: For networks like XRP and Stellar, the combination of address + memo identifies the destination. Always include both when whitelisting exchange addresses.
Usage Tracking: The lastUsedAt field helps identify frequently vs rarely used addresses. Consider removing unused addresses periodically.
Descriptive Names: Use clear, descriptive names that help identify the purpose and destination of each whitelisted address (e.g., “Binance Main Account | Trading”).

​
Address Validation

function validateWhitelistEntry(entry) {
  const addressPatterns = {
    xrp: /^r[1-9A-HJ-NP-Za-km-z]{25,34}$/,
    eth: /^0x[a-fA-F0-9]{40}$/,
    solana: /^[1-9A-HJ-NP-Za-km-z]{32,44}$/
  };

  const pattern = addressPatterns[entry.currency];
  if (!pattern) {
    throw new Error(`Unsupported currency: ${entry.currency}`);
  }

  if (!pattern.test(entry.walletAddress)) {
    throw new Error(`Invalid ${entry.currency.toUpperCase()} address format`);
  }

  if (!entry.name || entry.name.trim().length < 3) {
    throw new Error('Name must be at least 3 characters');
  }

  if (!entry.beneficiaryFirstName || !entry.beneficiaryLastName) {
    throw new Error('Beneficiary name is required');
  }

  const memoRequired = ['xrp', 'xlm'].includes(entry.currency);
  if (memoRequired && !entry.walletMemo) {
    console.warn(`Memo recommended for ${entry.currency.toUpperCase()}`);
  }

  return true;
}

​
Use Cases

​
Import from CSV

async function importWhitelistFromCSV(csvData, currency) {
  const lines = csvData.split('\n').slice(1);

  const addresses = lines.map(line => {
    const [name, firstName, lastName, address, memo] = line.split(',');
    return {
      currency,
      name: name.trim(),
      beneficiaryFirstName: firstName.trim(),
      beneficiaryLastName: lastName.trim(),
      walletAddress: address.trim(),
      walletMemo: memo?.trim() || undefined
    };
  });

  return await addToWhitelist(addresses);
}

​
Check if Address is Whitelisted

async function isAddressWhitelisted(address, currency, memo = null) {
  const whitelist = await getWhitelistedAddresses(currency);

  return whitelist.some(
    w => w.walletAddress === address &&
         (memo === null || w.walletMemo === memo)
  );
}

const isWhitelisted = await isAddressWhitelisted(
  'rNxp4h8apvRis6mJf9Sh8C6iRxfrDWN7AA',
  'xrp',
  '66'
);

​
Clean Up Unused Addresses

async function removeUnusedAddresses(currency, daysUnused = 90) {
  const whitelist = await getWhitelistedAddresses(currency);
  const cutoffDate = new Date();
  cutoffDate.setDate(cutoffDate.getDate() - daysUnused);

  const toRemove = whitelist.filter(w => {
    if (!w.lastUsedAt) return false;

    const lastUsed = new Date(w.lastUsedAt);
    return lastUsed < cutoffDate;
  });

  if (toRemove.length > 0) {
    const ids = toRemove.map(w => w.id);
    await removeFromWhitelist(ids);
    console.log(`Removed ${ids.length} unused addresses`);
  }
}

​
Edge Cases

​
Duplicate Addresses

Attempting to whitelist an already-whitelisted address: 
const whitelist = await getWhitelistedAddresses('xrp');
const isDuplicate = whitelist.some(
  w => w.walletAddress === newAddress && w.walletMemo === newMemo
);

if (isDuplicate) {
  console.log('Address already whitelisted');
}

​
Maximum Whitelist Size

Platforms may impose limits on whitelist size. Check current count: 
const MAX_WHITELIST_SIZE = 100;

const current = await getWhitelistedAddresses(currency);
if (current.length >= MAX_WHITELIST_SIZE) {
  throw new Error('Whitelist limit reached. Remove unused addresses first.');
}