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

# Auto Settlement

> Auto Settlement automatically distributes funds from your deposit addresses to destination wallets based on rules you define. This eliminates manual transfer operations and ensures funds are always where they need to be.

## Overview

```mermaid theme={null}
flowchart LR
    subgraph Incoming["Incoming Payments"]
        DA1[Customer A\n$500 USDC]
        DA2[Customer B\n$1,000 USDC]
        DA3[Customer C\n$250 USDC]
    end

    subgraph Rules["Settlement Rules"]
        R1[Rule: Amount > $100\n→ Main Treasury]
        R2[Rule: Amount < $100\n→ Operations Wallet]
        R3[Rule: USDC only\n→ USDC Treasury]
    end

    subgraph Destinations["Destination Wallets"]
        Main[Main Treasury]
        Ops[Operations Wallet]
        USDC[USDC Treasury]
    end

    DA1 --> R1
    DA2 --> R1
    DA3 --> R2
    DA1 --> R3
    DA2 --> R3

    R1 --> Main
    R2 --> Ops
    R3 --> USDC
```

## Why Use Auto Settlement?

<CardGroup cols={2}>
  <Card title="⚡ Automated Operations" icon="zap">
    Eliminate manual transfer operations - funds move automatically when conditions are met
  </Card>

  <Card title="🎯 Precision Control" icon="target">
    Define exactly when and where funds should go using configurable rules
  </Card>

  <Card title="💰 Optimize Treasury" icon="treasury">
    Keep funds in the right wallets for operational needs, savings, or investments
  </Card>

  <Card title="🔒 Risk Management" icon="shield">
    Limit exposure by automatically moving funds from customer-facing addresses
  </Card>

  <Card title="📊 Audit Trail" icon="document">
    Complete history of all settlement actions for compliance and reporting
  </Card>

  <Card title="🌐 Multi-asset" icon="globe">
    Support for all assets across multiple blockchains
  </Card>
</CardGroup>

## How Auto Settlement Works

```mermaid theme={null}
sequenceDiagram
    participant Customer
    participant Deposit as Deposit Address
    participant Rule as Settlement Rule
    participant Destination as Destination Wallet
    participant Webhook as Your Webhook

    Customer->>Deposit: Sends payment
    Deposit->>Rule: Triggers rule evaluation
    Rule->>Rule: Check conditions (amount, asset, etc.)

    alt Conditions Met
        Rule->>Destination: Execute transfer
        Destination->>Webhook: Settlement completed webhook
        Webhook->>YourApp: Update your records
    else Conditions Not Met
        Rule->>Deposit: Funds remain in deposit address
    end
```

## Key Concepts

### Settlement Rules

Rules define the conditions under which funds are transferred and where they go:

| Component       | Description                                  | Example              |
| --------------- | -------------------------------------------- | -------------------- |
| **Source**      | Which deposit addresses or assets to monitor | All USDC deposits    |
| **Trigger**     | When to execute settlement                   | Amount > \$1,000     |
| **Destination** | Where to send funds                          | Main treasury wallet |
| **Schedule**    | How often to check                           | Real-time or batch   |

### Settlement Triggers

| Trigger Type         | Description                   | Use Case                   |
| -------------------- | ----------------------------- | -------------------------- |
| **Amount threshold** | Settle when balance exceeds X | Large transaction handling |
| **Time-based**       | Settle at specific intervals  | Daily sweep                |
| **Asset-specific**   | Only settle certain tokens    | Stablecoin consolidation   |
| **Balance-based**    | Settle entire balance         | Zero-balance addresses     |
| **Manual override**  | Force settlement on demand    | Emergency sweeps           |

## Use Cases

### Merchant Settlement

| Scenario        | Rule Configuration              | Benefit                   |
| --------------- | ------------------------------- | ------------------------- |
| Daily sweep     | Settle all funds at 6 PM daily  | End-of-day reconciliation |
| Threshold sweep | Settle when balance > \$10,000  | Reduce exposure           |
| Per-transaction | Settle each payment immediately | Real-time treasury update |

### Exchange Integration

| Scenario                 | Rule Configuration                  | Benefit                  |
| ------------------------ | ----------------------------------- | ------------------------ |
| Stablecoin consolidation | All USDC → Central USDC wallet      | Liquidity management     |
| Profit transfer          | 10% of each payment → Profit wallet | Automated profit capture |
| Fee collection           | 2% fee → Fee wallet                 | Automatic fee deduction  |

### Multi-wallet Management

```mermaid theme={null}
flowchart TB
    subgraph Incoming["Customer Payments"]
        P1[$500 USDC]
        P2[$1,000 USDC]
        P3[$250 ETH]
    end

    subgraph Rules["Settlement Rules"]
        R1[Amount > $750 → Treasury]
        R2[Amount < $750 → Operations]
        R3[ETH → ETH Treasury]
    end

    subgraph Wallets["Destination Wallets"]
        T[Main Treasury]
        O[Operations Wallet]
        E[ETH Treasury]
    end

    P1 --> R2 --> O
    P2 --> R1 --> T
    P3 --> R3 --> E
```

## Creating Settlement Rules

### Basic Rule

<CodeGroup>
  ```bash theme={null}
  curl -X POST https://api.xentfi.com/v1/settlement-rules \
    -H "apiKey: your-api-key" \
    -H "orgId: your-org-id" \
    -H "Content-Type: application/json" \
    -d '{
      "masterId": "your-master-wallet-id",
      "name": "Daily USDC Sweep",
      "source": {
        "assetIds": ["usdc-asset-id"],
        "minAmount": "0",
        "maxAmount": "1000000"
      },
      "destination": {
        "address": "0xDestinationWallet..."
      }
    }'
  ```
</CodeGroup>

### Advanced Rule Configuration

```json theme={null}
{
    "masterId": "your-master-wallet-id",
    "name": "Tiered Settlement",
    "order": "ASC",
    "slippageTolerance": "0.5",
    "source": {
        "assetIds": [
            "usdc-asset-id",
            "usdt-asset-id"
        ],
        "minAmount": "100",
        "maxAmount": "10000"
    },
    "destination": {
        "assetId": "usdc-asset-id",
        "blockchainId": "eth-mainnet",
        "address": "0xConsolidationWallet..."
    },
    "isActive": true
}
```

## Rule Configuration Options

### Source Configuration

| Parameter      | Description               | Example         |
| -------------- | ------------------------- | --------------- |
| `assetIds`     | Which tokens to monitor   | USDC, USDT, DAI |
| `minAmount`    | Minimum amount to trigger | 100 USDC        |
| `maxAmount`    | Maximum amount to trigger | 10,000 USDC     |
| `blockchainId` | Specific blockchain       | eth-mainnet     |

### Destination Configuration

| Parameter      | Description                | Example          |
| -------------- | -------------------------- | ---------------- |
| `assetId`      | Output token (for swaps)   | USDC             |
| `blockchainId` | Destination blockchain     | polygon-mainnet  |
| `address`      | Destination wallet address | 0xDestination... |

### Rule Behavior

| Parameter           | Description           | Options                                     |
| ------------------- | --------------------- | ------------------------------------------- |
| `order`             | Execution order       | ASC (small to large), DESC (large to small) |
| `slippageTolerance` | Max price slippage    | 0.5%                                        |
| `isActive`          | Rule enabled/disabled | true / false                                |

## Settlement Execution

### Real-time Settlement

```mermaid theme={null}
flowchart LR
    Payment[Payment Received] --> Check[Check Rules]
    Check --> Execute[Execute Transfer]
    Execute --> Complete[Settlement Complete]
    Complete --> Notify[Webhook Sent]

    style Payment fill:#e8f5e9
    style Complete fill:#c8e6c9
```

### Batch Settlement

```mermaid theme={null}
flowchart LR
    Day[End of Day] --> Collect[Collect All Payments]
    Collect --> Consolidate[Consolidate Funds]
    Consolidate --> Transfer[Bulk Transfer]
    Transfer --> Report[Settlement Report]

    style Day fill:#fff3e0
    style Report fill:#ffe0b2
```

## Rule Types

### Single Destination Rule

Send all funds from source to a single destination:

```mermaid theme={null}
flowchart LR
    Source[Deposit Addresses] --> Rule[Settlement Rule]
    Rule --> Destination[Main Treasury]
```

### Conditional Rule

Send funds based on amount thresholds:

```mermaid theme={null}
flowchart LR
    Payment[Payment] --> Check{Amount?}
    Check -->|< $1,000| Ops[Operations Wallet]
    Check -->|≥ $1,000| Treasury[Main Treasury]
```

### Multi-asset Rule

Different rules for different assets:

| Asset | Rule             | Destination   |
| ----- | ---------------- | ------------- |
| USDC  | Amount > \$1,000 | USDC Treasury |
| USDT  | All amounts      | USDT Treasury |
| ETH   | Daily sweep      | ETH Savings   |

### Tiered Rule

Process settlements in priority order:

```mermaid theme={null}
flowchart TD
    Payments[All Payments] --> Priority1[Priority 1: > $10,000]
    Payments --> Priority2[Priority 2: $5,000 - $10,000]
    Payments --> Priority3[Priority 3: < $5,000]

    Priority1 --> Treasury[Main Treasury]
    Priority2 --> Ops[Operations]
    Priority3 --> Reserve[Reserve Fund]
```

## Settlement Monitoring

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

### Available Metrics

| Metric                  | Description                     | Update Frequency |
| ----------------------- | ------------------------------- | ---------------- |
| Total settled           | Cumulative settlement volume    | Real-time        |
| Pending settlements     | Awaiting execution              | Real-time        |
| Failed settlements      | Transactions that failed        | Real-time        |
| Average settlement time | Time from trigger to completion | Hourly           |
| Gas fees paid           | Total settlement costs          | Per transaction  |

## Webhook Events

| Event                   | Trigger            | Payload contains         |
| ----------------------- | ------------------ | ------------------------ |
| `settlement.created`    | Rule triggered     | Rule details, amount     |
| `settlement.processing` | Transfer initiated | Transaction hash         |
| `settlement.completed`  | Transfer confirmed | Full transaction details |
| `settlement.failed`     | Transfer failed    | Error reason             |
| `settlement.swept`      | Batch completed    | Summary of all transfers |

## Best Practices

<Info>
  * **Start simple** - Begin with basic amount-based rules
  * **Test on testnet** - Validate rules before mainnet
  * **Set appropriate thresholds** - Avoid micro-settlements that waste gas
  * **Monitor gas costs** - Batch settlements during low-fee periods
  * **Keep audit trail** - Log all settlement events
  * **Review regularly** - Update rules as business needs change
</Info>

## Gas Optimization Strategies

| Strategy           | Description                     | Gas Savings    |
| ------------------ | ------------------------------- | -------------- |
| Batch settlements  | Combine multiple transfers      | Up to 70%      |
| Off-peak execution | Settle during low gas times     | 30-50%         |
| L2 settlement      | Use Polygon/Base for settlement | 90%+           |
| Threshold minimums | Don't settle small amounts      | Prevents waste |

## Risk Management

| Risk                  | Mitigation                      |
| --------------------- | ------------------------------- |
| Gas price spikes      | Set slippage tolerance, use L2  |
| Failed transactions   | Retry logic with backoff        |
| Wrong destination     | Whitelist destination addresses |
| Orphaned funds        | Monitoring and alerts           |
| Regulatory compliance | Settlement audit trail          |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Rule not triggering">
    **Possible causes:**

    * Rule is inactive
    * Amount outside min/max range
    * Asset not in source list
    * Destination address invalid

    **Solutions:**

    * Verify rule is active
    * Check amount thresholds
    * Confirm asset IDs
    * Validate destination address
  </Accordion>

  <Accordion title="Settlement failed">
    **Possible causes:**

    * Insufficient gas
    * Network congestion
    * Destination wallet issue
    * Token approval missing

    **Solutions:**

    * Increase gas limit
    * Wait and retry
    * Verify destination wallet
    * Check token approvals
  </Accordion>

  <Accordion title="High gas costs">
    **Solutions:**

    * Use L2 networks (Polygon, Base)
    * Batch settlements
    * Settle during low-traffic times
    * Increase minimum thresholds
  </Accordion>

  <Accordion title="Duplicate settlements">
    **Solutions:**

    * Implement idempotency keys
    * Check for duplicate webhooks
    * Review rule configuration
  </Accordion>
</AccordionGroup>

## Performance Metrics

| Metric              | Target            | Description                 |
| ------------------- | ----------------- | --------------------------- |
| Rule evaluation     | \< 100ms          | Time to evaluate conditions |
| Transfer initiation | \< 500ms          | Time to start transfer      |
| Confirmation time   | Network dependent | Block confirmations         |
| Webhook delivery    | \< 2 seconds      | Notification time           |

## Pricing Impact

| Feature             | Starter | Professional | Business | Enterprise |
| ------------------- | ------- | ------------ | -------- | ---------- |
| Settlement rules    | 5       | 25           | 100      | Unlimited  |
| Rule types          | Basic   | Advanced     | Premium  | Custom     |
| Batch settlement    | ❌       | ✅            | ✅        | ✅          |
| Custom gas strategy | ❌       | ❌            | ✅        | ✅          |
| Priority execution  | ❌       | ❌            | ✅        | ✅          |

## Compliance & Reporting

| Requirement            | Status | Description             |
| ---------------------- | ------ | ----------------------- |
| Settlement audit trail | ✅      | Complete history        |
| Regulatory reporting   | ✅      | Exportable reports      |
| Tax reconciliation     | ✅      | Per-transaction records |
| AML monitoring         | ✅      | Automatic screening     |

## Related Products

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

  <Card title="Deposit Addresses" icon="address-card" href="/products/deposit-addresses">
    Source of incoming payments
  </Card>

  <Card title="Webhooks" icon="webhook" href="/products/webhooks">
    Settlement notifications
  </Card>
</CardGroup>

## Next Steps

* [Create settlement rules](/api-reference) in API Reference
* [Set up webhooks](/products/webhooks) for settlement notifications
* [Monitor settlement activity](/products/webhooks) in dashboard