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

# Custodial Wallets

> Platform-managed wallets with simplified user experience and whitelist-based security

## What are Custodial Wallets?

Custodial wallets are platform-managed blockchain wallets where private keys are securely held and managed by the service. Users interact with these wallets through simple API calls without needing wallet software, browser extensions, or blockchain knowledge.

## Key Benefits

<CardGroup cols={2}>
  <Card title="Simplified UX" icon="sparkles">
    No wallet software required. Users interact through your application's familiar interface.
  </Card>

  <Card title="Secure Key Management" icon="shield-halved">
    Private keys are encrypted and managed using enterprise-grade security infrastructure.
  </Card>

  <Card title="Whitelist Security" icon="list-check">
    Withdrawals restricted to pre-approved addresses, adding an extra security layer.
  </Card>

  <Card title="Multi-Network Support" icon="network-wired">
    Support for multiple blockchains from a single integration point.
  </Card>
</CardGroup>

## Custodial Wallet Types

### Internal Wallets

User-specific wallets holding cryptocurrency across various networks. Each user can have multiple internal wallets for different currencies and networks.

**Capabilities:**

* Create wallets on supported networks
* Receive crypto deposits
* Check balances
* Link to card for payments
* Withdraw to whitelisted addresses

[Learn more about Internal Wallets →](/guides/wallet/custodial/internal-wallets)

### Credit Wallets

Platform wallets holding user credits from refunds, transfers, or top-ups. Each user has one credit wallet per supported currency.

**Capabilities:**

* View balance
* Withdraw to whitelisted addresses (custodial environments)
* Use for card payments

### Reward Wallets

Platform wallets accumulating cashback, promotions, and incentives. Each user has one reward wallet per supported currency.

**Capabilities:**

* View balance
* Withdraw to whitelisted addresses (custodial environments)
* Use for card payments

## Security Model

Custodial wallets implement a whitelist-based security model:

```mermaid theme={null}
graph LR
    A[User] -->|1. Add Address| B[Whitelist]
    B -->|2. Verify| C[Approved Addresses]
    A -->|3. Initiate Withdrawal| D[Platform]
    D -->|4. Verify Against Whitelist| C
    C -->|5. Approve| E[Execute On-Chain]
    E -->|6. Send Funds| F[Whitelisted Address]
```

### How Whitelisting Works

1. **Add Address**: User submits external wallet address with beneficiary details
2. **Verification**: Platform validates address format and network compatibility
3. **Approval**: Address is added to user's approved whitelist
4. **Withdrawal**: User can only withdraw to addresses on their whitelist
5. **Tracking**: All withdrawals are tracked with beneficiary information

<Warning>
  Whitelist addresses cannot be modified once added. To change an address, remove the old entry and add a new one. Always verify addresses before whitelisting to prevent loss of funds.
</Warning>

## Card Linking

Internal wallets can be linked to cards for seamless cryptocurrency payments:

<Steps>
  <Step title="Create Internal Wallet">
    Set up an internal wallet for the desired network and currency.
  </Step>

  <Step title="Fund Wallet">
    Deposit cryptocurrency to the wallet address.
  </Step>

  <Step title="Link to Card">
    Connect the wallet to the user's card using the card linking API.
  </Step>

  <Step title="Set Priority">
    Configure which wallet is charged first when multiple wallets are linked.
  </Step>

  <Step title="Make Payments">
    Card transactions automatically deduct from linked wallets based on priority.
  </Step>
</Steps>

[Learn more about Card Linking →](/guides/wallet/custodial/card-linking)

## Supported Networks

| Network        | Currencies      | Memo Required | Notes                                         |
| -------------- | --------------- | ------------- | --------------------------------------------- |
| **Linea**      | USDC, USDT      | No            | Primary network, US routing available         |
| **Ethereum**   | USDC, USDT      | No            | Mainnet support                               |
| **Solana**     | USDC, USDT, SOL | No            | SPL token support                             |
| **XRP Ledger** | XRP             | Yes           | Destination tag required for all transactions |
| **Bitcoin**    | BTC             | No            | Native Bitcoin support                        |

<Note>
  Networks requiring memos (like XRP Ledger) return both `address` and `addressMemo` fields. Both are required for deposits and withdrawals.
</Note>

## Common Workflows

### Workflow 1: Simple Deposit and Card Payment

```mermaid theme={null}
sequenceDiagram
    participant User
    participant App
    participant API
    participant Blockchain
    participant Card

    User->>App: Request deposit address
    App->>API: POST /v1/wallet/internal
    API-->>App: Wallet created with address
    App-->>User: Display deposit address
    User->>Blockchain: Send crypto to address
    Blockchain-->>API: Confirm deposit
    API-->>App: Update balance
    User->>App: Link wallet to card
    App->>API: POST /v1/wallet/internal/card_linked
    API-->>App: Wallet linked
    User->>Card: Make purchase
    Card->>API: Charge linked wallet
```

### Workflow 2: Withdrawal to External Address

```mermaid theme={null}
sequenceDiagram
    participant User
    participant App
    participant API
    participant Blockchain

    User->>App: Request withdrawal
    App->>User: Prompt for address
    User->>App: Provide address + beneficiary
    App->>API: POST /v1/wallet/whitelist
    API-->>App: Address whitelisted
    User->>App: Confirm withdrawal
    App->>API: POST /v1/wallet/internal/withdraw
    API->>Blockchain: Execute transaction
    Blockchain-->>API: Confirm transaction
    API-->>App: Return txHash
    App-->>User: Display confirmation
```

## Priority Management

When multiple wallets are linked to a card, priority determines the charge order:

<CodeGroup>
  ```bash Get Priority theme={null}
  curl -X GET "https://api.example.com/v1/wallet/internal/card_linked/priority" \
    -H "x-client-key: YOUR_PUBLIC_KEY" \
    -H "Authorization: Bearer USER_ACCESS_TOKEN"
  ```

  ```json Response theme={null}
  {
    "wallets": [
      {
        "id": "wallet-1",
        "address": "0x123...",
        "currency": "usdc",
        "network": "linea",
        "priority": 1
      },
      {
        "id": "wallet-2",
        "address": "0x456...",
        "currency": "usdt",
        "network": "ethereum",
        "priority": 2
      }
    ]
  }
  ```
</CodeGroup>

**How Priority Works:**

1. Card transaction initiated
2. System attempts to charge wallet with priority 1
3. If insufficient balance, moves to priority 2
4. Process continues until transaction succeeds or all wallets exhausted

[Learn more about Priority Management →](/guides/wallet/custodial/card-linking#priority-management)

## Transaction History

View transaction history for any custodial wallet:

<CodeGroup>
  ```bash Internal Wallet History theme={null}
  curl -X GET "https://api.example.com/v1/wallet/history?walletId=098aeb90&walletType=INTERNAL&walletCurrency=usdc&page=0" \
    -H "x-client-key: YOUR_PUBLIC_KEY" \
    -H "Authorization: Bearer USER_ACCESS_TOKEN"
  ```

  ```bash Credit Wallet History theme={null}
  curl -X GET "https://api.example.com/v1/wallet/history?walletId=098aeb90&walletType=CREDIT&page=0" \
    -H "x-client-key: YOUR_PUBLIC_KEY" \
    -H "Authorization: Bearer USER_ACCESS_TOKEN"
  ```

  ```json Response theme={null}
  [
    {
      "name": "Card purchase",
      "amount": "25.50",
      "currency": "usdc",
      "sign": "debit",
      "date": "2024-02-02T15:01:09.091Z"
    },
    {
      "name": "Wallet deposit",
      "amount": "100.00",
      "currency": "usdc",
      "sign": "credit",
      "date": "2024-02-01T10:30:00.000Z"
    }
  ]
  ```
</CodeGroup>

<Note>
  History returns up to 10 transactions per page. Use the `page` parameter (zero-indexed) for pagination.
</Note>

## Error Handling

Common error scenarios and how to handle them:

### Insufficient Balance

```json theme={null}
{
  "error": "Insufficient balance",
  "code": "WALLET_INSUFFICIENT_BALANCE",
  "message": "Wallet balance is insufficient for this withdrawal"
}
```

**Solution:** Check wallet balance before attempting withdrawal or prompt user to fund wallet.

### Address Not Whitelisted

```json theme={null}
{
  "error": "Address not whitelisted",
  "code": "WALLET_ADDRESS_NOT_WHITELISTED",
  "message": "Withdrawal address must be whitelisted before use"
}
```

**Solution:** Add address to whitelist first using `POST /v1/wallet/whitelist`.

### Invalid Network

```json theme={null}
{
  "error": "Unsupported network",
  "code": "WALLET_UNSUPPORTED_NETWORK",
  "message": "The specified network is not supported"
}
```

**Solution:** Verify network name against supported networks list and ensure proper environment configuration.

### Maximum Linked Wallets

```json theme={null}
{
  "error": "Maximum linked wallets reached",
  "code": "WALLET_MAX_LINKED",
  "message": "User has reached the maximum number of linked wallets (5)"
}
```

**Solution:** Unlink an existing wallet before linking a new one, or prompt user to manage their linked wallets.

## Best Practices

<AccordionGroup>
  <Accordion title="Always Verify Addresses">
    Before adding an address to the whitelist, verify it's correct and on the intended network. Blockchain transactions are irreversible.
  </Accordion>

  <Accordion title="Use Descriptive Whitelist Names">
    Give each whitelisted address a clear, descriptive name (e.g., "Coinbase Main Account" or "Hardware Wallet #1") to help users identify addresses later.
  </Accordion>

  <Accordion title="Implement Balance Checks">
    Check wallet balance before initiating withdrawals to provide better user feedback and avoid failed transactions.
  </Accordion>

  <Accordion title="Handle Network-Specific Requirements">
    Some networks (like XRP) require memos/destination tags. Always include these fields when present.
  </Accordion>

  <Accordion title="Set Sensible Priority Orders">
    Configure wallet priority based on user preferences or fee optimization. Update priority when users change their preferences.
  </Accordion>

  <Accordion title="Display Transaction History">
    Show transaction history to help users track their activity and verify transactions.
  </Accordion>

  <Accordion title="Implement Withdrawal Limits">
    Consider implementing daily/monthly withdrawal limits for additional security, especially for high-value accounts.
  </Accordion>
</AccordionGroup>

## US Environment Routing

For US-based users and compliance requirements, use the US environment:

<Tabs>
  <Tab title="Header Method">
    ```bash theme={null}
    curl -X GET "https://api.example.com/v1/wallet/internal" \
      -H "x-client-key: YOUR_PUBLIC_KEY" \
      -H "Authorization: Bearer USER_ACCESS_TOKEN" \
      -H "x-us-env: true"
    ```
  </Tab>

  <Tab title="Query Parameter Method">
    ```bash theme={null}
    curl -X GET "https://api.example.com/v1/wallet/internal?region=us" \
      -H "x-client-key: YOUR_PUBLIC_KEY" \
      -H "Authorization: Bearer USER_ACCESS_TOKEN"
    ```
  </Tab>
</Tabs>

<Note>
  The US environment automatically routes Linea network operations to US-specific infrastructure while maintaining full API compatibility.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Internal Wallets" icon="wallet" href="/guides/wallet/custodial/internal-wallets">
    Learn how to create and manage internal wallets
  </Card>

  <Card title="Card Linking" icon="credit-card" href="/guides/wallet/custodial/card-linking">
    Connect wallets to cards for seamless payments
  </Card>

  <Card title="Whitelist Management" icon="list-check" href="/guides/wallet/custodial/whitelist">
    Manage approved withdrawal addresses
  </Card>

  <Card title="Withdrawals" icon="arrow-right-from-bracket" href="/guides/wallet/custodial/withdrawals">
    Execute withdrawals to external addresses
  </Card>
</CardGroup>