Auto Settlements - Blockradar

In a nutshell
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.

Prerequisites

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

API Key

Get your API key from the Blockradar Dashboard. Navigate to Developers to generate one.

Master Wallet Created

Create a master wallet via the Create Wallet API or dashboard. Rules are configured per wallet.

Destination Wallet

If settling cross-chain, ensure you have a wallet on the destination blockchain to receive converted assets.

Sufficient Gas

Fund your wallets with native tokens (ETH, BNB, MATIC, etc.) to cover swap and transfer fees.

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 for details.

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.

Rules Management

Create and manage auto-settlement rules to automate asset conversions.

Asset Conversion

Automatically convert any stablecoin to any other asset based on your rules.

Cross-Chain

Settle assets to any blockchain network seamlessly.

Risk Management

Apply slippage tolerance and rules to protect against poor executions.

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)

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

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

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.

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

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.

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

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

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.

Blockchain-Specific Rules

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

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:

Rule for Ethereum USDC → Optimism USDC
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

Navigate to your wallet’s Auto Settlements section
Click “Create New Rule”
Configure rule parameters
Set amount thresholds and slippage tolerance
Choose source and destination assets/chains
Save and activate the rule

Via API

Create settlement rules programmatically using the Auto Settlement Rules API:

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"
    }
}'

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.

With explicit destination address:

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

{
  "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

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.

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
`/v1/wallets/{walletId}/auto-settlements/rules`	POST	Create new settlement rule for master wallet	Create Rule
`/v1/wallets/{walletId}/auto-settlements/rules/{id}`	GET	Get specific master wallet rule details	Get Rule
`/v1/wallets/{walletId}/auto-settlements/rules/{id}`	PATCH	Update existing master wallet rule	Update Rule
`/v1/wallets/{walletId}/auto-settlements/rules/{id}`	DELETE	Delete master wallet settlement rule	Delete Rule
`/v1/wallets/{walletId}/auto-settlements`	GET	Get master wallet settlement history	Get Settlement
`/v1/wallets/{walletId}/auto-settlements`	PATCH	Update master wallet settlement settings	Update Settlement

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
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules`	POST	Create new settlement rule for specific address	Create Rule
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules/{id}`	GET	Get specific address rule details	Get Rule
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules/{id}`	PATCH	Update existing address rule	Update Rule
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules/{id}`	DELETE	Delete address settlement rule	Delete Rule
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements`	GET	Get address settlement history	Get Settlement
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements`	PATCH	Update address settlement settings	Update Settlement

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: [email protected]
API Reference: Auto Settlement Rules
Documentation: Gateway Configuration

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.

​Prerequisites

​How It Works

Rules Management

Asset Conversion

Cross-Chain

Risk Management

​How Auto Settlements Work

​1. Rule Creation

​2. Deposit Detection

​3. Asset Conversion

​4. Balance Unification

​Auto Settlement Rules

​Rule Components

​Rule Configuration Options

​Amount Thresholds

​Slippage Protection

​Destination Address (Optional)

​Execution Preferences

​Rule Hierarchy and Precedence

​How Rules Apply

​Rule Application Order

​Blockchain-Specific Rules

​Use Cases for Each Level

​Master Wallet Rules

​Child Address Rules

​Creating Auto Settlement Rules

​Via Dashboard

​Via API

​Use Cases

​Treasury Management

​Business Operations

​DeFi Integration

​Best Practices

​Rule Configuration

​Risk Management

​Operational Efficiency

​Monitoring and Alerts

​Dashboard Monitoring

​Webhook Notifications

​Webhook Payload Example

​Identifying Auto-Settlement Transactions

​Key Webhook Data Fields

​API Reference

​Endpoints

​Master Wallet Auto Settlements

​Child Address Auto Settlements

​Rule Parameters

​Getting Started

​1. Enable Auto Settlements

​2. Create Your First Rule

​3. Test and Monitor

​4. Scale Gradually

​Support and Resources

​Getting Help

Prerequisites

How It Works

How Auto Settlements Work

1. Rule Creation

2. Deposit Detection

3. Asset Conversion

4. Balance Unification

Auto Settlement Rules

Rule Components

Rule Configuration Options

Amount Thresholds

Slippage Protection

Destination Address (Optional)

Execution Preferences

Rule Hierarchy and Precedence

How Rules Apply

Rule Application Order

Blockchain-Specific Rules

Use Cases for Each Level

Master Wallet Rules

Child Address Rules

Creating Auto Settlement Rules

Via Dashboard

Via API

Use Cases

Treasury Management

Business Operations

DeFi Integration

Best Practices

Rule Configuration

Risk Management

Operational Efficiency

Monitoring and Alerts

Dashboard Monitoring

Webhook Notifications

Webhook Payload Example

Identifying Auto-Settlement Transactions

Key Webhook Data Fields

API Reference

Endpoints

Master Wallet Auto Settlements

Child Address Auto Settlements

Rule Parameters

Getting Started

1. Enable Auto Settlements

2. Create Your First Rule

3. Test and Monitor

4. Scale Gradually

Support and Resources

Getting Help