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

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

Auto Settlements

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`. Must be `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 `defi`.
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

wallets

{walletId}

addresses

{addressId}

auto-settlements

rules

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

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

授权

x-api-key

string

header

必填

路径参数

walletId

string

必填

示例:

"{{walletId}}"

addressId

string

必填

示例:

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

请求体

application/json

destination

object

必填

Show child attributes

source

object

必填

Show child attributes

type

enum<string>

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

可用选项:

withdraw,

swap,

gateway,

earn

示例:

"swap"

isActive

boolean

示例:

true

isGateway

boolean

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

示例:

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.

示例:

false

rewardProvider

enum<string>

Earn provider. Required when isReward is true.

可用选项:

aave

示例:

"aave"

rewardType

enum<string>

Earn strategy class. Only defi is currently offered.

可用选项:

defi

示例:

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

示例:

false

deductionPercentage

string

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

示例:

"0"

name

string

示例:

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

可用选项:

FASTEST,

CHEAPEST,

RECOMMENDED,

NO_SLIPPAGE

示例:

"FASTEST"

slippageTolerance

string

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

示例:

"5"

响应

200 - application/json

Regular 200 / Gateway 200

data

object

Show child attributes

message

string

示例:

"Auto settlement rule created successfully"

statusCode

number

示例:

200