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 in the Blockradar Dashboard. Rules are configured per wallet — look one up with Get 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. 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:

The amount is compared against source.minAmount. Below it, nothing settles.
The amount is capped at source.maxAmount ("-1" means no cap).
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:

Look for a matching child address rule. A rule matches when it is active and its source.assets and source.blockchain cover the deposit.
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.
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:

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 '{
    "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: [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

​Settlement Types

​Type validation rules

​Gateway rules can fall through to swap

​Auto Settlement Rules

​Rule Components

​How much gets settled

​Earn Settlement Rules

​Rule Configuration Options

​Amount Thresholds

​Slippage Protection

​Destination Address (Optional)

​Execution Preferences

​Rule Hierarchy and Precedence

​How Rules Apply

​Rule Application Order

​Per-Rule Inheritance

​Blockchain-Specific Rules

​Use Cases for Each Level

​Master Wallet Rules

​Child Address Rules

​Creating Auto Settlement Rules

​Via Dashboard

​Via API

​Copying Rules Across Wallets

​Partial success is normal

​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

​Update semantics differ by level

​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

Settlement Types

Type validation rules

Gateway rules can fall through to swap

Auto Settlement Rules

Rule Components

How much gets settled

Earn Settlement Rules

Rule Configuration Options

Amount Thresholds

Slippage Protection

Destination Address (Optional)

Execution Preferences

Rule Hierarchy and Precedence

How Rules Apply

Rule Application Order

Per-Rule Inheritance

Blockchain-Specific Rules

Use Cases for Each Level

Master Wallet Rules

Child Address Rules

Creating Auto Settlement Rules

Via Dashboard

Via API

Copying Rules Across Wallets

Partial success is normal

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

Update semantics differ by level

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