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

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
}

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

productKey

string

Pins a specific earn product for the rule. Only needed when a provider offers more than one product for a source asset; the rule must then have exactly one source asset.

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:

aave,

compound

Example:

"aave"

rewardType

enum<string>

Earn strategy class. Only defi is currently offered.

Available options:

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

API Documentation

Wallet

Addresses

Customer

Asset

Transactions

Withdraw

Withdraw Fiat

Signing

Swap

Liquidity Pool

Virtual Accounts

Deposit Fiat

Auto Settlements

Smart Contract

Gateway

Payment Links

AML

Asset Recovery

Miscellaneous

Rewards

Master Wallet Create Rule

Request Body Parameters

Authorizations

Path Parameters

Body

Response