Get/Create Internal Wallets

curl --request GET \
  --url https://api.example.com/v1/wallet/internal \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'x-client-key: <x-client-key>' \
  --data '
{
  "wallets": [
    {
      "network": "<string>",
      "currency": "<string>"
    }
  ]
}
'

import requests

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

payload = { "wallets": [
        {
            "network": "<string>",
            "currency": "<string>"
        }
    ] }
headers = {
    "x-client-key": "<x-client-key>",
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'GET',
  headers: {
    'x-client-key': '<x-client-key>',
    Authorization: '<authorization>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({wallets: [{network: '<string>', currency: '<string>'}]})
};

fetch('https://api.example.com/v1/wallet/internal', 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/internal",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => json_encode([
    'wallets' => [
        [
                'network' => '<string>',
                'currency' => '<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/internal"

	payload := strings.NewReader("{\n  \"wallets\": [\n    {\n      \"network\": \"<string>\",\n      \"currency\": \"<string>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("GET", 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.get("https://api.example.com/v1/wallet/internal")
  .header("x-client-key", "<x-client-key>")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"wallets\": [\n    {\n      \"network\": \"<string>\",\n      \"currency\": \"<string>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

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

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

[
  {
    "id": "098aeb90-e7f7-4f81-bc2e-4963330122c5",
    "balance": "125.50",
    "currency": "xrp",
    "address": "rNxp4h8apvRis6mJf9Sh8C6iRxfrDWN7AA",
    "addressMemo": "78",
    "addressId": "0x0a4b21fa733e9aeaddbf070302a85c559de13c4c",
    "type": "INTERNAL"
  },
  {
    "id": "7c1839ee-918e-4787-b74f-deeb48ead58b",
    "balance": "500.00",
    "currency": "usdc",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb4",
    "addressMemo": null,
    "addressId": "7c1839ee-918e-4787-b74f-deeb48ead58b",
    "type": "INTERNAL"
  }
]

{
  "message": "Not authenticated"
}

{
  "message": "Validation failed"
}

GET

wallet

internal

Get/Create Internal Wallets

curl --request GET \
  --url https://api.example.com/v1/wallet/internal \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'x-client-key: <x-client-key>' \
  --data '
{
  "wallets": [
    {
      "network": "<string>",
      "currency": "<string>"
    }
  ]
}
'

import requests

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

payload = { "wallets": [
        {
            "network": "<string>",
            "currency": "<string>"
        }
    ] }
headers = {
    "x-client-key": "<x-client-key>",
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'GET',
  headers: {
    'x-client-key': '<x-client-key>',
    Authorization: '<authorization>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({wallets: [{network: '<string>', currency: '<string>'}]})
};

fetch('https://api.example.com/v1/wallet/internal', 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/internal",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => json_encode([
    'wallets' => [
        [
                'network' => '<string>',
                'currency' => '<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/internal"

	payload := strings.NewReader("{\n  \"wallets\": [\n    {\n      \"network\": \"<string>\",\n      \"currency\": \"<string>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("GET", 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.get("https://api.example.com/v1/wallet/internal")
  .header("x-client-key", "<x-client-key>")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"wallets\": [\n    {\n      \"network\": \"<string>\",\n      \"currency\": \"<string>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

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

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

[
  {
    "id": "098aeb90-e7f7-4f81-bc2e-4963330122c5",
    "balance": "125.50",
    "currency": "xrp",
    "address": "rNxp4h8apvRis6mJf9Sh8C6iRxfrDWN7AA",
    "addressMemo": "78",
    "addressId": "0x0a4b21fa733e9aeaddbf070302a85c559de13c4c",
    "type": "INTERNAL"
  },
  {
    "id": "7c1839ee-918e-4787-b74f-deeb48ead58b",
    "balance": "500.00",
    "currency": "usdc",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb4",
    "addressMemo": null,
    "addressId": "7c1839ee-918e-4787-b74f-deeb48ead58b",
    "type": "INTERNAL"
  }
]

{
  "message": "Not authenticated"
}

{
  "message": "Validation failed"
}

Overview

Internal wallets are custodial wallets where the Baanx platform securely manages private keys on behalf of users. Each wallet has a unique blockchain address for deposits, and users can create multiple wallets across different networks and currencies. Wallet Features:

Platform-managed private keys (custodial)
Unique deposit addresses per currency/network
Support for memo/destination tag networks (XRP, Stellar, etc.)
Multi-currency and multi-network support
Automatic balance tracking

Supported Networks & Currencies:

XRP Ledger (XRP)
Stellar (XLM)
Solana (SOL, USDC, USDT)
Ethereum/EVM chains (ETH, USDC, USDT)
And more (check platform documentation for current list)

Custodial Nature: The platform holds the private keys for internal wallets. For non-custodial solutions where users control their own keys, see External Wallets.

GET - Retrieve Internal Wallets

Retrieve all custodial wallets for the authenticated user.

Authentication

string

required

Your public API client key

string

required

Bearer token for authentication

Query Parameters

boolean

default:false

Route to US backend environment

Response

Returns an array of internal wallet objects.

string

Unique identifier for the wallet

string

Current balance (decimal string)

string

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

string

Blockchain address for deposits

string

Memo/destination tag (for XRP, Stellar, etc.)

string

Internal address identifier

string

Wallet type, always “INTERNAL”

Response Example

[
  {
    "id": "098aeb90-e7f7-4f81-bc2e-4963330122c5",
    "balance": "125.50",
    "currency": "xrp",
    "address": "rNxp4h8apvRis6mJf9Sh8C6iRxfrDWN7AA",
    "addressMemo": "78",
    "addressId": "0x0a4b21fa733e9aeaddbf070302a85c559de13c4c",
    "type": "INTERNAL"
  },
  {
    "id": "7c1839ee-918e-4787-b74f-deeb48ead58b",
    "balance": "500.00",
    "currency": "usdc",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb4",
    "addressMemo": null,
    "addressId": "7c1839ee-918e-4787-b74f-deeb48ead58b",
    "type": "INTERNAL"
  }
]

{
  "message": "Not authenticated"
}

{
  "message": "Validation failed"
}

Code Examples

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

import requests

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

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

for wallet in wallets:
    print(f"{wallet['currency'].upper()}: {wallet['balance']}")
    print(f"  Address: {wallet['address']}")
    if wallet['addressMemo']:
        print(f"  Memo: {wallet['addressMemo']}")

interface InternalWallet {
  id: string;
  balance: string;
  currency: string;
  address: string;
  addressMemo: string | null;
  addressId: string;
  type: 'INTERNAL';
}

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

  return await response.json();
}

POST - Create Internal Wallets

Create new custodial wallets for specific network and currency combinations. You can create multiple wallets in a single request.

Authentication

string

required

Your public API client key

string

required

Bearer token for authentication

Query Parameters

boolean

default:false

Route to US backend environment

Request Body

array

required

Array of wallet specifications to create

Show Wallet Object

string

required

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

string

required

Currency code (e.g., “xrp”, “usdc”, “eth”)

Response

boolean

Whether wallet creation was successful

Response Example

{
  "success": true
}

{
  "message": "Not authenticated"
}

{
  "message": "Invalid network or currency combination"
}

Code Examples

curl -X POST "https://dev.api.baanx.com/v1/wallet/internal" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wallets": [
      {
        "network": "xrp",
        "currency": "xrp"
      },
      {
        "network": "solana",
        "currency": "usdc"
      }
    ]
  }'

import requests

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

data = {
    "wallets": [
        {"network": "xrp", "currency": "xrp"},
        {"network": "solana", "currency": "usdc"}
    ]
}

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

if response.status_code == 201:
    print("Wallets created successfully!")

    wallets = requests.get(url, headers=headers).json()
    print(f"Total wallets: {len(wallets)}")

interface CreateWalletRequest {
  wallets: Array<{
    network: string;
    currency: string;
  }>;
}

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

  if (!response.ok) throw new Error('Failed to create wallets');

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

await createInternalWallets([
  { network: 'xrp', currency: 'xrp' },
  { network: 'solana', currency: 'usdc' }
]);

Deposit Instructions

When users want to deposit funds to an internal wallet, provide them with the appropriate address and memo information:

function getDepositInstructions(wallet) {
  const instructions = {
    currency: wallet.currency.toUpperCase(),
    network: wallet.network || wallet.currency.toUpperCase(),
    address: wallet.address
  };

  if (wallet.addressMemo) {
    instructions.memo = wallet.addressMemo;
    instructions.warning = `IMPORTANT: Include memo ${wallet.addressMemo} with your deposit`;
  }

  return instructions;
}

const wallet = wallets.find(w => w.currency === 'xrp');
const deposit = getDepositInstructions(wallet);

console.log(`Send ${deposit.currency} to:`);
console.log(`Address: ${deposit.address}`);
if (deposit.memo) {
  console.log(`Memo/Tag: ${deposit.memo} (REQUIRED)`);
}

def format_deposit_instructions(wallet):
    currency = wallet['currency'].upper()
    address = wallet['address']
    memo = wallet.get('addressMemo')

    instructions = f"""
    Deposit {currency}

    Address: {address}
    """

    if memo:
        instructions += f"""
    Memo/Destination Tag: {memo}

    ⚠️ IMPORTANT: You MUST include the memo/destination tag.
    Deposits without the correct memo cannot be credited to your account.
    """

    return instructions

xrp_wallet = next(w for w in wallets if w['currency'] == 'xrp')
print(format_deposit_instructions(xrp_wallet))

Memo Requirements: For networks that use memos/destination tags (XRP, Stellar, etc.), users MUST include the addressMemo value. Deposits without the correct memo cannot be automatically credited.

Important Notes

Wallet Creation: Creating a wallet generates blockchain addresses and initializes tracking. This may take a few seconds. Poll GET endpoint to verify creation.

Multiple Wallets: Users can create multiple wallets for the same currency on different networks (e.g., USDC on Ethereum and USDC on Solana).

Address Reuse: Wallet addresses are permanent and can be reused for multiple deposits. Users should save their deposit addresses for future use.

Edge Cases

Duplicate Wallet Creation

Attempting to create a wallet that already exists:

API typically returns success without creating duplicate
Use GET endpoint first to check existing wallets
Safe to retry wallet creation requests

Network-Currency Compatibility

Not all currency/network combinations are valid:

const validCombinations = {
  'xrp': ['xrp'],
  'usdc': ['ethereum', 'solana', 'polygon'],
  'eth': ['ethereum'],
  'sol': ['solana']
};

function isValidCombination(network, currency) {
  return validCombinations[currency]?.includes(network) || false;
}

Withdraw from Internal Wallet - Send funds to external address
Link Internal Wallet to Card - Use wallet for card payments
Get Wallet History - View transaction history
Whitelist External Addresses - Manage approved withdrawal destinations

Overview

Authentication

User

Card

Orders

Wallet

Delegation

Consent

Referral

Webhooks

Get/Create Internal Wallets

Overview

GET - Retrieve Internal Wallets

Authentication

Query Parameters

Response

Response Example

Code Examples

POST - Create Internal Wallets

Authentication

Query Parameters

Request Body

Response

Response Example

Code Examples

Deposit Instructions

Important Notes

Edge Cases

Duplicate Wallet Creation

Network-Currency Compatibility

​Overview

​GET - Retrieve Internal Wallets

​Authentication

​Query Parameters

​Response

​Response Example

​Code Examples

​POST - Create Internal Wallets

​Authentication

​Query Parameters

​Request Body

​Response

​Response Example

​Code Examples

​Deposit Instructions

​Important Notes

​Edge Cases

​Duplicate Wallet Creation

​Network-Currency Compatibility

​Related Endpoints

Overview

GET - Retrieve Internal Wallets

Authentication

Query Parameters

Response

Response Example

Code Examples

POST - Create Internal Wallets

Authentication

Query Parameters

Request Body

Response

Response Example

Code Examples

Deposit Instructions

Important Notes

Edge Cases

Duplicate Wallet Creation

Network-Currency Compatibility

Related Endpoints