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": "gateway",
"destination": {
"blockchain": "base",
"asset": "USDC"
},
"isActive": true,
"isGateway": true,
"name": "Swap from USDC to Gateway",
"order": "FASTEST",
"slippageTolerance": "5",
"source": {
"assets": [
"USDC"
],
"maxAmount": "1000",
"minAmount": "1"
}
}
'{
"data": {
"id": "586db9b9-a6d8-4185-af72-395f21254eaf",
"type": "gateway",
"destination": {
"address": "0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE",
"asset": "USDC",
"blockchain": "base"
},
"isActive": true,
"isGateway": true,
"name": "Swap from USDC to Gateway",
"order": "FASTEST",
"slippageTolerance": "5",
"useTransactionAmount": false,
"deductionPercentage": "0",
"source": {
"assets": [
"USDC"
],
"blockchain": "base",
"maxAmount": "1000",
"minAmount": "1"
},
"createdAt": "2025-08-26T17:27:37.369Z",
"updatedAt": "2025-08-26T17:27:37.369Z"
},
"message": "Auto settlement rule created successfully",
"statusCode": 201
}Auto Settlements
Master Wallet Create Rule
This endpoint allows you to create a new auto-settlement rule for a specific wallet. By providing the necessary parameters in the request body, you can define the conditions and actions for the auto-settlement process.
Request Body Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| type | string | No | The settlement rule type: withdraw, swap, gateway, or earn. Recommended on every create; rules saved without it keep the legacy inferred behavior. withdraw settles each deposited source asset as-is to destination.address on the source blockchain (address required, and destination.blockchain must equal the source blockchain). swap converts to a different asset or chain. gateway requires isGateway: true; earn requires isReward: true. |
| name | string | No | The name of the auto-settlement rule. A descriptive title reflecting its purpose. |
| isActive | boolean | No | Whether the rule is enabled. Defaults to true. |
| order | string | No | Routing preference for the swap leg. Possible values: FASTEST, CHEAPEST, RECOMMENDED, NO_SLIPPAGE. Defaults to RECOMMENDED, and is ignored for gateway and earn rules. |
| slippageTolerance | string | No | The acceptable slippage tolerance (as a percentage). Example: "5" = 5% tolerance. Defaults to "0"; use "-1" for unlimited. |
| isGateway | boolean | No | Route the settlement through Circle’s Gateway into the unified USDC balance. Required to be true when type is gateway. |
| isReward | boolean | No | Settle into an Earn position instead of transferring the funds out. Required to be true when type is earn. Mainnet only, and cannot be combined with isGateway. |
| rewardProvider | string | Conditional | Required when isReward is true. One of aave or compound. Every source asset must be supported by that provider on the wallet’s blockchain. |
| rewardType | string | No | Strategy class (defi). Optional — defaults from the resolved product. |
| useTransactionAmount | boolean | No | Defaults to false, which settles the address’s current balance of the source asset. Set to true to settle only the amount of the deposit that triggered the rule. |
| deductionPercentage | string | No | Percentage withheld from the settled amount before execution, e.g. "2.5" leaves 2.5% behind. Defaults to "0". |
| inheritance | object | No | Controls which child addresses this master-wallet rule cascades to. Omit it to keep the legacy behavior, where the rule applies to the master wallet and every child address. |
| ├─ mode | string | Yes | One of master_only, all_children, or selected_children. |
| ├─ childAddressIds | array of strings | Conditional | Required and non-empty when mode is selected_children. Each address must be active, belong to this business and network, and match the wallet’s chain family. |
| source | object | Yes | Details about the source of the settlement. |
| ├─ assets | array of strings | Yes | List of asset symbols this rule settles (e.g., ["USDC"]). Source assets cannot overlap with another rule on the same blockchain. |
| ├─ minAmount | string | No | The minimum amount required for settlement (e.g., "1"). Defaults to "0". |
| ├─ maxAmount | string | No | The maximum amount that can be settled (e.g., "1000"). Defaults to "-1" (unlimited). |
| ├─ blockchain | string | No | Ignored on create — always set to the wallet’s own blockchain. |
| destination | object | Yes | Details about the destination of the settlement. |
| ├─ blockchain | string | Yes | The blockchain network for the destination. |
| ├─ asset | string | Yes | The asset the settlement is directed to. Gateway rules are forced to USDC. |
| ├─ address | string | Conditional | The address the settlement is sent to. Required for withdraw rules. When omitted, the smart fallback applies: same-chain settlements reuse the deposit address, EVM-to-EVM settlements reuse the same address on the destination chain, and other cross-chain settlements use the destination chain’s master wallet address. |
POST
/
v1
/
wallets
/
{walletId}
/
auto-settlements
/
rules
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": "gateway",
"destination": {
"blockchain": "base",
"asset": "USDC"
},
"isActive": true,
"isGateway": true,
"name": "Swap from USDC to Gateway",
"order": "FASTEST",
"slippageTolerance": "5",
"source": {
"assets": [
"USDC"
],
"maxAmount": "1000",
"minAmount": "1"
}
}
'{
"data": {
"id": "586db9b9-a6d8-4185-af72-395f21254eaf",
"type": "gateway",
"destination": {
"address": "0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE",
"asset": "USDC",
"blockchain": "base"
},
"isActive": true,
"isGateway": true,
"name": "Swap from USDC to Gateway",
"order": "FASTEST",
"slippageTolerance": "5",
"useTransactionAmount": false,
"deductionPercentage": "0",
"source": {
"assets": [
"USDC"
],
"blockchain": "base",
"maxAmount": "1000",
"minAmount": "1"
},
"createdAt": "2025-08-26T17:27:37.369Z",
"updatedAt": "2025-08-26T17:27:37.369Z"
},
"message": "Auto settlement rule created successfully",
"statusCode": 201
}Body
application/json

