Auto Settlements

Automate asset settlements and conversions across blockchain networks

Introduction

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 (%)	5
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	Specific address to receive converted assets	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

• Conservative: 0.1% - 0.5% (minimal price impact)
• Moderate: 0.5% - 1.0% (balanced approach)
• Aggressive: 1.0% - 2.0% (faster execution)

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

Rule Application Order

1. Child Address Rules: Applied first if they exist
2. Master Wallet Rules: Applied as fallback if no child address rules
3. Default Behavior: No auto-settlement if no rules are configured

Override Behavior

• Child Address Override: Address-specific rules completely override master wallet rules
• No Inheritance: Child addresses don’t inherit master wallet rules when they have their own
• Independent Configuration: Each level can have completely different settlement strategies

Use Cases for Each Level

Master Wallet Rules

• Consistent Strategy: Same settlement behavior across all 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:

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

Distinguishing Auto-Settlements from Regular Swaps

The webhook payload includes metadata that helps identify auto-settlement transactions:

Field	Description
metadata.swapAutoSettlement.rule	Complete auto-settlement rule payload that triggered this swap
metadata.swapAutoSettlement.settleAmount	Amount that was settled according to the rule
metadata.transactionId	Internal transaction ID for tracking

When metadata.swapAutoSettlement is present, the swap 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	number	Yes	Maximum acceptable slippage (%)
isGateway	boolean	false	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
source.maxAmount	string	No	Maximum amount per settlement
destination.blockchain	string	Yes	Target blockchain network
destination.asset	string	Yes	Target asset for conversion
destination.address	string	Yes	Destination address to receive converted assets

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: [e-mail]
• 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.