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

# Master Wallets

> Master wallets are the cornerstone of XentFi's wallet infrastructure. They serve as your primary treasury account, enabling you to manage funds, create deposit addresses, and configure automated settlement rules—all from a single interface.

## Overview

<img src="https://mintcdn.com/xentfi/JDzCYV2X25w6qMNc/images/master_wallets.png?fit=max&auto=format&n=JDzCYV2X25w6qMNc&q=85&s=64e266c4623366c45158038ebe62883e" alt="Main dashboard interface" className="rounded-lg" width="1841" height="927" data-path="images/master_wallets.png" />

## Key Features

<CardGroup cols={3}>
  <Card title="🏦 Central Treasury" icon="bank">
    Single point of control for all your crypto funds with multi-chain support
  </Card>

  <Card title="🔐 Enterprise Security" icon="shield-check">
    Bank-grade security with AES-256 encryption and HSM integration
  </Card>

  <Card title="📊 Real-time Analytics" icon="activity">
    Live transaction monitoring and comprehensive reporting dashboard
  </Card>

  <Card title="🔄 Auto Settlement" icon="arrow-right">
    Automated fund distribution based on configurable rules
  </Card>

  <Card title="🌐 Multi-chain" icon="globe">
    Support for 7+ major blockchains including Ethereum, Base, and Solana
  </Card>

  <Card title="📈 Scalable" icon="trending-up">
    Handle thousands of transactions with enterprise-grade infrastructure
  </Card>
</CardGroup>

## Dashboard Overview

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

*The master wallet dashboard provides a comprehensive view of your treasury operations.*

## Supported Blockchains

| Blockchain | Network | Chain ID | Native Token | Avg Block Time | Status |
| ---------- | ------- | -------- | ------------ | -------------- | ------ |
| Ethereum   | Mainnet | 1        | ETH          | 12-15 sec      | ✅ Live |
| Base       | Mainnet | 8453     | ETH          | 2 sec          | ✅ Live |
| Polygon    | Mainnet | 137      | POL          | 2-3 sec        | ✅ Live |
| Arbitrum   | Mainnet | 42161    | ETH          | 0.25 sec       | ✅ Live |
| Optimism   | Mainnet | 10       | ETH          | 2 sec          | ✅ Live |
| BNB Chain  | Mainnet | 56       | BNB          | 3 sec          | ✅ Live |
| Solana     | Mainnet | 1        | SOL          | 0.4 sec        | ✅ Live |

## Prerequisites

Before creating a master wallet, ensure you have:

* ✅ A verified XentFi account
* ✅ API key and App ID from the dashboard
* ✅ Selected target blockchain
* ✅ Understanding of gas fees for your chosen network

## Creating a Master Wallet

### Via API

<CodeGroup>
  ```bash theme={null}
  curl -X POST https://api.xentfi.com/v1/master-wallets \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main Treasury",
    "blockchainId": "eth-mainnet",
    "description": "Primary business treasury",
    "enableMonitoring": true,
    "enableGaslessWithdraw": false
  }'
  ```

  ```javascript theme={null}
  const { XentFiClient } = require('@xentfi/sdk');

  const client = new XentFiClient({
    apiKey: process.env.XENTFI_API_KEY,
    appId: process.env.XENTFI_APP_ID
  });

  const wallet = await client.createMasterWallet({
    name: 'Main Treasury',
    blockchainId: 'eth-mainnet',
    description: 'Primary business treasury',
    enableMonitoring: true
  });

  console.log(`Wallet created: ${wallet.id}`);
  console.log(`Address: ${wallet.walletAddress}`);
  ```

  ```python theme={null}
  from xentfi import XentFiClient

  client = XentFiClient(
    api_key=os.environ['XENTFI_API_KEY'],
    app_id=os.environ['XENTFI_APP_ID']
  )

  wallet = client.create_master_wallet(
    name='Main Treasury',
    blockchain_id='eth-mainnet',
    description='Primary business treasury',
    enable_monitoring=True
  )

  print(f"Wallet created: {wallet['id']}")
  print(f"Address: {wallet['wallet_address']}")
  ```
</CodeGroup>

### Via Dashboard

<Steps>
  <Step title="Navigate to Wallets">
    Log into your dashboard and click **Wallets** in the left sidebar.
  </Step>

  <Step title="Create New Wallet">
    Click the **Create Wallet** button in the top right corner.
  </Step>

  <Step title="Configure Wallet">
    Fill in the wallet details:

    * **Name**: A descriptive name (e.g., "Production Treasury")
    * **Blockchain**: Select your target blockchain
    * **Description**: Optional description
    * **Enable Monitoring**: Toggle for transaction alerts
  </Step>

  <Step title="Review and Create">
    Review your settings and click **Create Wallet**.
  </Step>
</Steps>

## Response Example

```json theme={null}
{
    "data": {
        "id": "wallet_123e4567-e89b-12d3-a456-426614174000",
        "name": "Main Treasury",
        "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
        "description": "Primary business treasury",
        "blockchain": {
            "id": "eth-mainnet",
            "name": "Ethereum",
            "symbol": "ETH",
            "chainId": 1,
            "logoUrl": "https://assets.xentfi.com/chains/eth.svg"
        },
        "configurations": {
            "monitoringConfig": {
                "enabledChains": [
                    "eth-mainnet"
                ],
                "defaultEnabled": true
            }
        },
        "isActive": true,
        "analytics": {
            "addressCount": 0,
            "paymentLinksCount": 0,
            "totalVolume": "0",
            "transactionCount": 0
        },
        "createdAt": "2024-01-15T10:30:00.000Z",
        "updatedAt": "2024-01-15T10:30:00.000Z"
    }
}
```

## Quick Guide: Wallet Configuration

### Auto-Sweep Configuration

Auto-sweep automatically moves funds from deposit addresses to your master wallet, consolidating funds and reducing gas costs.

<CodeGroup>
  ```bash theme={null}
  curl -X PUT https://api.xentfi.com/v1/master-wallets/{walletId}/auto-sweep \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "threshold": "100",
    "destinationAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
    "sweepAll": false
  }'
  ```

  ```javascript theme={null}
  const config = await client.configureAutoSweep({
    walletId: 'wallet_123e4567',
    enabled: true,
    threshold: '100', // USD value trigger
    destinationAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0',
    sweepAll: false // If true, sweeps all funds regardless of threshold
  });

  console.log('Auto-sweep configured:', config);
  ```

  ```python theme={null}
  config = client.configure_auto_sweep(
    wallet_id='wallet_123e4567',
    enabled=True,
    threshold='100',
    destination_address='0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0',
    sweep_all=False
  )

  print(f"Auto-sweep configured: {config}")
  ```
</CodeGroup>

**Configuration Options:**

| Parameter            | Type    | Description                                       |
| -------------------- | ------- | ------------------------------------------------- |
| `enabled`            | boolean | Enable or disable auto-sweep                      |
| `threshold`          | string  | Minimum balance to trigger sweep (in USD)         |
| `destinationAddress` | string  | Address to sweep funds to                         |
| `sweepAll`           | boolean | If true, sweeps all funds regardless of threshold |

### Testing on Development

#### 1. Set Up Test Environment

<Steps>
  <Step title="Create Test Wallet">
    Create a wallet on testnet (Sepolia, Mumbai, or Solana Devnet):

    <CodeGroup>
      ```bash theme={null}
      curl -X POST https://api.xentfi.com/v1/master-wallets \
      -H "apiKey: your-test-api-key" \
      -H "orgId: your-org-id" \
      -d '{
        "name": "Test Treasury",
        "blockchainId": "sepolia",
        "description": "Development testing wallet"
      }'
      ```
    </CodeGroup>
  </Step>

  <Step title="Get Test Funds">
    Use public testnet faucets to fund your test wallet:

    * **Sepolia ETH**: [sepoliafaucet.com](https://sepoliafaucet.com) or [Alchemy Sepolia Faucet](https://sepoliafaucet.com/)
    * **Mumbai MATIC**: [Polygon Faucet](https://faucet.polygon.technology/)
    * **Base Testnet**: [Base Faucet](https://base.org/faucet)
    * **Solana Devnet**: [Solana Faucet](https://solfaucet.com/)
  </Step>

  <Step title="Verify Balance">
    Check your test wallet balance:

    <CodeGroup>
      ```bash theme={null}
      curl -X GET https://api.xentfi.com/v1/master-wallets/{walletId}/balance \
      -H "apiKey: your-test-api-key" \
      -H "orgId: your-org-id"
      ```
    </CodeGroup>
  </Step>
</Steps>

#### 2. Test Transaction Flow

<CodeGroup>
  ```bash theme={null}
  # Create a deposit address
  curl -X POST https://api.xentfi.com/v1/addresses \
  -H "apiKey: your-test-api-key" \
  -H "orgId: your-org-id" \
  -d '{
    "masterId": "wallet_123e4567",
    "name": "Test Customer Address"
  }'

  # Send test funds to the deposit address using a public faucet

  # Monitor transaction
  curl -X GET https://api.xentfi.com/v1/addresses/{addressId}/transfers \
  -H "apiKey: your-test-api-key" \
  -H "orgId: your-org-id"
  ```

  ```javascript theme={null}
  // Test flow with SDK
  async function testWalletFlow() {
    // 1. Create deposit address
    const address = await client.createDepositAddress({
      masterId: 'wallet_123e4567',
      name: 'Test Customer Address'
    });

    // 2. Monitor for incoming transfers
    const transfers = await client.listAddressTransfers({
      addressId: address.id,
      txType: 'incoming'
    });

    console.log('Transfers:', transfers);

    // 3. Test auto-sweep
    const sweepResult = await client.triggerAutoSweep({
      addressId: address.id
    });

    return { address, transfers, sweepResult };
  }
  ```

  ```python theme={null}
  def test_wallet_flow():
      # 1. Create deposit address
      address = client.create_deposit_address(
          master_id='wallet_123e4567',
          name='Test Customer Address'
      )

      # 2. Monitor for incoming transfers
      transfers = client.list_address_transfers(
          address_id=address['id'],
          tx_type='incoming'
      )

      print(f"Transfers: {transfers}")

      # 3. Test auto-sweep
      sweep_result = client.trigger_auto_sweep(
          address_id=address['id']
      )

      return address, transfers, sweep_result
  ```
</CodeGroup>

## Best Practices

### Security

<AccordionGroup>
  <Accordion title="API Key Management">
    * Rotate API keys every 30 days
    * Use different API keys for development and production
    * Never commit API keys to version control
    * Store keys in environment variables or secure vault
    * Use read-only API keys for monitoring dashboards
  </Accordion>

  <Accordion title="Wallet Security">
    * Enable monitoring for all production wallets
    * Set up webhook alerts for large transactions
    * Use multi-signature wallets for large treasuries
    * Regularly audit transaction history
    * Implement IP whitelisting for API access
  </Accordion>

  <Accordion title="Network Selection">
    * Always test on testnet before mainnet
    * Consider gas fees when choosing networks
    * Use Layer 2 networks (Base, Polygon) for high-volume transactions
    * Monitor network congestion and adjust gas settings
  </Accordion>
</AccordionGroup>

### Development

<AccordionGroup>
  <Accordion title="Testing Strategy">
    * Test all wallet operations on testnet
    * Simulate edge cases (low balance, network errors)
    * Test auto-sweep with different thresholds
    * Validate webhook integrations
    * Test recovery flows with test tokens
  </Accordion>

  <Accordion title="Error Handling">
    * Implement exponential backoff for retries
    * Handle network timeout errors gracefully
    * Log all API errors for debugging
    * Set up monitoring alerts for failed transactions
    * Validate all addresses before sending funds
  </Accordion>

  <Accordion title="Transaction Management">
    * Batch similar transactions to save gas
    * Use idempotency keys for critical operations
    * Monitor pending transactions
    * Set transaction timeouts
    * Implement transaction status polling
  </Accordion>
</AccordionGroup>

### Performance Optimization

| Practice               | Impact                      | Recommendation                                    |
| ---------------------- | --------------------------- | ------------------------------------------------- |
| **Batch Transactions** | Reduces gas costs by 30-50% | Batch up to 10 transactions per request           |
| **Use L2 Networks**    | Reduces fees by 90%         | Base or Polygon for high-volume operations        |
| **Cache Addresses**    | Reduces API calls by 80%    | Cache frequently used addresses for 1 hour        |
| **Monitor Gas Prices** | Saves 10-20% on fees        | Use gas price APIs to optimize transaction timing |
| **Implement Webhooks** | Reduces polling by 95%      | Use webhooks for real-time updates                |

## Development vs Production

| Aspect          | Development                         | Production                          |
| --------------- | ----------------------------------- | ----------------------------------- |
| **Network**     | Testnet (Sepolia, Mumbai)           | Mainnet                             |
| **API Keys**    | Sandbox keys                        | Production keys                     |
| **Funds**       | Testnet tokens (via public faucets) | Real cryptocurrency                 |
| **Auto-Sweep**  | Test with small amounts             | Configure with realistic thresholds |
| **Monitoring**  | Optional                            | Required                            |
| **Gas Fees**    | Free (testnet)                      | Real (paid by you)                  |
| **Rate Limits** | Higher limits                       | Standard limits                     |
| **SLA**         | Best effort                         | 99.9% uptime guaranteed             |

## Transaction Volume Tiers

| Tier         | Monthly Volume     | Features                            |
| ------------ | ------------------ | ----------------------------------- |
| Starter      | \< \$10,000        | Basic features, standard support    |
| Professional | $10,000 - $100,000 | Advanced features, priority support |
| Business     | $100,000 - $1M     | Premium features, dedicated support |
| Enterprise   | > \$1M             | Custom features, SLA guarantees     |

## Use Cases

<CardGroup cols={2}>
  <Card title="E-commerce" icon="shopping-cart">
    Accept crypto payments for online stores with automatic settlement to your treasury
  </Card>

  <Card title="SaaS Subscriptions" icon="repeat">
    Manage recurring crypto payments with subscription billing
  </Card>

  <Card title="Invoice Payments" icon="file-text">
    Generate unique addresses per invoice for easy reconciliation
  </Card>

  <Card title="Crypto Treasury" icon="treasury">
    Centralized management of corporate crypto assets
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Wallet creation fails with 'Blockchain not supported'">
    **Solution:** Verify the blockchain ID is correct. Use `list-supported-blockchains` endpoint to get valid IDs.
  </Accordion>

  <Accordion title="Cannot find wallet" icon="search">
    **Solution:**

    * Confirm wallet ID is correct
    * Check if wallet belongs to your app ID
    * Verify wallet hasn't been deactivated
  </Accordion>

  <Accordion title="Monitoring not working">
    **Solution:**

    * Ensure blockchain webhook is configured
    * Check if monitoring was properly enabled
    * Verify webhook URL is accessible
  </Accordion>

  <Accordion title="High gas fees">
    **Solution:**

    * Consider using L2 solutions like Base or Polygon
    * Enable gasless withdrawals for users
    * Batch transactions when possible
  </Accordion>

  <Accordion title="Rate limit exceeded">
    **Solution:**

    * Implement exponential backoff
    * Cache responses when possible
    * Upgrade to higher tier plan
  </Accordion>
</AccordionGroup>

## Migration to Production

<Steps>
  <Step title="Test on Testnet">
    Create test wallets on Sepolia or Mumbai testnets
  </Step>

  <Step title="Verify Functionality">
    Test all wallet operations with test tokens from public faucets
  </Step>

  <Step title="Generate Production Keys">
    Create new API keys with production environment
  </Step>

  <Step title="Create Production Wallets">
    Deploy wallets on mainnet networks
  </Step>

  <Step title="Configure Auto-Sweep">
    Set up auto-sweep with appropriate thresholds
  </Step>

  <Step title="Enable Monitoring">
    Turn on monitoring for all production wallets
  </Step>

  <Step title="Go Live">
    Update your application configuration and launch
  </Step>
</Steps>

## API Reference

| Endpoint                                     | Method | Description             |
| -------------------------------------------- | ------ | ----------------------- |
| `/v1/master-wallets`                         | GET    | List all master wallets |
| `/v1/master-wallets`                         | POST   | Create a master wallet  |
| `/v1/master-wallets/{id}`                    | GET    | Get wallet details      |
| `/v1/master-wallets/{id}`                    | PUT    | Update wallet           |
| `/v1/master-wallets/{id}/monitoring/enable`  | POST   | Enable monitoring       |
| `/v1/master-wallets/{id}/monitoring/disable` | POST   | Disable monitoring      |
| `/v1/master-wallets/{id}/balance`            | POST   | Get token balances      |
| `/v1/master-wallets/{id}/transfers`          | GET    | List transactions       |
| `/v1/master-wallets/{id}/auto-sweep`         | PUT    | Configure auto-sweep    |

## Support Resources

* 📧 **Email**: [support@xentfi.com](mailto:support@xentfi.com)
* 💬 **Discord**: [Join our community](https://discord.gg/xentfi)
* 📚 **API Reference**: [Complete documentation](/api-reference)
* 🐛 **Issues**: [GitHub Issues](https://github.com/xentfi/api/issues)

## Next Steps

<CardGroup cols={3}>
  <Card title="Deposit Addresses" icon="address-card" href="/products/deposit-addresses">
    Create addresses for customer payments
  </Card>

  <Card title="Auto Settlement" icon="automation" href="/products/auto-settlement">
    Automate fund distribution
  </Card>

  <Card title="Payment Links" icon="link" href="/products/payment-links">
    Generate hosted payment pages
  </Card>
</CardGroup>