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

授权

x-api-key

string

header

必填

路径参数

walletId

string

必填

示例:

"{{walletId}}"

请求体

application/json

destination

object

必填

Show child attributes

source

object

必填

Show child attributes

type

enum<string>

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

可用选项:

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

示例:

false

deductionPercentage

string

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

示例:

"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

示例:

"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

示例:

201