Skip to main content
PUT
/
v1
/
wallet
/
internal
/
card_linked
/
priority
{
  "success": true
}

​
Overview

Update the charging priority of card-linked internal wallets. Priority determines which wallet is charged first during card transactions. Lower priority numbers are charged before higher numbers (priority 1 is charged before priority 2). How Priority Works:
  1. Transaction is initiated
  2. Platform attempts to charge wallet with priority 1
  3. If insufficient balance or failure, moves to priority 2
  4. Process continues until transaction succeeds or all wallets exhausted

​
Authentication

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

​
Request Body

​
wallets
array
required
Array of wallet priority updates

​
Response

​
success
boolean
Whether priority update was successful
{
  "success": true
}

​
Code Examples

curl -X PUT "https://dev.api.baanx.com/v1/wallet/internal/card_linked/priority" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wallets": [
      {
        "addressId": "7c1839ee-918e-4787-b74f-deeb48ead58b",
        "priority": 1
      },
      {
        "addressId": "1693a6da-5945-4461-ba1c-0b9891f78848",
        "priority": 2
      }
    ]
  }'

​
Use Cases

​
Reorder All Wallets

async function reorderWallets(newOrder) {
  const priorities = newOrder.map((addressId, index) => ({
    addressId,
    priority: index + 1
  }));

  await updateWalletPriority(priorities);
}

await reorderWallets([
  '7c1839ee-918e-4787-b74f-deeb48ead58b',
  '1693a6da-5945-4461-ba1c-0b9891f78848',
  'a8f3c2e1-445d-4a3b-9c7e-1f2d3e4a5b6c'
]);

​
Swap Two Wallet Priorities

async function swapWalletPriorities(wallet1, wallet2) {
  const temp = wallet1.priority;

  await updateWalletPriority([
    { addressId: wallet1.addressId, priority: wallet2.priority },
    { addressId: wallet2.addressId, priority: temp }
  ]);
}

​
Move Wallet to Top Priority

async function moveToTopPriority(walletId) {
  const linked = await fetch('/v1/wallet/internal/card_linked')
    .then(r => r.json());

  const priorities = linked
    .sort((a, b) => a.priority - b.priority)
    .map((w, index) => ({
      addressId: w.addressId,
      priority: w.addressId === walletId ? 1 : index + 2
    }));

  await updateWalletPriority(priorities);
}

​
Important Notes

Update All Wallets: You must provide priority values for ALL linked wallets, not just the ones you want to change. Omitted wallets may lose their linked status.
Unique Priorities: Each wallet must have a unique priority value. Duplicate priorities will result in a validation error.
Sequential Numbering: While not required, it’s recommended to use sequential numbering (1, 2, 3…) for clarity and consistency.

​
Best Practices

​
Maintain Sequential Order

function ensureSequentialPriorities(wallets) {
  return wallets
    .sort((a, b) => a.priority - b.priority)
    .map((wallet, index) => ({
      ...wallet,
      priority: index + 1
    }));
}

​
Validate Before Update

function validatePriorities(wallets) {
  const priorities = wallets.map(w => w.priority);
  const hasDuplicates = new Set(priorities).size !== priorities.length;

  if (hasDuplicates) {
    throw new Error('Duplicate priorities not allowed');
  }

  const hasGaps = priorities.length > 0 &&
    Math.max(...priorities) !== priorities.length;

  if (hasGaps) {
    console.warn('Priority sequence has gaps');
  }

  return true;
}