Skip to main content
GET
/
v1
/
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>"
    }
  ]
}
'
[
  {
    "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"
  }
]

​
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

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

​
Query Parameters

​
x-us-env
boolean
default:false
Route to US backend environment

​
Response

Returns an array of internal wallet objects.
​
id
string
Unique identifier for the wallet
​
balance
string
Current balance (decimal string)
​
currency
string
Currency code (e.g., “xrp”, “usdc”, “sol”)
​
address
string
Blockchain address for deposits
​
addressMemo
string
Memo/destination tag (for XRP, Stellar, etc.)
​
addressId
string
Internal address identifier
​
type
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"
  }
]

​
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"

​
POST - Create Internal Wallets

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

​
Authentication

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

​
Query Parameters

​
x-us-env
boolean
default:false
Route to US backend environment

​
Request Body

​
wallets
array
required
Array of wallet specifications to create

​
Response

​
success
boolean
Whether wallet creation was successful

​
Response Example

{
  "success": true
}

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

​
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)`);
}
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;
}