> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baanx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get/Create Internal Wallets

> Retrieve or create custodial wallets managed by the Baanx platform

## 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)

<Warning>
  **Custodial Nature**: The platform holds the private keys for internal wallets. For non-custodial solutions where users control their own keys, see [External Wallets](/api-reference/wallet/external).
</Warning>

***

## GET - Retrieve Internal Wallets

Retrieve all custodial wallets for the authenticated user.

### Authentication

<ParamField header="x-client-key" type="string" required>
  Your public API client key
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

### Query Parameters

<ParamField query="x-us-env" type="boolean" default={false}>
  Route to US backend environment
</ParamField>

### Response

Returns an array of internal wallet objects.

<ResponseField name="id" type="string">
  Unique identifier for the wallet
</ResponseField>

<ResponseField name="balance" type="string">
  Current balance (decimal string)
</ResponseField>

<ResponseField name="currency" type="string">
  Currency code (e.g., "xrp", "usdc", "sol")
</ResponseField>

<ResponseField name="address" type="string">
  Blockchain address for deposits
</ResponseField>

<ResponseField name="addressMemo" type="string">
  Memo/destination tag (for XRP, Stellar, etc.)
</ResponseField>

<ResponseField name="addressId" type="string">
  Internal address identifier
</ResponseField>

<ResponseField name="type" type="string">
  Wallet type, always "INTERNAL"
</ResponseField>

### Response Example

<ResponseExample>
  ```json 200 - Success theme={null}
  [
    {
      "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"
    }
  ]
  ```

  ```json 401 - Authentication Error theme={null}
  {
    "message": "Not authenticated"
  }
  ```

  ```json 422 - Validation Error theme={null}
  {
    "message": "Validation failed"
  }
  ```
</ResponseExample>

### Code Examples

<CodeGroup>
  ```bash cURL - Get Wallets theme={null}
  curl -X GET "https://dev.api.baanx.com/v1/wallet/internal" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```python Python - Get Wallets theme={null}
  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']}")
  ```

  ```typescript TypeScript - Get Wallets theme={null}
  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();
  }
  ```
</CodeGroup>

***

## POST - Create Internal Wallets

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

### Authentication

<ParamField header="x-client-key" type="string" required>
  Your public API client key
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

### Query Parameters

<ParamField query="x-us-env" type="boolean" default={false}>
  Route to US backend environment
</ParamField>

### Request Body

<ParamField body="wallets" type="array" required>
  Array of wallet specifications to create

  <Expandable title="Wallet Object">
    <ParamField body="network" type="string" required>
      Blockchain network (e.g., "xrp", "solana", "ethereum")
    </ParamField>

    <ParamField body="currency" type="string" required>
      Currency code (e.g., "xrp", "usdc", "eth")
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Whether wallet creation was successful
</ResponseField>

### Response Example

<ResponseExample>
  ```json 201 - Created theme={null}
  {
    "success": true
  }
  ```

  ```json 401 - Authentication Error theme={null}
  {
    "message": "Not authenticated"
  }
  ```

  ```json 422 - Validation Error theme={null}
  {
    "message": "Invalid network or currency combination"
  }
  ```
</ResponseExample>

### Code Examples

<CodeGroup>
  ```bash cURL - Create Wallets theme={null}
  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"
        }
      ]
    }'
  ```

  ```python Python - Create Wallets theme={null}
  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)}")
  ```

  ```typescript TypeScript - Create Wallets theme={null}
  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' }
  ]);
  ```
</CodeGroup>

***

## Deposit Instructions

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

<CodeGroup>
  ```javascript Display Deposit Info theme={null}
  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)`);
  }
  ```

  ```python Python - Deposit Instructions theme={null}
  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))
  ```
</CodeGroup>

<Warning>
  **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.
</Warning>

## Important Notes

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

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

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

## 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:

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

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

## Related Endpoints

* [Withdraw from Internal Wallet](/api-reference/wallet/internal-withdraw) - Send funds to external address
* [Link Internal Wallet to Card](/api-reference/wallet/internal-card-linked) - Use wallet for card payments
* [Get Wallet History](/api-reference/wallet/history) - View transaction history
* [Whitelist External Addresses](/api-reference/wallet/whitelist) - Manage approved withdrawal destinations