Manage Card-Linked Internal Wallets

[
  {
    "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
  }
]

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

string

required

Your public API client key

string

required

Bearer token for authentication

Response

string

Linked wallet identifier

string

Wallet blockchain address

string

Currency code (e.g., “sol”, “usdc”)

string

Blockchain network (e.g., “solana”, “ethereum”)

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"

import requests

url = "https://dev.api.baanx.com/v1/wallet/internal/card_linked"
headers = {
    "x-client-key": "YOUR_CLIENT_KEY",
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
}

response = requests.get(url, headers=headers)
linked_wallets = response.json()

print(f"Linked wallets: {len(linked_wallets)}")
for wallet in sorted(linked_wallets, key=lambda w: w['priority']):
    print(f"{wallet['priority']}. {wallet['currency'].upper()} on {wallet['network']}")

interface LinkedWallet {
  id: string;
  address: string;
  currency: string;
  network: string;
  priority: number;
}

async function getLinkedWallets(): Promise<LinkedWallet[]> {
  const response = await fetch(
    'https://dev.api.baanx.com/v1/wallet/internal/card_linked',
    {
      headers: {
        'x-client-key': 'YOUR_CLIENT_KEY',
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
      }
    }
  );

  return await response.json();
}

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

string

required

Wallet addressId from GET /v1/wallet/internal response

Response

boolean

Whether linking was successful

{
  "success": true
}

{
  "message": "Maximum 5 wallets can be linked"
}

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

import requests

all_wallets = requests.get(
    "https://dev.api.baanx.com/v1/wallet/internal",
    headers=headers
).json()

usdc_wallet = next(w for w in all_wallets if w['currency'] == 'usdc')

link_data = {"addressId": usdc_wallet['addressId']}
response = requests.post(
    "https://dev.api.baanx.com/v1/wallet/internal/card_linked",
    headers=headers,
    json=link_data
)

if response.status_code == 201:
    print("Wallet linked to card successfully!")

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

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

DELETE - Unlink Internal Wallet from Card

Remove a wallet from card payment sources. The wallet remains available but won’t be used for card transactions.

Request Body

string

required

Wallet addressId to unlink

Response

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

unlink_data = {"addressId": "7c1839ee-918e-4787-b74f-deeb48ead58b"}
response = requests.delete(
    "https://dev.api.baanx.com/v1/wallet/internal/card_linked",
    headers=headers,
    json=unlink_data
)

if response.status_code == 200:
    print("Wallet unlinked from card")

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

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

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.

Update Linked Wallet Priority - Change charging order
Get Internal Wallets - View all available wallets

Overview

Authentication

User

Card

Orders

Wallet

Delegation

Consent

Referral

Webhooks

Manage Card-Linked Internal Wallets

Overview

GET - List Card-Linked Wallets

Authentication

Response

POST - Link Internal Wallet to Card

Request Body

Response

DELETE - Unlink Internal Wallet from Card

Request Body

Response

Complete Management Flow

Important Notes

​Overview

​GET - List Card-Linked Wallets

​Authentication

​Response

​POST - Link Internal Wallet to Card

​Request Body

​Response

​DELETE - Unlink Internal Wallet from Card

​Request Body

​Response

​Complete Management Flow

​Important Notes

​Related Endpoints

Overview

GET - List Card-Linked Wallets

Authentication

Response

POST - Link Internal Wallet to Card

Request Body

Response

DELETE - Unlink Internal Wallet from Card

Request Body

Response

Complete Management Flow

Important Notes

Related Endpoints