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

Master Wallet Create Rule

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

200

Gateway 200

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

Authorizations

x-api-key · string · header · required

Path Parameters

walletId · string · required

Example:

"{{walletId}}"

Body

application/json

destination · object · required

Show child attributes

source · object · required

Show child attributes

type · enum<string>

Settlement rule type. Recommended on every create; rules saved without it keep the legacy inferred behavior.

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. Required to be true when type is earn. 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.

Example:

false

deductionPercentage · string

Percentage withheld from the settled amount before execution. Defaults to "0".

Example:

"0"

inheritance · object

Controls which child addresses this master-wallet rule cascades to. Omit for the legacy behavior (master wallet plus every child address).

Show child attributes

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:

201