Child Address Create Rule

This endpoint allows you to create a new auto-settlement rule for a specific address. By providing the necessary parameters in the request body, you can define the conditions and actions for the auto-settlement process.

Send type on every create. When type is omitted this endpoint stores the rule in the legacy shape and silently discards isReward, rewardProvider, rewardType, useTransactionAmount, and deductionPercentage. Earn settlement and the balance/deduction controls therefore only work on a child address when you send an explicit type.

inheritance is never stored on a child-address rule — a rule that already lives on one address has nothing to cascade to. Set inheritance on the master-wallet rule instead.

Request Body Parameters

Parameter	Type	Required	Description
type	string	No	The settlement rule type: withdraw, swap, gateway, or earn. Strongly recommended — see the warning above. 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. Requires type: earn. Mainnet only, and cannot be combined with isGateway.
rewardProvider	string	Conditional	Required when isReward is true. Either fija or aave. Every source asset must be supported by that provider on the wallet’s blockchain.
rewardType	string	Conditional	Required when isReward is true. Must be regulated for fija and defi for aave.
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".
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 this address.
├─ 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 parent wallet’s 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}/addresses/{addressId}/auto-settlements/rules

cURL

Child Address Create Rule

curl --request POST \ --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/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" } } '

200

Gateway 200

{ "data": { "type": "gateway", "createdAt": "2025-08-26T17:27:37.369Z", "destination": { "address": "0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE", "asset": "USDC", "blockchain": "base" }, "id": "55869cbe-fa3a-44d2-a7e3-d65c08355e4d", "isActive": true, "isGateway": true, "name": "Swap from USDC to Gateway", "order": "FASTEST", "slippageTolerance": "5", "source": { "assets": [ "USDC" ], "blockchain": "base", "maxAmount": "1000", "minAmount": "1" }, "updatedAt": "2025-08-26T17:27:37.369Z" }, "message": "Auto settlement rule created successfully", "statusCode": 200 }

Authorizations

x-api-key · string · header · required

Path Parameters

walletId · string · required

Example:

"{{walletId}}"

addressId · string · required

Example:

"534e0480-f444-40c0-bc2e-2ef17bf7999e"

Body

application/json

destination · object · required

Show child attributes

source · object · required

Show child attributes

type · enum<string>

Settlement rule type. Send it on every create — without it the extended fields below are discarded.

Available options: withdraw, swap, gateway, earn

Example:

"swap"

isActive · boolean

Example:

true

isGateway · boolean

Route the settlement through Circle's Gateway. Required to be true when type is gateway.

Example:

true

isReward · boolean

Settle into an Earn position. Requires type earn, and is discarded when type is omitted. Mainnet only, and cannot be combined with isGateway.

Example:

false

rewardProvider · enum<string>

Earn provider. Required when isReward is true.

Available options: fija, aave

Example:

"aave"

rewardType · enum<string>

Earn strategy class. Must be regulated for fija and defi for aave.

Available options: regulated, defi

Example:

"defi"

useTransactionAmount · boolean

When false (default) the rule settles the address's current balance of the source asset; when true it settles only the triggering deposit amount. Discarded when type is omitted.

Example:

false

deductionPercentage · string

Percentage withheld from the settled amount before execution. Defaults to "0". Discarded when type is omitted.

Example:

"0"

name · string

Example:

"Swap from USDC to Gateway"

order · enum<string>

Routing preference for the swap leg. Defaults to RECOMMENDED and is ignored for gateway and earn rules.

Available options: FASTEST, CHEAPEST, RECOMMENDED, NO_SLIPPAGE

Example:

"FASTEST"

slippageTolerance · string

Acceptable slippage as a percentage. Defaults to "0"; use "-1" for unlimited.

Example:

"5"

Response

200 - application/json

Regular 200 / Gateway 200

data · object

Show child attributes

message · string

Example:

"Auto settlement rule created successfully"

statusCode · number

Example:

200