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

# Deposit Addresses

> Deposit addresses are unique blockchain addresses generated from your master wallet. Each address can be assigned to a specific customer, invoice, or use case, enabling precise payment tracking and automated reconciliation.

## Overview

```mermaid theme={null}
flowchart LR
    subgraph Treasury["Your Treasury"]
        MW[Master Wallet\nMain Account]
    end

    subgraph Addresses["Deposit Addresses"]
        DA1[Customer A\nDeposit Address]
        DA2[Customer B\nDeposit Address]
        DA3[Invoice #12345\nDeposit Address]
        DA4[Refund Address]
    end

    subgraph Payments["Incoming Payments"]
        P1[$500 USDC]
        P2[$1,000 USDC]
        P3[$250 USDC]
        P4[$100 USDC]
    end

    MW --> DA1
    MW --> DA2
    MW --> DA3
    MW --> DA4

    DA1 --> P1
    DA2 --> P2
    DA3 --> P3
    DA4 --> P4
```

## Why Use Deposit Addresses?

<CardGroup cols={2}>
  <Card title="🎯 Payment Tracking" icon="target">
    Each address is unique per customer or invoice, making it easy to identify who paid and for what
  </Card>

  <Card title="🔄 Automated Reconciliation" icon="automation">
    Match incoming payments to specific customers automatically without manual intervention
  </Card>

  <Card title="🔒 Privacy & Security" icon="shield">
    Customers don't share addresses; each transaction uses a unique address for better privacy
  </Card>

  <Card title="📊 Analytics" icon="chart">
    Track payment behavior per customer, identify trends, and optimize your payment flow
  </Card>
</CardGroup>

## How It Works

```mermaid theme={null}
sequenceDiagram
    participant Customer
    participant YourApp as Your Application
    participant XentFi as XentFi API
    participant Blockchain as Blockchain

    Customer->>YourApp: Initiates payment
    YourApp->>XentFi: Create deposit address
    XentFi-->>YourApp: Returns unique address
    YourApp-->>Customer: Display address to customer
    Customer->>Blockchain: Send crypto to address
    Blockchain->>XentFi: Detects incoming transaction
    XentFi->>YourApp: Webhook notification
    YourApp->>Customer: Confirm payment received
```

## Use Cases

### Per-Customer Addresses

Assign a permanent deposit address to each customer for recurring payments:

| Use Case             | Benefit                                    |
| -------------------- | ------------------------------------------ |
| Subscription billing | Same address for all subscription payments |
| VIP customers        | Faster checkout experience                 |
| Business accounts    | Easy reconciliation per client             |

### Per-Invoice Addresses

Generate a unique address for every invoice:

| Use Case                | Benefit                            |
| ----------------------- | ---------------------------------- |
| One-time payments       | Clear payment-to-invoice mapping   |
| Marketplace settlements | Track which order paid             |
| Event tickets           | Match payment to specific attendee |

### Refund Addresses

Whitelist addresses for processing refunds:

| Use Case             | Benefit                        |
| -------------------- | ------------------------------ |
| Customer refunds     | Pre-verified addresses only    |
| Exchange withdrawals | Secure withdrawal destinations |
| Partner payouts      | Automated distribution         |

## Creating Deposit Addresses

### Basic Creation

<CodeGroup>
  ```bash theme={null}
  curl -X POST https://api.xentfi.com/v1/addresses \
    -H "apiKey: your-api-key" \
    -H "orgId: your-org-id" \
    -H "Content-Type: application/json" \
    -d '{
      "masterId": "your-master-wallet-id",
      "name": "Customer: john@example.com"
    }'
  ```
</CodeGroup>

<CodeGroup>
  ```json theme={null}
  {
      "data": {
          "id": "addr_123e4567-e89b-12d3-a456-426614174000",
          "name": "Customer: john@example.com",
          "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
          "masterWalletId": "your-master-wallet-id",
          "blockchain": {
              "id": "eth-mainnet",
              "name": "Ethereum",
              "chainId": 1
          },
          "createdAt": "2024-01-15T10:30:00.000Z"
      }
  }
  ```
</CodeGroup>

## Best Practices

### Address Management

<AccordionGroup>
  <Accordion title="Naming Convention">
    Use consistent naming patterns to easily identify addresses:

    * `customer_{customerId}` for recurring customers
    * `invoice_{invoiceId}` for one-time invoices
    * `order_{orderId}` for e-commerce orders
    * `refund_{transactionId}` for refund addresses
  </Accordion>

  <Accordion title="Metadata Usage">
    Store additional information in the metadata field:

    * Customer email or ID
    * Order or invoice reference
    * Product or service details
    * Tags for categorization
    * Internal tracking codes
  </Accordion>

  <Accordion title="Address Lifecycle">
    * Monitor address activity regularly
    * Deactivate addresses that are no longer in use
    * Keep inactive addresses for audit purposes
    * Archive old addresses after 12 months of inactivity
    * Never reuse the same address for different customers
  </Accordion>

  <Accordion title="Security">
    * Enable monitoring for all production addresses
    * Set up webhook alerts for large transactions
    * Validate all addresses before whitelisting
    * Regularly audit address configurations
    * Implement IP whitelisting for API access
  </Accordion>
</AccordionGroup>

### Monitoring Best Practices

<AccordionGroup>
  <Accordion title="Enable Monitoring">
    Always enable monitoring for production addresses:

    <CodeGroup>
      ```bash theme={null}
      curl -X POST https://api.xentfi.com/v1/addresses/{addressId}/monitoring/{blockchainId}/enable \
        -H "apiKey: your-api-key" \
        -H "orgId: your-org-id"
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Alert Configuration">
    * Set up notifications for large transactions
    * Monitor for unusual activity patterns
    * Configure alerts for failed transactions
    * Track address balance thresholds
  </Accordion>
</AccordionGroup>

## Get Address Balance

Check the token balance of any deposit address:

<CodeGroup>
  ```bash theme={null}
  curl -X GET https://api.xentfi.com/v1/addresses/{addressId}/balance \
    -H "apiKey: your-api-key" \
    -H "orgId: your-org-id" \
    -G \
    -d "blockchainIds[]=8a864e95-4b86-423d-9ba4-f4e692ec121e"
  ```

  ```javascript theme={null}
  const balance = await client.getAddressTokenBalance({
    addressId: 'addr_123e4567',
    blockchainIds: ['8a864e95-4b86-423d-9ba4-f4e692ec121e']
  });

  console.log('Balance:', balance.data);
  ```

  ```python theme={null}
  balance = client.get_address_token_balance(
    address_id='addr_123e4567',
    blockchain_ids=['8a864e95-4b86-423d-9ba4-f4e692ec121e']
  )

  print(f"Balance: {balance['data']}")
  ```
</CodeGroup>

### Balance Response Example

```json theme={null}
{
    "data": [
        {
            "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
            "balance": 100.5,
            "usdValue": 100.5,
            "asset": {
                "id": "69d851b9-c358-4359-becd-3e614ca1ab4d",
                "name": "Euro Coin",
                "symbol": "EURC",
                "decimals": 6,
                "address": "0x08210F9170F89Ab7658F0B5E3fF39b0E03C594D4"
            },
            "blockchain": {
                "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
                "name": "Base",
                "symbol": "ETH"
            }
        }
    ]
}
```

### Balance Query Parameters

| Parameter       | Type          | Description                                        |
| --------------- | ------------- | -------------------------------------------------- |
| `addressId`     | string (path) | ID of the deposit address                          |
| `blockchainIds` | array (query) | Optional list of blockchain IDs to filter balances |

## Get Transaction History

View all transactions for a specific deposit address:

<CodeGroup>
  ```bash theme={null}
  curl -X GET https://api.xentfi.com/v1/addresses/{addressId}/transfers \
    -H "apiKey: your-api-key" \
    -H "orgId: your-org-id" \
    -G \
    -d "txType=incoming" \
    -d "pageSize=20" \
    -d "order=DESC"
  ```

  ```javascript theme={null}
  const transfers = await client.listAddressTransfers({
    addressId: 'addr_123e4567',
    txType: 'incoming',
    pageSize: 20,
    order: 'DESC'
  });

  console.log('Transfers:', transfers.transfer);
  console.log('Total:', transfers.totalCount);
  ```

  ```python theme={null}
  transfers = client.list_address_transfers(
    address_id='addr_123e4567',
    tx_type='incoming',
    page_size=20,
    order='DESC'
  )

  print(f"Transfers: {transfers['transfer']}")
  print(f"Total: {transfers['totalCount']}")
  ```
</CodeGroup>

### Transaction History Response

```json theme={null}
{
    "transfer": [
        {
            "category": "erc20",
            "blockNum": "18500000",
            "from": "0xSenderAddress...",
            "to": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
            "value": 100.5,
            "symbol": "EURC",
            "hash": "0x28a1bfa727a024dd450352e736f957ac6f08471825362130ef1c3b4da536ebfb",
            "timestamp": "2024-01-15T10:30:00Z",
            "asset": {
                "id": "69d851b9-c358-4359-becd-3e614ca1ab4d",
                "symbol": "EURC",
                "decimals": 6
            }
        }
    ],
    "pageInfo": {
        "hasMore": true,
        "nextCursor": "next_page_token"
    },
    "totalCount": 150
}
```

### Transaction Filtering Options

| Parameter  | Type    | Description                              |
| ---------- | ------- | ---------------------------------------- |
| `txType`   | string  | `incoming` or `outgoing` (default: `to`) |
| `pageSize` | integer | Number of results per page (default: 10) |
| `pageKey`  | string  | Pagination cursor for next page          |
| `order`    | string  | `ASC` or `DESC` ordering                 |

## Whitelisting External Addresses

For addresses you own (exchange accounts, other wallets), you can whitelist them:

<CodeGroup>
  ```bash theme={null}
  curl -X POST https://api.xentfi.com/v1/addresses/whitelist \
    -H "apiKey: your-api-key" \
    -H "orgId: your-org-id" \
    -H "Content-Type: application/json" \
    -d '{
      "masterId": "your-master-wallet-id",
      "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
      "name": "Binance Withdrawal Address",
      "disableAutoSweep": false,
      "enableGaslessWithdraw": false,
      "enableMonitoring": true,
      "metadata": {
        "source": "exchange",
        "platform": "binance"
      }
    }'
  ```

  ```javascript theme={null}
  const whitelisted = await client.whitelistDepositAddress({
    masterId: 'your-master-wallet-id',
    walletAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0',
    name: 'Binance Withdrawal Address',
    disableAutoSweep: false,
    enableGaslessWithdraw: false,
    enableMonitoring: true,
    metadata: {
      source: 'exchange',
      platform: 'binance'
    }
  });

  console.log('Address whitelisted:', whitelisted.data);
  ```

  ```python theme={null}
  whitelisted = client.whitelist_deposit_address(
    master_id='your-master-wallet-id',
    wallet_address='0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0',
    name='Binance Withdrawal Address',
    disable_auto_sweep=False,
    enable_gasless_withdraw=False,
    enable_monitoring=True,
    metadata={
      'source': 'exchange',
      'platform': 'binance'
    }
  )

  print(f"Address whitelisted: {whitelisted['data']}")
  ```
</CodeGroup>

### Whitelist Request Parameters

| Parameter               | Type    | Required | Description                                                           |
| ----------------------- | ------- | -------- | --------------------------------------------------------------------- |
| `masterId`              | string  | ✅        | ID of the master wallet to associate the address with                 |
| `walletAddress`         | string  | ✅        | Existing blockchain wallet address (EVM format or Solana)             |
| `privatekey`            | string  | ❌        | Optional private key for the wallet (EVM or Solana format)            |
| `name`                  | string  | ❌        | Optional custom name for the deposit address                          |
| `disableAutoSweep`      | boolean | ❌        | Disable automatic sweeping of funds to master wallet (default: false) |
| `enableGaslessWithdraw` | boolean | ❌        | Enable gasless withdrawals for this address (default: false)          |
| `enableMonitoring`      | boolean | ❌        | Enable blockchain monitoring (default: false)                         |
| `metadata`              | object  | ❌        | Additional metadata for the address                                   |

### Whitelist Benefits

| Benefit              | Description                                |
| -------------------- | ------------------------------------------ |
| ✅ Security           | Prevents sending to unauthorized addresses |
| ✅ Faster withdrawals | Pre-approved addresses skip verification   |
| ✅ Audit trail        | Track all withdrawal destinations          |
| ✅ Compliance         | Meet regulatory requirements               |

## Address Monitoring

### Enable Monitoring

Get real-time notifications when your deposit address receives funds:

<CodeGroup>
  ```bash theme={null}
  curl -X POST https://api.xentfi.com/v1/addresses/{addressId}/monitoring/{blockchainId}/enable \
    -H "apiKey: your-api-key" \
    -H "orgId: your-org-id"
  ```

  ```javascript theme={null}
  const result = await client.enableAddressMonitoring({
    addressId: 'addr_123e4567',
    blockchainId: '8a864e95-4b86-423d-9ba4-f4e692ec121e'
  });

  console.log('Monitoring enabled:', result.message);
  ```

  ```python theme={null}
  result = client.enable_address_monitoring(
    address_id='addr_123e4567',
    blockchain_id='8a864e95-4b86-423d-9ba4-f4e692ec121e'
  )

  print(f"Monitoring enabled: {result['message']}")
  ```
</CodeGroup>

### Disable Monitoring

<CodeGroup>
  ```bash theme={null}
  curl -X POST https://api.xentfi.com/v1/addresses/{addressId}/monitoring/{blockchainId}/disable \
    -H "apiKey: your-api-key" \
    -H "orgId: your-org-id"
  ```
</CodeGroup>

### What Gets Tracked

| Event             | Description         | Webhook Event                |
| ----------------- | ------------------- | ---------------------------- |
| Payment detected  | First confirmation  | `DEPOSITE_INCOMING_DETECTED` |
| Swap executed     | Swap completed      | `SWAP_EXECUTED`              |
| Transfer executed | Transfer completed  | `TRANSFER_EXECUTED`          |
| Address created   | New deposit address | `DEPOSITE_ADDRESS_CREATED`   |

## Address Lifecycle

```mermaid theme={null}
stateDiagram-v2
    [*] --> Created: Generate address
    Created --> Active: Ready for payments
    Active --> Monitoring: Enable monitoring
    Monitoring --> Active: Disable monitoring
    Active --> Inactive: Deactivate address
    Inactive --> Active: Reactivate
    Inactive --> [*]: Delete address
```

## Address vs Payment Link

| Feature                 | Deposit Address                      | Payment Link                           |
| ----------------------- | ------------------------------------ | -------------------------------------- |
| **Best for**            | Recurring customers, API integration | One-time payments, marketing campaigns |
| **Customer experience** | Copy/paste address                   | Hosted payment page                    |
| **Payment methods**     | Crypto only                          | Crypto + Wallet Connect                |
| **Tracking**            | Per address                          | Per link                               |
| **QR code**             | Can generate manually                | Auto-generated                         |
| **Expiration**          | Permanent                            | Configurable                           |

## Reconciliation Strategies

### Per-Customer Strategy

```mermaid theme={null}
flowchart LR
    Customer[Customer A] --> Address1[Address: cust_A_123]
    Customer --> Payment1[$500 Payment]
    Address1 --> Wallet[Master Wallet]
    Payment1 --> Recon[Auto-reconciled to Customer A]
```

### Per-Invoice Strategy

```mermaid theme={null}
flowchart LR
    Invoice[Invoice #12345] --> Address2[Address: inv_12345]
    Invoice --> Payment2[$250 Payment]
    Address2 --> Wallet[Master Wallet]
    Payment2 --> Recon2[Auto-reconciled to Invoice #12345]
```

## Security Considerations

| Risk           | Mitigation                                   |
| -------------- | -------------------------------------------- |
| Address reuse  | Generate new addresses per customer/invoice  |
| Typo errors    | Validate addresses before whitelisting       |
| Phishing       | Use consistent naming and verification       |
| Key compromise | Rotate API keys, monitor suspicious activity |
| Wrong network  | Display network warnings to customers        |

## Dashboard View

<img src="https://mintlify.s3.us-west-1.amazonaws.com/xentfi/images/addresses/dashboard.png" alt="Deposit Addresses Dashboard" />

*The deposit addresses dashboard shows all your addresses with real-time status.*

## Common Patterns

### E-commerce Checkout

1. Customer places order
2. Create deposit address with order ID in name
3. Display address to customer
4. Monitor for payment
5. Update order status on webhook

### Subscription Billing

1. Customer signs up
2. Create permanent deposit address for customer
3. Store address in customer profile
4. Customer uses same address for all payments
5. Webhook triggers subscription renewal

### Crypto Payroll

1. Employee onboarded
2. Whitelist employee's personal wallet
3. Set up auto-settlement to whitelisted address
4. Payroll automatically distributed

## Troubleshooting

<AccordionGroup>
  <Accordion title="Address not receiving payments">
    **Possible causes:**

    * Wrong network selected
    * Address not activated
    * Blockchain congestion

    **Solutions:**

    * Verify network matches sender's network
    * Check address status in dashboard
    * Wait for block confirmations
  </Accordion>

  <Accordion title="Webhook not triggered">
    **Possible causes:**

    * Monitoring not enabled
    * Webhook URL not configured
    * Network issues

    **Solutions:**

    * Enable monitoring for the address
    * Verify webhook configuration
    * Check webhook logs
  </Accordion>

  <Accordion title="Wrong amount received">
    **Possible causes:**

    * Sender sent wrong amount
    * Decimal place confusion
    * Gas fee deduction

    **Solutions:**

    * Verify expected amount
    * Check token decimals
    * Review transaction details
  </Accordion>
</AccordionGroup>

## Performance Metrics

| Metric                | Target            | Description                       |
| --------------------- | ----------------- | --------------------------------- |
| Address creation time | \< 1 second       | Time to generate new address      |
| Payment detection     | \< 10 seconds     | Time to detect incoming payment   |
| Confirmation time     | Network dependent | Time for block confirmations      |
| Webhook delivery      | \< 5 seconds      | Time to send webhook notification |

## Pricing & Limits

| Plan         | Max Addresses | Monitoring | Support   |
| ------------ | ------------- | ---------- | --------- |
| Starter      | 100           | Basic      | Email     |
| Professional | 1,000         | Advanced   | Priority  |
| Business     | 10,000        | Premium    | Dedicated |
| Enterprise   | Unlimited     | Custom     | 24/7      |

## Related Products

<CardGroup cols={3}>
  <Card title="Master Wallets" icon="wallet" href="/products/master-wallets">
    Parent wallet management and treasury
  </Card>

  <Card title="Payment Links" icon="link" href="/products/payment-links">
    Hosted payment pages for one-time payments
  </Card>

  <Card title="Webhooks" icon="webhook" href="/products/webhooks">
    Real-time payment notifications
  </Card>
</CardGroup>

## Next Steps

* [Set up webhooks](/products/webhooks) for real-time payment notifications
* [Configure auto-settlement](/products/auto-settlement) for automatic fund distribution
* [Review API Reference](/api-reference) for complete endpoint documentation