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

# Auto Settlements

> Automate asset settlements and conversions across blockchain networks

<Note>
  In a nutshell<br />
  Auto Settlements automatically convert incoming deposits to your preferred asset on any blockchain. Define rules once, and all matching deposits are swapped and routed to your destination chain—no manual intervention required.
</Note>

<img src="https://mintcdn.com/blockradar/fWg7SGpNBqmitg8P/images/auto-settlements.png?fit=max&auto=format&n=fWg7SGpNBqmitg8P&q=85&s=da36bc007cde5ce5112b567a12da7c70" alt="Auto Settlements" width="3434" height="2174" data-path="images/auto-settlements.png" />

## Prerequisites

Before setting up auto-settlement rules, ensure you have:

<Steps>
  <Step title="API Key">
    Get your API key from the [Blockradar Dashboard](https://dashboard.blockradar.co). Navigate to **Developers** to generate one.
  </Step>

  <Step title="Master Wallet Created">
    Create a master wallet via the [Create Wallet API](/en/api-reference/wallets/create-wallet) or dashboard. Rules are configured per wallet.
  </Step>

  <Step title="Destination Wallet">
    If settling cross-chain, ensure you have a wallet on the destination blockchain to receive converted assets.
  </Step>

  <Step title="Sufficient Gas">
    Fund your wallets with native tokens (ETH, BNB, MATIC, etc.) to cover swap and transfer fees.
  </Step>

  <Step title="Webhook Configured">
    Set up webhooks to receive settlement notifications. Depending on the action, you'll receive `swap.success`/`swap.failed`, `gateway.success`/`gateway.failed`, or `withdraw.success`/`withdraw.failed` events. See [Webhooks](/en/essentials/webhooks) for details.
  </Step>
</Steps>

## How It Works

Auto Settlements allow you to automatically convert incoming deposits into any destination asset on any blockchain network based on your configured rules. This eliminates the need to manually swap or bridge assets, ensuring your treasury can be automatically converted to your preferred assets across multiple chains.

<CardGroup cols={2}>
  <Card title="Rules Management" icon="gears">
    Create and manage auto-settlement rules to automate asset conversions.
  </Card>

  <Card title="Asset Conversion" icon="arrow-right-arrow-left">
    Automatically convert any stablecoin to any other asset based on your rules.
  </Card>

  <Card title="Cross-Chain" icon="globe">
    Settle assets to any blockchain network seamlessly.
  </Card>

  <Card title="Risk Management" icon="shield">
    Apply slippage tolerance and rules to protect against poor executions.
  </Card>
</CardGroup>

## How Auto Settlements Work

### **1. Rule Creation**

Define settlement rules that specify when and how deposits should be automatically converted.

### **2. Deposit Detection**

When funds arrive at your addresses, Blockradar automatically detects deposits matching your rules.

### **3. Asset Conversion**

Deposits are automatically swapped to your destination asset (typically USDC) on your chosen chain.

### **4. Balance Unification**

All converted assets are consolidated into a single, unified balance on your destination chain.

## Auto Settlement Rules

### **Rule Components**

Each auto-settlement rule defines the following parameters:

| Component                  | Description                                                                                            | Example                                      |
| -------------------------- | ------------------------------------------------------------------------------------------------------ | -------------------------------------------- |
| **Rule Name**              | Descriptive name for your settlement rule                                                              | "Swap from USDC to Optimism USDC"            |
| **Order**                  | Execution priority preference                                                                          | FASTEST, CHEAPEST, RECOMMENDED, NO\_SLIPPAGE |
| **Slippage Tolerance**     | Maximum acceptable price deviation (%). Use `-1` for unlimited slippage                                | 5 or -1                                      |
| **Source Assets**          | Array of assets to auto-settle                                                                         | \["USDC", "USDT"]                            |
| **Source Min/Max Amount**  | Control deposit size that triggers settlement                                                          | Min: $1, Max: $1,000                         |
| **Destination Blockchain** | Target blockchain network                                                                              | optimism, base, ethereum                     |
| **Destination Asset**      | Target asset for conversion                                                                            | USDC, USDT, cNGN, DAI                        |
| **Destination Address**    | (Optional) Specific address to receive converted assets. If not provided, smart fallback logic applies | 0x2455eC6700092991Ce0782365A89d5Cd89c8Fa22   |
| **Is Gateway**             | Enable gateway functionality for the rule                                                              | false                                        |

### **Rule Configuration Options**

#### **Amount Thresholds**

* **Minimum Amount**: Only settle deposits above this threshold
* **Maximum Amount**: Cap the size of individual settlements
* **Batch Processing**: Group multiple small deposits for efficiency

#### **Slippage Protection**

* **Unlimited**: `-1` (no slippage limit - default behavior)
* **Conservative**: 0.1% - 0.5% (minimal price impact)
* **Moderate**: 0.5% - 1.0% (balanced approach)
* **Aggressive**: 1.0% - 2.0% (faster execution)

<Note>
  Setting `slippageTolerance` to `-1` means unlimited slippage tolerance. This is the default behavior if not specified, allowing settlements to execute regardless of price deviation.
</Note>

#### **Destination Address (Optional)**

The `destination.address` field is now optional. When not provided, the system uses smart fallback logic to determine the recipient address:

| Scenario                              | Fallback Behavior                                  |
| ------------------------------------- | -------------------------------------------------- |
| **Explicit address provided**         | Uses the specified address                         |
| **Same chain settlement**             | Uses the deposit address (source address)          |
| **EVM-to-EVM cross-chain**            | Uses the same address on the destination chain     |
| **Cross-chain (non-EVM destination)** | Uses the destination chain's master wallet address |

<Tip>
  For most use cases, you can omit the destination address and let the system automatically route funds to the appropriate address based on the settlement type.
</Tip>

#### **Execution Preferences**

* **Fastest**: Prioritize speed over cost
* **Cheapest**: Optimize for lowest fees
* **Recommended**: Balance speed and cost with reliability
* **No Slippage**: Execute only when no price deviation occurs

## Rule Hierarchy and Precedence

### **How Rules Apply**

<Info>
  **Key Concept**: Rules created on a master wallet automatically apply to all child addresses under that wallet. However, if you create rules directly on a child address, those rules will completely override the master wallet rules for that specific address.
</Info>

| Rule Level              | Scope                                              | Behavior                                             |
| ----------------------- | -------------------------------------------------- | ---------------------------------------------------- |
| **Master Wallet Rules** | Apply to the master wallet AND all child addresses | Default rules for the entire wallet hierarchy        |
| **Child Address Rules** | Apply only to that specific address                | Completely override master wallet rules when present |

### **Rule Application Order**

1. **Check for Child Address Rules**: If the receiving address has its own rules, use those exclusively
2. **Fall back to Master Wallet Rules**: If no child address rules exist, apply master wallet rules
3. **No Rules**: If neither level has rules configured, no auto-settlement occurs

<Warning>
  When a child address has its own rules, master wallet rules are **completely ignored** for that address—there is no merging or combining of rules.
</Warning>

### **Blockchain-Specific Rules**

<Info>
  **Important**: Rules are isolated and tied to each blockchain. A rule configured for one blockchain (e.g., Ethereum) will NOT affect deposits on another blockchain (e.g., Base or Optimism).
</Info>

This means:

* You must create separate rules for each source blockchain you want to auto-settle
* A rule for "USDC on Ethereum" will not trigger for "USDC on Base"
* This allows granular control over settlement behavior per chain

**Example**: If you want to auto-settle USDC deposits from both Ethereum and Base to Optimism, you need two separate rules:

1. Rule for Ethereum USDC → Optimism USDC
2. Rule for Base USDC → Optimism USDC

### **Use Cases for Each Level**

#### **Master Wallet Rules**

* **Consistent Strategy**: Same settlement behavior across all child addresses
* **Simplified Management**: Single place to configure default behavior
* **Bulk Operations**: Apply rules to multiple addresses at once
* **Standardization**: Ensure compliance and consistency

#### **Child Address Rules**

* **Testing**: Try different settlement strategies on specific addresses
* **Custom Requirements**: Address-specific settlement needs
* **Override Defaults**: Modify behavior for particular use cases
* **Granular Control**: Fine-tune settlement for specific addresses

## Creating Auto Settlement Rules

### **Via Dashboard**

1. Navigate to your wallet's Auto Settlements section
2. Click "Create New Rule"
3. Configure rule parameters
4. Set amount thresholds and slippage tolerance
5. Choose source and destination assets/chains
6. Save and activate the rule

### **Via API**

Create settlement rules programmatically using the Auto Settlement Rules API:

```bash theme={null}
curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/auto-settlements/rules \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "name": "Swap from USDC to Optimism USDC",
    "order": "FASTEST",
    "slippageTolerance": "-1",
    "source": {
        "assets": [
            "USDC",
            "USDT"
        ],
        "minAmount": "1",
        "maxAmount": "1000"
    },
    "destination": {
        "blockchain": "optimism",
        "asset": "USDC"
    }
}'
```

<Note>
  In this example, `slippageTolerance` is set to `-1` for unlimited slippage, and `destination.address` is omitted. The system will automatically use smart fallback logic to determine the recipient address.
</Note>

**With explicit destination address:**

```bash theme={null}
curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/auto-settlements/rules \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "name": "Swap from USDC to Optimism USDC",
    "order": "FASTEST",
    "slippageTolerance": "5",
    "source": {
        "assets": [
            "USDC",
            "USDT"
        ],
        "minAmount": "1",
        "maxAmount": "1000"
    },
    "destination": {
        "blockchain": "optimism",
        "asset": "USDC",
        "address": "0x2455eC6700092991Ce0782365A89d5Cd89c8Fa22"
    }
}'
```

## Use Cases

### **Treasury Management**

* **Flexible Asset Conversion**: Convert to any preferred asset (USDC, ETH, USDT, etc.)
* **Cross-Chain Operations**: Maintain balances across multiple networks
* **Automated Consolidation**: No manual intervention required
* **Multi-Asset Strategy**: Support various asset preferences and strategies

### **Business Operations**

* **Payment Processing**: Automatically settle incoming payments to preferred assets
* **Revenue Management**: Convert various stablecoins to your chosen destination asset
* **Risk Mitigation**: Apply slippage protection automatically
* **Asset Diversification**: Maintain target asset allocations automatically

### **DeFi Integration**

* **Yield Farming**: Automatically settle rewards to preferred asset
* **Liquidity Management**: Consolidate LP rewards and fees
* **Portfolio Rebalancing**: Maintain target asset allocations

## Best Practices

### **Rule Configuration**

* **Start Conservative**: Begin with low slippage tolerance
* **Monitor Performance**: Track settlement success rates
* **Adjust Gradually**: Fine-tune rules based on market conditions
* **Test on Testnet**: Validate rules before mainnet deployment

### **Risk Management**

* **Slippage Limits**: Set appropriate tolerance levels
* **Amount Caps**: Limit maximum settlement sizes
* **Network Selection**: Choose reliable destination chains
* **Fallback Rules**: Create backup settlement options

### **Operational Efficiency**

* **Batch Processing**: Group small deposits for efficiency
* **Timing Optimization**: Consider network congestion patterns
* **Cost Analysis**: Balance speed vs. cost preferences
* **Monitoring**: Set up alerts for failed settlements

## Monitoring and Alerts

### **Dashboard Monitoring**

* **Rule Status**: Active/inactive rule indicators
* **Settlement History**: Track successful and failed settlements
* **Performance Metrics**: Success rates and execution times
* **Asset Balances**: Monitor unified balance growth

### **Webhook Notifications**

Auto-settlements trigger webhook events when settlements are executed:

| Event          | Description                                    |
| -------------- | ---------------------------------------------- |
| `swap.success` | Auto-settlement swap was successfully executed |
| `swap.failed`  | Auto-settlement swap failed to execute         |

### **Webhook Payload Example**

```json theme={null}
{
  "event": "swap.success",
  "data": {
    "id": "99a2b490-0798-460b-9265-4d99f182fe52",
    "reference": "ZMxcorDGtf",
    "senderAddress": "0xAA2d5fd5e7bE97E214f8565DCf3a4862719960b5",
    "recipientAddress": "0xb55c054D8eE75224E1033e6eC775B4F62D942b43",
    "amount": "5",
    "status": "SUCCESS",
    "type": "SWAP",
    "network": "mainnet",
    "toAmount": "4.965398",
    "rate": "0.9930796000000001",
    "asset": {
      "name": "USD Coin",
      "symbol": "USDC",
      "network": "mainnet"
    },
    "toAsset": {
      "name": "Tether USD",
      "symbol": "USDT",
      "network": "mainnet"
    },
    "toBlockchain": {
      "name": "optimism",
      "slug": "optimism"
    },
    "toWallet": {
      "name": "Optimism Mainnet Wallet",
      "address": "0xb55c054D8eE75224E1033e6eC775B4F62D942b43"
    },
    "metadata": {
      "swapAutoSettlement": {
        "rule": {
          "id": "rule-id-123",
          "name": "USDT to USDC on Base",
          "order": "RECOMMENDED",
          "slippageTolerance": 5,
          "source": {
            "assets": ["USDC", "USDT"],
            "minAmount": "1",
            "maxAmount": "1000"
          },
          "destination": {
            "blockchain": "optimism",
            "asset": "USDC",
            "address": "0x2455eC6700092991Ce0782365A89d5Cd89c8Fa22"
          }
        },
        "settleAmount": "5"
      },
      "transactionId": "transaction-id"
    }
  }
}
```

### **Identifying Auto-Settlement Transactions**

The best way to identify auto-settlement transactions is by checking the metadata field. Depending on the action, the metadata will contain one of these keys:

| Metadata Key             | Description                                                       |
| ------------------------ | ----------------------------------------------------------------- |
| `swapAutoSettlement`     | Present when the auto-settlement triggered a swap operation       |
| `gatewayAutoSettlement`  | Present when the auto-settlement triggered a Gateway operation    |
| `withdrawAutoSettlement` | Present when the auto-settlement triggered a withdrawal operation |

Each metadata object contains:

| Field          | Description                                                           |
| -------------- | --------------------------------------------------------------------- |
| `rule`         | Complete auto-settlement rule payload that triggered this transaction |
| `settleAmount` | Amount that was settled according to the rule                         |

<Note>
  When any of these metadata keys (`swapAutoSettlement`, `gatewayAutoSettlement`, or `withdrawAutoSettlement`) is present, the transaction was triggered by an auto-settlement rule. The `rule` field contains the complete rule configuration, not just an ID.
</Note>

### **Key Webhook Data Fields**

| Field          | Description                                                         |
| -------------- | ------------------------------------------------------------------- |
| `toAmount`     | Final amount received after swap (accounting for fees and slippage) |
| `rate`         | Exchange rate used for the swap                                     |
| `toAsset`      | Destination asset details (USDT in this example)                    |
| `toBlockchain` | Destination blockchain network (Optimism in this example)           |
| `toWallet`     | Destination wallet that received the converted assets               |
| `assetSwept`   | Whether the original assets were swept after conversion             |

## API Reference

### **Endpoints**

#### **Master Wallet Auto Settlements**

| Endpoint                                             | Method | Description                                  | API Reference                                                                |
| ---------------------------------------------------- | ------ | -------------------------------------------- | ---------------------------------------------------------------------------- |
| `/v1/wallets/{walletId}/auto-settlements/rules`      | GET    | List all settlement rules for master wallet  | [Get All Rules](/en/api-reference/auto-settlements/master-wallet-get-rules)  |
| `/v1/wallets/{walletId}/auto-settlements/rules`      | POST   | Create new settlement rule for master wallet | [Create Rule](/en/api-reference/auto-settlements/master-wallet-create-rule)  |
| `/v1/wallets/{walletId}/auto-settlements/rules/{id}` | GET    | Get specific master wallet rule details      | [Get Rule](/en/api-reference/auto-settlements/master-wallet-get-rule)        |
| `/v1/wallets/{walletId}/auto-settlements/rules/{id}` | PATCH  | Update existing master wallet rule           | [Update Rule](/en/api-reference/auto-settlements/master-wallet-update-rule)  |
| `/v1/wallets/{walletId}/auto-settlements/rules/{id}` | DELETE | Delete master wallet settlement rule         | [Delete Rule](/en/api-reference/auto-settlements/master-wallet-delete-rule)  |
| `/v1/wallets/{walletId}/auto-settlements`            | GET    | Get master wallet settlement history         | [Get Settlement](/en/api-reference/auto-settlements/master-wallet)           |
| `/v1/wallets/{walletId}/auto-settlements`            | PATCH  | Update master wallet settlement settings     | [Update Settlement](/en/api-reference/auto-settlements/master-wallet-update) |

#### **Child Address Auto Settlements**

| Endpoint                                                                   | Method | Description                                     | API Reference                                                                |
| -------------------------------------------------------------------------- | ------ | ----------------------------------------------- | ---------------------------------------------------------------------------- |
| `/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules`      | GET    | List all settlement rules for specific address  | [Get All Rules](/en/api-reference/auto-settlements/child-address-get-rules)  |
| `/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules`      | POST   | Create new settlement rule for specific address | [Create Rule](/en/api-reference/auto-settlements/child-address-create-rule)  |
| `/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules/{id}` | GET    | Get specific address rule details               | [Get Rule](/en/api-reference/auto-settlements/child-address-get-rule)        |
| `/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules/{id}` | PATCH  | Update existing address rule                    | [Update Rule](/en/api-reference/auto-settlements/child-address-update-rule)  |
| `/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules/{id}` | DELETE | Delete address settlement rule                  | [Delete Rule](/en/api-reference/auto-settlements/child-address-delete-rule)  |
| `/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements`            | GET    | Get address settlement history                  | [Get Settlement](/en/api-reference/auto-settlements/child-address)           |
| `/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements`            | PATCH  | Update address settlement settings              | [Update Settlement](/en/api-reference/auto-settlements/child-address-update) |

### **Rule Parameters**

| Parameter                | Type    | Required | Description                                                            |
| ------------------------ | ------- | -------- | ---------------------------------------------------------------------- |
| `name`                   | string  | Yes      | Rule name for identification                                           |
| `order`                  | string  | Yes      | Execution priority (FASTEST/CHEAPEST/RECOMMENDED/NO\_SLIPPAGE)         |
| `slippageTolerance`      | string  | No       | Maximum acceptable slippage (%). Use `-1` for unlimited (default)      |
| `isGateway`              | boolean | No       | Enable gateway functionality for the rule                              |
| `source.assets`          | array   | Yes      | Array of source assets to auto-settle                                  |
| `source.minAmount`       | string  | No       | Minimum amount to trigger settlement. Use `-1` for no minimum          |
| `source.maxAmount`       | string  | No       | Maximum amount per settlement. Use `-1` for unlimited                  |
| `destination.blockchain` | string  | Yes      | Target blockchain network                                              |
| `destination.asset`      | string  | Yes      | Target asset for conversion                                            |
| `destination.address`    | string  | No       | Destination address. If omitted, uses smart fallback logic (see above) |

## Getting Started

### **1. Enable Auto Settlements**

* Navigate to your wallet settings
* Enable auto-settlement functionality
* Configure default preferences

### **2. Create Your First Rule**

* Start with a simple USDT to ETH rule (or any asset you prefer)
* Set conservative slippage tolerance
* Choose your preferred destination chain and asset

### **3. Test and Monitor**

* Deploy on testnet first
* Monitor settlement success rates
* Adjust parameters as needed

### **4. Scale Gradually**

* Add rules for additional assets
* Implement batch processing
* Optimize for your use case

## Support and Resources

### **Getting Help**

* **Email**: [support@blockradar.co](mailto:support@blockradar.co)
* **API Reference**: [Auto Settlement Rules](/en/api-reference/auto-settlements/master-wallet)
* **Documentation**: [Gateway Configuration](/en/essentials/gateway)

<Note>
  Auto settlements are a powerful way to automate your treasury management. Start with simple rules and gradually add complexity as you become more familiar with the system.
</Note>