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

# Wallet Management Overview

> Understand custodial and non-custodial wallet models and choose the right approach for your integration

## Introduction

The platform supports two distinct wallet management models, each designed for different use cases and user experiences. Understanding these models is essential for choosing the right integration approach for your application.

## Wallet Models

<CardGroup cols={2}>
  <Card title="Custodial Wallets" icon="lock" href="/guides/wallet/custodial">
    Platform-managed keys with simplified UX. Ideal for users who want convenience without managing private keys.
  </Card>

  <Card title="Non-Custodial Wallets" icon="wallet" href="/guides/wallet/non-custodial">
    User-controlled keys with full self-custody. Perfect for users who want complete control of their assets.
  </Card>
</CardGroup>

## Custodial vs Non-Custodial

| Feature             | Custodial                               | Non-Custodial                                |
| ------------------- | --------------------------------------- | -------------------------------------------- |
| **Key Management**  | Platform manages private keys           | User controls private keys                   |
| **User Experience** | Simple, no wallet software needed       | Requires wallet software (MetaMask, Phantom) |
| **Security Model**  | Platform-secured, whitelist-based       | User-secured, delegation-based               |
| **Withdrawals**     | Whitelist addresses only                | Any address (subject to allowance)           |
| **Card Payments**   | Direct wallet linking                   | Delegation approval required                 |
| **Best For**        | Mainstream users, simplified onboarding | Crypto-native users, DeFi integration        |

## When to Use Each Model

### Choose Custodial When:

* Your users are new to cryptocurrency
* You want the simplest possible user experience
* You need to control withdrawal destinations
* Your users don't want to manage wallet software
* Compliance requires strict address whitelisting

### Choose Non-Custodial When:

* Your users are cryptocurrency-experienced
* Self-custody is a core value proposition
* Users need flexibility in withdrawal destinations
* You're integrating with existing Web3 applications
* Users demand full control over their private keys

## Environment-Specific Features

Both wallet models support environment-specific configuration through the `x-us-env` header or `region=us` query parameter:

<Tabs>
  <Tab title="Global Environment">
    Default environment. All wallet operations route to global infrastructure.

    ```bash theme={null}
    GET /v1/wallet/internal
    Headers:
      x-client-key: YOUR_PUBLIC_KEY
      Authorization: Bearer USER_ACCESS_TOKEN
    ```
  </Tab>

  <Tab title="US Environment">
    US-specific routing. Use for US-based users and compliance requirements.

    ```bash theme={null}
    GET /v1/wallet/internal
    Headers:
      x-client-key: YOUR_PUBLIC_KEY
      Authorization: Bearer USER_ACCESS_TOKEN
      x-us-env: true
    ```

    Or via query parameter:

    ```bash theme={null}
    GET /v1/wallet/internal?region=us
    ```
  </Tab>
</Tabs>

<Note>
  The `x-us-env: true` header or `region=us` parameter automatically routes Linea network operations to the US-specific Linea environment. This ensures compliance with regional requirements.
</Note>

## Wallet Types

Both custodial and non-custodial models support multiple wallet types:

### Internal Wallets (Custodial)

Platform-managed wallets holding user crypto assets. Support multiple networks and currencies. Can be linked to cards for payments.

**Key Operations:**

* Create new internal wallets
* View balances across networks
* Link wallets to cards
* Withdraw to whitelisted addresses

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

### External Wallets (Non-Custodial)

User-controlled wallets registered via delegation. Users maintain full custody while granting spending authority for card payments.

**Key Operations:**

* Register external wallets via delegation
* View allowances and balances
* Manage withdrawal priority
* Withdraw credit/rewards to external wallets

[Learn more about External Wallets →](/guides/wallet/non-custodial/external-wallets)

### Credit Wallets

Platform wallets holding user credits from various sources (refunds, top-ups, transfers). Available in both custodial and non-custodial environments.

**Key Operations:**

* View credit balance
* Withdraw to whitelisted addresses (custodial)
* Withdraw to registered external wallets (non-custodial)

### Reward Wallets

Platform wallets accumulating cashback, incentives, and promotional credits. Similar to credit wallets but specifically for earned rewards.

**Key Operations:**

* View reward balance
* Withdraw to whitelisted addresses (custodial)
* Withdraw to registered external wallets (non-custodial)

## Supported Networks and Currencies

The platform supports multiple blockchain networks and cryptocurrencies:

| Network        | Currencies | Type    | Notes                                 |
| -------------- | ---------- | ------- | ------------------------------------- |
| **Linea**      | USDC, USDT | EVM     | Primary network, US routing available |
| **Ethereum**   | USDC, USDT | EVM     | Mainnet support                       |
| **Solana**     | USDC, USDT | Non-EVM | SPL token support                     |
| **XRP Ledger** | XRP        | Non-EVM | Requires destination tags (memo)      |

<Warning>
  Network and currency availability may vary by environment and configuration. Contact support to confirm specific network availability for your integration.
</Warning>

## Common Operations

### Transaction History

View transaction history for any wallet type:

```bash theme={null}
GET /v1/wallet/history?walletId={id}&walletType=INTERNAL&page=0
```

**API Reference:** [`GET /v1/wallet/history`](/api-reference/wallet/history)

**Supported Wallet Types:**

* `CREDIT` - Credit wallet transactions
* `REWARD` - Reward wallet transactions
* `INTERNAL` - Internal wallet transactions (requires `walletCurrency` parameter)

**Response:**

```json 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"
  }
]
```

<Note>
  Transaction history is paginated with 10 transactions per page. Use the `page` parameter (zero-indexed) to navigate through history.
</Note>

## Priority Management

Both custodial and non-custodial models support priority ordering for multiple wallets:

**Custodial:** Control which linked wallet is charged first for card transactions.

**Non-Custodial:** Control which external wallet receives credit/reward withdrawals first.

Priority works the same way in both models:

* Lower numbers = higher priority (1 is charged/paid before 2)
* Platform attempts wallets in priority order
* Insufficient balance/allowance triggers next priority wallet

## Security Best Practices

### Custodial Model Security

<Card title="Whitelist Management" icon="shield-check">
  Only whitelist addresses you control. Verify each address carefully before adding to prevent loss of funds.
</Card>

<Card title="Beneficiary Verification" icon="user-check">
  Ensure beneficiary names match the actual owner of withdrawal addresses for compliance tracking.
</Card>

### Non-Custodial Model Security

<Card title="Delegation Limits" icon="gauge">
  Set appropriate allowance limits when delegating. You can always increase limits later through redelegation.
</Card>

<Card title="Signature Verification" icon="signature">
  Never share private keys. The platform only requires transaction signatures, not private key access.
</Card>

## Next Steps

<CardGroup cols={2}>
  <Card title="Custodial Wallets" icon="lock" href="/guides/wallet/custodial">
    Explore custodial wallet operations including internal wallets, card linking, whitelists, and withdrawals.
  </Card>

  <Card title="Non-Custodial Wallets" icon="wallet" href="/guides/wallet/non-custodial">
    Learn about external wallet registration, delegation, and priority management.
  </Card>

  <Card title="Delegation Guide" icon="link" href="/guides/delegation">
    Detailed guide on implementing the delegation flow for non-custodial wallets.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Complete API documentation for all wallet endpoints.
  </Card>
</CardGroup>