Skip to main content

​
Overview

Link internal (custodial) wallets to your card to use them as funding sources for card transactions. Users can link up to 5 wallets, with priority determining the order in which they are charged during purchases. Use Cases:
  • Enable card payments from specific wallets
  • Manage which currencies fund card transactions
  • Control payment source priority
  • Temporarily disable wallet usage for cards

​
GET - List Card-Linked Wallets

Retrieve all custodial wallets currently linked to the user’s card.

​
Authentication

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

​
Response

​
id
string
Linked wallet identifier
​
address
string
Wallet blockchain address
​
currency
string
Currency code (e.g., “sol”, “usdc”)
​
network
string
Blockchain network (e.g., “solana”, “ethereum”)
​
priority
number
Charging priority (lower numbers charged first)
[
  {
    "id": "1693a6da-5945-4461-ba1c-0b9891f78848",
    "address": "DfKNsYfrCEHb7ScJkuMTtPTeDiyjmBBm9NMHnbR7uFHz",
    "currency": "sol",
    "network": "solana",
    "priority": 1
  },
  {
    "id": "7c1839ee-918e-4787-b74f-deeb48ead58b",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb4",
    "currency": "usdc",
    "network": "ethereum",
    "priority": 2
  }
]

curl -X GET "https://dev.api.baanx.com/v1/wallet/internal/card_linked" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
POST - Link Internal Wallet to Card

Link a custodial wallet to the card as a payment source. Each user can link up to 5 wallets.

​
Request Body

​
addressId
string
required
Wallet addressId from GET /v1/wallet/internal response

​
Response

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

curl -X POST "https://dev.api.baanx.com/v1/wallet/internal/card_linked" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "addressId": "7c1839ee-918e-4787-b74f-deeb48ead58b"
  }'
Remove a wallet from card payment sources. The wallet remains available but won’t be used for card transactions.

​
Request Body

​
addressId
string
required
Wallet addressId to unlink

​
Response

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

curl -X DELETE "https://dev.api.baanx.com/v1/wallet/internal/card_linked" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "addressId": "7c1839ee-918e-4787-b74f-deeb48ead58b"
  }'

​
Complete Management Flow

async function manageCardWallets() {
  const allWallets = await fetch('/v1/wallet/internal')
    .then(r => r.json());

  const linkedWallets = await fetch('/v1/wallet/internal/card_linked')
    .then(r => r.json());

  const usdcWallet = allWallets.find(w => w.currency === 'usdc');

  const isLinked = linkedWallets.some(
    w => w.address === usdcWallet.address
  );

  if (!isLinked && linkedWallets.length < 5) {
    await fetch('/v1/wallet/internal/card_linked', {
      method: 'POST',
      body: JSON.stringify({ addressId: usdcWallet.addressId })
    });
    console.log('USDC wallet linked to card');
  }

  const orderedWallets = linkedWallets.sort((a, b) => a.priority - b.priority);
  console.log('Payment priority:', orderedWallets.map(w => w.currency));

  return {
    total: allWallets.length,
    linked: linkedWallets.length,
    available: 5 - linkedWallets.length
  };
}

​
Important Notes

Maximum Limit: Users can link up to 5 wallets to their card. Attempting to link more will result in an error.
Priority Management: Use the Update Linked Wallets Priority endpoint to control which wallet is charged first.
Unlinking Effects: Unlinking a wallet doesn’t delete it, only removes it as a card payment source. The wallet and its funds remain accessible.