Auto Settlements

Automate asset settlements and conversions across blockchain networks

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:

1. API Key

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

2. Master Wallet Created

   Create a master wallet in the Blockradar Dashboard. Rules are configured per wallet — look one up with Get Wallet.

3. Destination Wallet

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

4. Sufficient Gas

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

5. Webhook Configured

   Set up webhooks to receive settlement notifications. The event family depends on which settlement type ran: swap.*, withdraw.*, gateway-deposit.*, or reward-deposit.*. See Webhook notifications below and the Webhooks guide 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.

Settlement Types

Every rule resolves to one of four settlement flows. Set it explicitly with the type field:

Type	What happens	Required companion field
withdraw	The source asset is transferred out as-is to destination.address on the same blockchain. No conversion.	destination.address, and destination.blockchain must equal the source blockchain
swap	The source asset is converted to a different asset and/or bridged to a different blockchain.	Source assets must differ from the destination asset when both are on the same chain
gateway	USDC is deposited into Circle’s Gateway unified balance.	isGateway: true
earn	Funds are deposited into an Earn position with Fija or Aave.	isReward: true

type is optional for backwards compatibility. Rules created before it existed have no type and keep their inferred behavior — Blockradar decides between withdraw and swap by comparing the source and destination asset and chain. Send type on every new rule so the flow is explicit, and send it on an update to migrate a legacy rule onto the explicit system.

On a child address, type is not just a hint. If you create a child-address rule without type, the extended fields — isReward, rewardProvider, rewardType, useTransactionAmount, and deductionPercentage — are silently discarded and the rule is stored in the legacy shape. Always send type when creating child-address rules.

Type validation rules

The API rejects contradictory combinations:

• type: gateway requires isGateway: true, and isGateway: true requires type: gateway
• type: earn requires isReward: true, and isReward: true requires type: earn
• A rule can never be both gateway and earn
• type: withdraw requires a destination.address, and the destination blockchain must equal the source blockchain
• type: swap rejects a source asset that equals the destination asset on the same blockchain
• Two rules on the same wallet cannot cover the same source asset on the same blockchain

Gateway rules can fall through to swap

A gateway rule only performs a Gateway deposit when the source chain and asset are Gateway-eligible. When they are not, the rule falls through and executes as a swap to destination.blockchain / destination.asset instead. The funds still settle, but you receive swap.* webhooks rather than gateway-deposit.*, so handle both when you configure gateway rules on chains outside Gateway’s supported set.

Auto Settlement Rules

Rule Components

Each auto-settlement rule defines the following parameters:

Component	Description	Example
Type	Settlement flow for the rule	withdraw, swap, gateway, earn
Rule Name	Descriptive name for your settlement rule	”Swap from USDC to Optimism USDC”
Order	Routing preference for the swap leg. Ignored for gateway and earn rules	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 except for withdraw rules) Specific address to receive converted assets. If not provided, smart fallback logic applies	0x2455eC6700092991Ce0782365A89d5Cd89c8Fa22
Is Gateway	Route the settlement through Circle’s Gateway	false
Is Reward	Route the settlement into an Earn position	false
Use Transaction Amount	Settle the triggering deposit amount instead of the address balance	false
Deduction Percentage	Percentage held back from the settled amount	”0”
Inheritance	Which child addresses a master-wallet rule cascades to	{ "mode": "all_children" }

How much gets settled

By default a settlement is sized from the address’s balance, not from the deposit that triggered it. Set useTransactionAmount to choose:

useTransactionAmount	What is settled
false (default)	The address’s current balance of the source asset — which can be more than the deposit that triggered the rule, for example when earlier deposits were left unsettled
true	Only the amount of the deposit that triggered the rule

The amount is then clamped and adjusted in this order:

1. The amount is compared against source.minAmount. Below it, nothing settles.
2. The amount is capped at source.maxAmount ("-1" means no cap).
3. deductionPercentage is withheld from what remains. "2.5" settles 97.5% and leaves 2.5% on the address.

Set useTransactionAmount: true when you need each deposit to map to exactly one settlement — reconciliation per payment, for example. Leave it false when you want the address swept clean each time.

Earn Settlement Rules

An earn rule deposits incoming funds into a yield position instead of transferring them out. It is the auto-settlement entry point to Earn.

Field	Value
type	earn
isReward	true
rewardProvider	fija or aave
rewardType	regulated for fija, defi for aave

Constraints:

• Mainnet only. Earn rules are rejected on testnet.
• Every asset in source.assets must be supported by the chosen provider on the wallet’s blockchain, otherwise the rule is rejected at creation.
• rewardProvider and rewardType must agree — fija is always regulated and aave is always defi.
• A rule cannot be both isGateway and isReward.

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 '{
    "type": "earn",
    "name": "Earn on Base USDC deposits",
    "isReward": true,
    "rewardProvider": "aave",
    "rewardType": "defi",
    "source": {
        "assets": ["USDC"],
        "minAmount": "10",
        "maxAmount": "-1"
    },
    "destination": {
        "blockchain": "base",
        "asset": "USDC"
    }
}'

Earn settlements create a REWARD_DEPOSIT transaction and emit reward-deposit.* webhooks.

Balance-based earn rules (useTransactionAmount: false) skip a new settlement while one is already pending or processing for the same address and asset — the in-flight settlement will absorb the newly arrived funds anyway. Amount-based earn rules (useTransactionAmount: true) are never skipped.

Rule Configuration Options

Amount Thresholds

• Minimum Amount: Only settle when the amount is above this threshold
• Maximum Amount: Cap the size of individual settlements
• Accumulation: With useTransactionAmount: false (the default), the rule settles the address’s whole balance of the source asset, so deposits that individually fell below minAmount are picked up together once the balance clears it

Slippage Protection

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

Before executing, the settlement fetches a quote and compares its slippage against your tolerance. If the quote exceeds the tolerance, the settlement fails rather than executing at a worse rate.

Always send slippageTolerance explicitly on swap rules. "-1" means unlimited, and a value like "5" means 5%. A tolerance of "0" only permits a settlement at exactly zero slippage, which rejects almost every real swap quote. Slippage tolerance is not used by gateway or earn rules.

Destination Address (Optional)

The destination.address field is optional for swap, gateway, and earn rules. 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.

withdraw rules are the exception: they require an explicit destination.address, and destination.blockchain must be the same blockchain as the source. destination.blockchain and destination.asset are always required, on every rule 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: By default, rules created on a master wallet apply to the master wallet and all child addresses under it. A rule on a child address takes precedence over the master wallet’s rules for the deposit it matches.

Rule Level	Scope	Behavior
Master Wallet Rules	The master wallet, plus the child addresses selected by the rule’s inheritance setting (all of them by default)	Default rules for the wallet hierarchy
Child Address Rules	Only that specific address	Take precedence over master wallet rules for any deposit they match

Rule Application Order

Precedence is evaluated per deposit, not per address:

1. Look for a matching child address rule. A rule matches when it is active and its source.assets and source.blockchain cover the deposit.
2. Fall back to the master wallet rules. A master rule is then considered only if its inheritance setting allows it to apply to the address that received the deposit.
3. No match at either level: no auto-settlement occurs.

A child address having some rules does not disable the master wallet’s rules for that address. If none of the child address’s rules match the deposited asset and chain, the master wallet rules are evaluated next. To stop a master rule from reaching an address, set that rule’s inheritance explicitly — see below.

Per-Rule Inheritance

Each master-wallet rule controls which child addresses it cascades to through the optional inheritance object:

mode	The rule applies to
all_children	The master wallet and every child address
master_only	The master wallet only — deposits on child addresses are ignored by this rule
selected_children	The master wallet plus the specific addresses listed in childAddressIds

Omitting inheritance entirely keeps the original behavior and is equivalent to all_children.

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 '{
    "type": "swap",
    "name": "Settle USDT deposits from partner addresses",
    "slippageTolerance": "1",
    "inheritance": {
        "mode": "selected_children",
        "childAddressIds": [
            "0f9a1c3e-58c2-4a1b-9f0d-6d5f2a7c1b34",
            "7b3d9e21-4f6a-4c0e-8a52-1c9b0e4d7f88"
        ]
    },
    "source": {
        "assets": ["USDT"],
        "minAmount": "1",
        "maxAmount": "-1"
    },
    "destination": {
        "blockchain": "optimism",
        "asset": "USDC"
    }
}'

Rules for selected_children:

• childAddressIds must be present and non-empty, otherwise the request fails with At least one child address must be selected.
• Every ID must be an active address belonging to your business on the same network.
• The addresses must match the wallet’s chain family. A rule on a non-EVM wallet (for example Tron, Solana, or Stellar) only accepts addresses on that same chain; a rule on an EVM wallet accepts any EVM address. A mismatch fails with One or more selected child addresses are not valid for this chain or are inactive.

inheritance only exists on master-wallet rules. A rule created directly on a child address has nothing to cascade to, so the field is ignored and never stored there.

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:

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:

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 '{
    "type": "swap",
    "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 '{
    "type": "swap",
    "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"
    }
}'

Copying Rules Across Wallets

Rules are per-blockchain, so rolling one strategy out across every chain you operate on means recreating the same rule many times. The copy endpoint does it in one call:

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/auto-settlements/rules/copy \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "rules": [
        {
            "type": "withdraw",
            "name": "Sweep USDC to treasury",
            "slippageTolerance": "0",
            "source": {
                "assets": ["USDC"],
                "minAmount": "1",
                "maxAmount": "-1"
            },
            "destination": {
                "blockchain": "base",
                "asset": "USDC",
                "address": "0x2455eC6700092991Ce0782365A89d5Cd89c8Fa22"
            }
        }
    ],
    "targetWalletIds": [
        "3f6c9a11-9a7e-4a3c-8f2b-0d51e6c4a7b2",
        "c81e7d40-5b6a-4f9e-9c3d-2a7f10b8e654"
    ]
}'

Rules are sent by value, not by ID, so the source can be a master wallet’s rules, a child address’s rules, or a payload you composed yourself. Each rule’s source.blockchain is rewritten to the target wallet’s own blockchain before it is saved.

Partial success is normal

The call returns 200 even when some rules are skipped or some wallets fail. Always read the response rather than relying on the status code:

{
  "data": {
    "summary": {
      "walletsTargeted": 2,
      "rulesRequested": 1,
      "applied": 1,
      "skipped": 1,
      "failed": 0
    },
    "results": [
      {
        "walletId": "3f6c9a11-9a7e-4a3c-8f2b-0d51e6c4a7b2",
        "walletName": "Base Mainnet Wallet",
        "chain": "base",
        "applied": [{ "name": "Sweep USDC to treasury" }],
        "skipped": []
      },
      {
        "walletId": "c81e7d40-5b6a-4f9e-9c3d-2a7f10b8e654",
        "walletName": "Optimism Mainnet Wallet",
        "chain": "optimism",
        "applied": [],
        "skipped": [
          {
            "name": "Sweep USDC to treasury",
            "reason": "A settlement rule for USDC already exists on the optimism wallet"
          }
        ]
      }
    ]
  },
  "message": "Settlement rules copied",
  "statusCode": 200
}

Outcome	Meaning
applied	The rule was written to that wallet
skipped	The rule was rejected for that wallet only — the asset is not enabled there, a rule already covers that asset on that chain, or the rule failed validation against that wallet
failed	The whole wallet could not be written, for example because it does not exist or is inactive on this network

Each target wallet is locked and written in its own transaction, so a failure on one target never leaves another partially written. Applying at least one rule to a wallet also switches auto-settlement on for that wallet.

The request itself fails with 400 when the rules array is malformed, when rules or targetWalletIds is empty, or when the only target listed is the source wallet (the source is always removed from the target list).

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

• Accumulation: Leave useTransactionAmount at false so small deposits settle together once the balance clears minAmount
• 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. Which event family you receive depends on the settlement type that ran:

Settlement type	Events
swap	swap.success, swap.failed, swap.cancelled, swap.processing
withdraw	withdraw.success, withdraw.failed, withdraw.cancelled, withdraw.processing
gateway	gateway-deposit.success, gateway-deposit.failed, gateway-deposit.cancelled, gateway-deposit.processing
earn	reward-deposit.success, reward-deposit.failed, reward-deposit.cancelled, reward-deposit.processing

A gateway rule on a chain that is not Gateway-eligible falls through to a swap, so it emits swap.* events instead of gateway-deposit.*. Subscribe to both if you run gateway rules outside Gateway’s supported chains.

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
rewardAutoSettlement	Present when the auto-settlement triggered an Earn deposit

The swap, gateway, and withdraw objects contain:

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

rewardAutoSettlement has a different shape — it carries the rule ID rather than the whole rule:

Field	Description
ruleId	ID of the earn rule that triggered this deposit
settleAmount	Amount that was settled according to the rule
sourceTransactionId	ID of the deposit transaction that triggered the settlement

When any of these metadata keys is present, the transaction was triggered by an auto-settlement rule. For swap, gateway, and withdraw settlements the rule field contains the complete rule configuration, not just an ID; for earn settlements, look up the rule with ruleId.

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/copy	POST	Copy settlement rules onto other master wallets	Copy Rules
/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

There is no copy endpoint for child addresses — copying always targets master wallets, though the rules you copy can come from a child address.

Update semantics differ by level

Endpoint	Body handling
PATCH /wallets/{walletId}/auto-settlements/rules/{id}	Partial merge. Send only the fields you are changing; everything else keeps its current value. Nested objects such as source and destination are replaced wholesale, so send them complete when you send them at all
PATCH /wallets/{walletId}/addresses/{addressId}/auto-settlements/rules/{id}	Full rule. source and destination are required, and any optional field you omit is reset to its default — order to RECOMMENDED, slippageTolerance and deductionPercentage to "0", useTransactionAmount to false, isActive to true, source.minAmount to "0", source.maxAmount to "-1"

Read the rule first and send the whole object back when updating a child address rule. Sending only the field you want to change will silently reset the rest of the rule to defaults.

In both cases the merged rule is re-validated, so an update can be rejected because of a field you did not send.

Rule Parameters

Parameter	Type	Required	Description
type	string	No	Settlement flow: withdraw, swap, gateway, or earn. Send it on every new rule
name	string	No	Rule name for identification
isActive	boolean	No	Whether the rule is enabled. Defaults to true
order	string	No	Routing preference (FASTEST/CHEAPEST/RECOMMENDED/NO_SLIPPAGE). Defaults to RECOMMENDED; ignored for gateway and earn rules
slippageTolerance	string	No	Maximum acceptable slippage (%). Use -1 for unlimited. Send it explicitly on swap rules
isGateway	boolean	No	Route through Circle’s Gateway. Required with type: gateway
isReward	boolean	No	Route into an Earn position. Required with type: earn. Mainnet only
rewardProvider	string	Conditional	fija or aave. Required when isReward is true
rewardType	string	Conditional	regulated for fija, defi for aave. Required when isReward is true
useTransactionAmount	boolean	No	false (default) settles the address balance; true settles only the triggering deposit
deductionPercentage	string	No	Percentage withheld from the settled amount. Defaults to "0"
inheritance.mode	string	No	master_only, all_children, or selected_children. Master-wallet rules only
inheritance.childAddressIds	array	Conditional	Required and non-empty when mode is selected_children
source.assets	array	Yes	Array of source assets to auto-settle
source.minAmount	string	No	Minimum amount to trigger settlement. Defaults to "0"
source.maxAmount	string	No	Maximum amount per settlement. Use -1 for unlimited (default)
source.blockchain	string	No	Ignored on create — always set to the wallet’s own blockchain
destination.blockchain	string	Yes	Target blockchain network. Must equal the source blockchain for withdraw rules
destination.asset	string	Yes	Target asset for conversion. Forced to USDC for gateway rules
destination.address	string	Conditional	Required for withdraw rules. Otherwise optional — 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: [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.