自动结算 - Blockradar

简而言之
自动结算会自动将到账存款转换为您在任意区块链上偏好的资产。规则只需定义一次,所有匹配的存款都会被自动兑换并路由到您的目标链——无需任何手动干预。

前提条件

在配置自动结算规则之前,请确保具备以下条件:

API 密钥

在 Blockradar 控制台获取您的 API 密钥。前往 Developers 进行生成。

已创建 Master Wallet

在 Blockradar 控制台创建一个 master wallet。规则按 wallet 进行配置——可通过 Get Wallet 查询。

目标 Wallet

如需进行跨链结算,请确保在目标区块链上已有可用于接收已转换资产的 wallet。

充足的 Gas

请向您的 wallet 充值原生代币(ETH、BNB、MATIC 等),以支付 swap 与转账的手续费。

已配置 Webhook

设置 webhook 以接收结算通知。事件族取决于实际执行的结算类型:swap.*、withdraw.*、gateway-deposit.* 或 reward-deposit.*。详见下文的 Webhook 通知以及 Webhooks 指南。

工作原理

自动结算可以根据您配置的规则,将到账存款自动转换为任意区块链网络上的目标资产。这样无需手动进行 swap 或 bridge,即可让您的资金库自动按偏好转换为多条链上的目标资产。

规则管理

创建并管理自动结算规则,实现资产转换的自动化。

资产转换

根据您的规则,自动将任意稳定币转换为其他资产。

跨链

无缝地在任意区块链网络上完成资产结算。

风险管理

应用滑点容忍度与规则,防止出现不利的执行结果。

自动结算如何运作

1. 创建规则

定义结算规则,明确何时以及如何对存款进行自动转换。

2. 检测存款

当资金到达您的地址时,Blockradar 会自动检测与您规则匹配的存款。

3. 资产转换

存款会被自动 swap 为您所选链上的目标资产(通常是 USDC)。

4. 余额统一

所有已转换的资产都会汇总为您目标链上的统一余额。

结算类型

每条规则最终都会归结为四种结算流程之一。请通过 type 字段显式指定:

类型	规则的行为	必须搭配的字段
`withdraw`	将源资产原样转出到同一条区块链上的 `destination.address`,不做任何转换。	`destination.address`,且 `destination.blockchain` 必须与源区块链相同
`swap`	转换为其他资产,和/或跨到其他区块链。	当源资产与目标资产位于同一条链时,两者必须不同
`gateway`	将 USDC 存入 Circle Gateway 的统一余额。	`isGateway: true`
`earn`	存入 Fija 或 Aave 的 Earn 仓位。	`isReward: true`

出于向后兼容,type 是可选的。在该字段出现之前创建的规则没有 type,并保留其推断行为:Blockradar 通过比较源与目标的资产和链来判定属于 withdraw 还是 swap。请在每条新规则上发送 type 以明确流程,并在更新时发送它,以将旧规则迁移到显式类型体系。

在子地址上,type 不只是一个提示。如果创建子地址规则时不带 type,扩展字段——isReward、rewardProvider、rewardType、useTransactionAmount 和 deductionPercentage——会被静默丢弃,规则将以旧格式保存。创建子地址规则时请务必发送 type。

按类型的校验规则

API 会拒绝互相矛盾的组合:

type: gateway 要求 isGateway: true,而 isGateway: true 要求 type: gateway
type: earn 要求 isReward: true,而 isReward: true 要求 type: earn
一条规则永远不能同时是 gateway 和 earn
type: withdraw 要求提供 destination.address,且目标区块链必须与源区块链相同
type: swap 会拒绝与目标资产在同一条链上相同的源资产
同一个 wallet 上的两条规则不能覆盖同一条链上的同一种源资产

gateway 规则可能回退为 swap

只有当源链和源资产符合 Gateway 的支持条件时,gateway 规则才会执行 Gateway 存款。若不符合,该规则会回退并以 swap 的方式执行到 destination.blockchain / destination.asset。资金照常完成结算,但您收到的是 swap.* 而非 gateway-deposit.* webhook。因此在 Gateway 支持范围之外的链上配置 gateway 规则时,请同时处理这两类事件。

自动结算规则

规则组成部分

每条自动结算规则包含以下参数:

组件	说明	示例
Type	该规则的结算流程	withdraw、swap、gateway、earn
规则名称	结算规则的描述性名称	”Swap from USDC to Optimism USDC”
Order	swap 环节的路由偏好。gateway 和 earn 规则会忽略该字段	FASTEST、CHEAPEST、RECOMMENDED、NO_SLIPPAGE
滑点容忍度	可接受的最大价格偏差(%)。使用 `-1` 表示不限制滑点	5 或 -1
源资产	待自动结算的资产数组	[“USDC”, “USDT”]
源最小/最大金额	控制触发结算的存款规模	最小: $1,最大:$ 1,000
目标区块链	目标区块链网络	optimism、base、ethereum
目标资产	转换的目标资产	USDC、USDT、cNGN、DAI
目标地址	(withdraw 规则以外为可选)用于接收已转换资产的特定地址。若未提供,将使用智能回退逻辑	0x2455eC6700092991Ce0782365A89d5Cd89c8Fa22
Is Gateway	通过 Circle Gateway 路由该笔结算	false
Is Reward	将结算路由到 Earn 仓位	false
Use Transaction Amount	结算触发本次规则的存款金额,而非地址余额	false
Deduction Percentage	从结算金额中扣留的百分比	”0”
Inheritance	master wallet 规则会向哪些子地址传递	`{ "mode": "all_children" }`

实际结算多少金额

默认情况下,结算金额取自地址余额,而不是触发它的那笔存款。可用 useTransactionAmount 选择:

`useTransactionAmount`	结算的金额
`false` (默认)	该地址上源资产的当前余额。它可能大于触发规则的存款,例如此前有存款未被结算时
`true`	仅触发本次规则的那笔存款金额

随后金额会按以下顺序调整:

与 source.minAmount 比较。低于该值则不结算。
按 source.maxAmount 封顶("-1" 表示不封顶)。
从剩余金额中扣留 deductionPercentage。"2.5" 表示结算 97.5%,并把 2.5% 留在地址上。

当您需要每笔存款恰好对应一次结算时(例如逐笔对账),请设置 useTransactionAmount: true。若希望每次都把地址清空,则保持为 false。

Earn 结算规则

earn 规则会把入账资金存入收益仓位,而不是转出。它是自动结算通往 Earn 的入口。

字段	取值
`type`	`earn`
`isReward`	`true`
`rewardProvider`	`fija` 或 `aave`
`rewardType`	`fija` 对应 `regulated`,`aave` 对应 `defi`

约束条件:

仅限主网。 earn 规则在测试网会被拒绝。
source.assets 中的每种资产都必须被所选提供方在该 wallet 的区块链上支持,否则规则在创建时即被拒绝。
rewardProvider 与 rewardType 必须一致:fija 始终为 regulated,aave 始终为 defi。
一条规则不能同时为 isGateway 和 isReward。

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": "earn",
    "name": "Earn on Base USDC deposits",
    "isReward": true,
    "rewardProvider": "aave",
    "rewardType": "defi",
    "source": {
        "assets": ["USDC"],
        "minAmount": "10",
        "maxAmount": "-1"
    },
    "destination": {
        "blockchain": "base",
        "asset": "USDC"
    }
}'

Earn 结算会创建一笔 REWARD_DEPOSIT 交易,并发出 reward-deposit.* webhook。

基于余额的 earn 规则(useTransactionAmount: false)在同一地址、同一资产已有结算处于 pending 或 processing 状态时会跳过新的结算,因为进行中的结算本就会吸收新到账的资金。基于金额的 earn 规则(useTransactionAmount: true)则永远不会被跳过。

规则配置选项

金额阈值

最小金额:仅在金额高于此阈值时才结算
最大金额:限制单次结算的金额上限
累积:当 useTransactionAmount: false(默认值)时,规则会结算该地址上源资产的全部余额,因此单笔低于 minAmount 的存款会在余额超过该阈值后被一并取走

滑点保护

不限制:-1(无滑点上限)
保守:0.1% - 0.5%(对价格影响最小)
适中:0.5% - 1.0%(均衡策略)
激进:1.0% - 2.0%(执行更快)

执行前,结算会先获取报价,并将报价的滑点与您的容忍度比较。若报价超出容忍度,结算会直接失败,而不会以更差的价格成交。

在 swap 规则上请始终显式发送 slippageTolerance。"-1" 表示不限制,"5" 之类的值表示 5%。容忍度为 "0" 只允许滑点恰好为零的结算,几乎会拒绝所有真实报价。gateway 和 earn 规则不使用滑点容忍度。

目标地址(可选)

destination.address 字段在 swap、gateway 和 earn 规则中为可选。如果未提供,系统会使用智能回退逻辑来确定收款地址:

场景	回退行为
显式提供地址	使用指定的地址
同链结算	使用存款地址(源地址)
EVM 之间的跨链	在目标链上使用相同地址
跨链(目标为非 EVM)	使用目标链上 master wallet 的地址

对于大多数用例,您可以省略目标地址,让系统根据结算类型自动将资金路由到合适的地址。

执行偏好

Fastest:速度优先,而非成本
Cheapest:优化为最低手续费
Recommended:在速度、成本与可靠性之间取得平衡
No Slippage:仅在无价格偏差时执行

规则的层级与优先级

规则的应用方式

关键概念:默认情况下,在 master wallet 上创建的规则会应用到该 master wallet 及其下所有 child address。对于某笔与之匹配的存款,child address 上的规则优先于 master wallet 的规则。

规则级别	范围	行为
Master Wallet 规则	该 master wallet,以及由规则的 `inheritance` 设置所选中的 child address(默认为全部)	wallet 层级的默认规则
Child Address 规则	仅该特定地址	对任何与之匹配的存款,优先于 master wallet 规则

规则应用顺序

优先级是逐笔存款评估的,而不是按地址评估:

先在该 child address 上寻找匹配的规则。 规则处于启用状态,且其 source.assets 与 source.blockchain 覆盖该笔存款时,即为匹配。
回退到 master wallet 规则。 此时只有当某条 master wallet 规则的 inheritance 设置允许它作用于收到该存款的地址时,才会被纳入考虑。
两个层级都没有匹配:不会进行任何自动结算。

child address 上存在某些规则,并不会使 master wallet 的规则对该地址失效。如果该 child address 的规则都不匹配存入的资产与链,系统会继续评估 master wallet 的规则。若要阻止某条 master wallet 规则作用到某个地址,请显式设置该规则的 inheritance,见下文。

按规则的继承设置

每条 master wallet 规则都通过可选的 inheritance 对象控制自己会传递到哪些 child address:

`mode`	规则作用范围
`all_children`	该 master wallet 及其所有 child address
`master_only`	仅该 master wallet——该规则会忽略 child address 上的存款
`selected_children`	该 master wallet,以及 `childAddressIds` 中列出的特定地址

完全省略 inheritance 将保持原有行为,等同于 all_children。

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": "swap",
    "name": "Settle USDT deposits from partner addresses",
    "slippageTolerance": "1",
    "inheritance": {
        "mode": "selected_children",
        "childAddressIds": [
            "0f9a1c3e-58c2-4a1b-9f0d-6d5f2a7c1b34",
            "7b3d9e21-4f6a-4c0e-8a52-1c9b0e4d7f88"
        ]
    },
    "source": {
        "assets": ["USDT"],
        "minAmount": "1",
        "maxAmount": "-1"
    },
    "destination": {
        "blockchain": "optimism",
        "asset": "USDC"
    }
}'

selected_children 的规则要求:

childAddressIds 必须存在且非空,否则请求会以 At least one child address must be selected 失败。
每个 ID 都必须是同一网络下、属于您商户的启用状态地址。
这些地址必须与该 wallet 属于同一链系。非 EVM wallet(例如 Tron、Solana 或 Stellar)上的规则只接受同一条链的地址;EVM wallet 上的规则接受任意 EVM 地址。不匹配时会以 One or more selected child addresses are not valid for this chain or are inactive 失败。

inheritance 只存在于 master wallet 规则上。直接创建在 child address 上的规则没有可传递的对象,因此该字段会被忽略,也不会保存在那里。

针对特定区块链的规则

重要:规则相互隔离并绑定到各自的区块链。为某条区块链(例如 Ethereum)配置的规则不会影响其他区块链(例如 Base 或 Optimism)上的存款。

这意味着:

您必须为每条希望自动结算的源区块链分别创建规则
一条针对 “Ethereum 上的 USDC” 的规则不会对 “Base 上的 USDC” 生效
这样可以按链对结算行为实现细粒度控制

示例:如果您希望同时将 Ethereum 与 Base 上的 USDC 自动结算到 Optimism,需要创建两条独立规则:

Ethereum USDC → Optimism USDC 的规则
Base USDC → Optimism USDC 的规则

各级别的使用场景

Master Wallet 规则

统一策略:所有 child address 采用相同的结算行为
简化管理:在单一位置配置默认行为
批量操作:一次性应用规则到多个地址
标准化:确保合规与一致性

Child Address 规则

测试:在特定地址上尝试不同的结算策略
定制需求:满足特定地址的结算需求
覆盖默认:针对特定用例修改行为
细粒度控制:对特定地址精细调整结算

创建自动结算规则

通过控制台

进入您 wallet 的 Auto Settlements 区域
点击 “Create New Rule”
配置规则参数
设置金额阈值与滑点容忍度
选择源/目标资产与链
保存并启用规则

通过 API

可使用 Auto Settlement Rules API 以编程方式创建结算规则:

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": "swap",
    "name": "Swap from USDC to Optimism USDC",
    "order": "FASTEST",
    "slippageTolerance": "-1",
    "source": {
        "assets": [
            "USDC",
            "USDT"
        ],
        "minAmount": "1",
        "maxAmount": "1000"
    },
    "destination": {
        "blockchain": "optimism",
        "asset": "USDC"
    }
}'

在此示例中,slippageTolerance 被设为 -1 表示不限制滑点,且 destination.address 被省略。系统会自动使用智能回退逻辑来确定收款地址。

带有显式目标地址的示例:

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": "swap",
    "name": "Swap from USDC to Optimism USDC",
    "order": "FASTEST",
    "slippageTolerance": "5",
    "source": {
        "assets": [
            "USDC",
            "USDT"
        ],
        "minAmount": "1",
        "maxAmount": "1000"
    },
    "destination": {
        "blockchain": "optimism",
        "asset": "USDC",
        "address": "0x2455eC6700092991Ce0782365A89d5Cd89c8Fa22"
    }
}'

在多个 wallet 之间复制规则

规则是按区块链划分的,因此要把同一套策略铺开到您运营的每一条链上,就意味着要把同一条规则重建很多次。复制端点可以一次调用完成:

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/auto-settlements/rules/copy \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "rules": [
        {
            "type": "withdraw",
            "name": "Sweep USDC to treasury",
            "slippageTolerance": "0",
            "source": {
                "assets": ["USDC"],
                "minAmount": "1",
                "maxAmount": "-1"
            },
            "destination": {
                "blockchain": "base",
                "asset": "USDC",
                "address": "0x2455eC6700092991Ce0782365A89d5Cd89c8Fa22"
            }
        }
    ],
    "targetWalletIds": [
        "3f6c9a11-9a7e-4a3c-8f2b-0d51e6c4a7b2",
        "c81e7d40-5b6a-4f9e-9c3d-2a7f10b8e654"
    ]
}'

规则是按值发送的,而不是按 ID,因此来源可以是某个 master wallet 的规则、某个 child address 的规则,或您自己拼装的 payload。每条规则的 source.blockchain 在保存前都会被改写为目标 wallet 自身的区块链。

部分成功是正常情况

即使有些规则被跳过、有些 wallet 失败,该调用仍会返回 200。请始终读取响应内容,而不要依赖状态码:

{
  "data": {
    "summary": {
      "walletsTargeted": 2,
      "rulesRequested": 1,
      "applied": 1,
      "skipped": 1,
      "failed": 0
    },
    "results": [
      {
        "walletId": "3f6c9a11-9a7e-4a3c-8f2b-0d51e6c4a7b2",
        "walletName": "Base Mainnet Wallet",
        "chain": "base",
        "applied": [{ "name": "Sweep USDC to treasury" }],
        "skipped": []
      },
      {
        "walletId": "c81e7d40-5b6a-4f9e-9c3d-2a7f10b8e654",
        "walletName": "Optimism Mainnet Wallet",
        "chain": "optimism",
        "applied": [],
        "skipped": [
          {
            "name": "Sweep USDC to treasury",
            "reason": "A settlement rule for USDC already exists on the optimism wallet"
          }
        ]
      }
    ]
  },
  "message": "Settlement rules copied",
  "statusCode": 200
}

结果	含义
`applied`	该规则已写入这个 wallet
`skipped`	该规则仅在这个 wallet 上被拒绝:该资产未在此启用、该链上已有规则覆盖了这种资产,或该规则未通过针对这个 wallet 的校验
`failed`	整个 wallet 都无法写入,例如它不存在或在当前网络下处于停用状态

每个目标 wallet 都会被加锁并在各自的事务中写入,因此某一个目标失败时,绝不会让另一个只写入了一半。只要有一条规则被应用到某个 wallet,也会同时开启该 wallet 的自动结算。

当 rules 数组格式有误、rules 或 targetWalletIds 为空,或列出的唯一目标就是源 wallet 时(源 wallet 始终会从目标列表中移除),请求本身会以 400 失败。

使用场景

资金库管理

灵活的资产转换:可转换为任意偏好资产(USDC、ETH、USDT 等)
跨链运营:在多条网络中维护余额
自动化归集:无需任何手动干预
多资产策略:支持多种资产偏好与策略

业务运营

支付处理:自动将到账款项结算为偏好资产
收入管理:将多种稳定币转换为指定的目标资产
风险缓解:自动应用滑点保护
资产多样化:自动维持目标资产配置

DeFi 集成

流动性挖矿:自动将奖励结算为偏好资产
流动性管理:汇总 LP 奖励与手续费
投资组合再平衡:维持目标资产配置

最佳实践

规则配置

从保守开始:以较低的滑点容忍度起步
监控表现:跟踪结算的成功率
逐步调整:根据市场情况逐步优化规则
在测试网测试:在主网部署前先验证规则

风险管理

滑点限制:设置合适的容忍度
金额上限:限制最大结算规模
网络选择:选择可靠的目标链
回退规则:创建备用结算方案

运营效率

累积:将 useTransactionAmount 保持为 false,让小额存款在余额超过 minAmount 后被一并结算
时机优化:考虑网络拥堵规律
成本分析:在速度与成本之间取得平衡
监控:为失败的结算配置告警

监控与告警

控制台监控

规则状态:启用/停用状态指示
结算历史:跟踪成功与失败的结算
性能指标:成功率与执行时长
资产余额:监控统一余额的增长情况

Webhook 通知

执行自动结算时会触发 webhook 事件。您收到哪一族事件,取决于实际执行的结算类型:

结算类型	事件
`swap`	`swap.success`、`swap.failed`、`swap.cancelled`、`swap.processing`
`withdraw`	`withdraw.success`、`withdraw.failed`、`withdraw.cancelled`、`withdraw.processing`
`gateway`	`gateway-deposit.success`、`gateway-deposit.failed`、`gateway-deposit.cancelled`、`gateway-deposit.processing`
`earn`	`reward-deposit.success`、`reward-deposit.failed`、`reward-deposit.cancelled`、`reward-deposit.processing`

在不符合 Gateway 支持条件的链上,gateway 规则会回退为 swap,因此发出的是 swap.* 而非 gateway-deposit.* 事件。若您在 Gateway 支持范围之外的链上使用 gateway 规则,请同时订阅这两类事件。

Webhook 负载示例

{
  "event": "swap.success",
  "data": {
    "id": "99a2b490-0798-460b-9265-4d99f182fe52",
    "reference": "ZMxcorDGtf",
    "senderAddress": "0xAA2d5fd5e7bE97E214f8565DCf3a4862719960b5",
    "recipientAddress": "0xb55c054D8eE75224E1033e6eC775B4F62D942b43",
    "amount": "5",
    "status": "SUCCESS",
    "type": "SWAP",
    "network": "mainnet",
    "toAmount": "4.965398",
    "rate": "0.9930796000000001",
    "asset": {
      "name": "USD Coin",
      "symbol": "USDC",
      "network": "mainnet"
    },
    "toAsset": {
      "name": "Tether USD",
      "symbol": "USDT",
      "network": "mainnet"
    },
    "toBlockchain": {
      "name": "optimism",
      "slug": "optimism"
    },
    "toWallet": {
      "name": "Optimism Mainnet Wallet",
      "address": "0xb55c054D8eE75224E1033e6eC775B4F62D942b43"
    },
    "metadata": {
      "swapAutoSettlement": {
        "rule": {
          "id": "rule-id-123",
          "name": "USDT to USDC on Base",
          "order": "RECOMMENDED",
          "slippageTolerance": 5,
          "source": {
            "assets": ["USDC", "USDT"],
            "minAmount": "1",
            "maxAmount": "1000"
          },
          "destination": {
            "blockchain": "optimism",
            "asset": "USDC",
            "address": "0x2455eC6700092991Ce0782365A89d5Cd89c8Fa22"
          }
        },
        "settleAmount": "5"
      },
      "transactionId": "transaction-id"
    }
  }
}

识别自动结算交易

识别自动结算交易最可靠的方式是查看 metadata 字段。根据具体操作,metadata 中会包含以下键之一:

metadata 键	说明
`swapAutoSettlement`	当自动结算触发了一次 swap 操作时出现
`gatewayAutoSettlement`	当自动结算触发了一次 Gateway 操作时出现
`withdrawAutoSettlement`	当自动结算触发了一次提现操作时出现
`rewardAutoSettlement`	当自动结算触发了一次 Earn 存入时出现

swap、gateway 和提现对应的对象包含:

字段	说明
`rule`	触发该交易的自动结算规则的完整 payload
`settleAmount`	根据该规则结算的金额

rewardAutoSettlement 的结构不同——它携带规则的 ID,而不是完整规则:

字段	说明
`ruleId`	触发该笔存入的 earn 规则 ID
`settleAmount`	根据该规则结算的金额
`sourceTransactionId`	触发该次结算的存款交易 ID

当上述任意一个 metadata 键存在时,该笔交易就是由自动结算规则触发的。对于 swap、gateway 和提现结算,rule 字段包含完整的规则配置,而不仅仅是一个 ID;对于 earn 结算,请通过 ruleId 查询对应规则。

关键 Webhook 数据字段

字段	说明
`toAmount`	swap 后实际收到的最终金额(已扣除手续费与滑点)
`rate`	swap 所采用的汇率
`toAsset`	目标资产详情(本示例中为 USDT)
`toBlockchain`	目标区块链网络(本示例中为 Optimism)
`toWallet`	接收已转换资产的目标 wallet
`assetSwept`	是否在转换后对原始资产进行了 sweep

API 参考

端点

Master Wallet 自动结算

端点	方法	说明	API 参考
`/v1/wallets/{walletId}/auto-settlements/rules`	GET	列出 master wallet 的所有结算规则	Get All Rules
`/v1/wallets/{walletId}/auto-settlements/rules`	POST	为 master wallet 创建新的结算规则	Create Rule
`/v1/wallets/{walletId}/auto-settlements/rules/copy`	POST	将结算规则复制到其他 master wallet	Copy Rules
`/v1/wallets/{walletId}/auto-settlements/rules/{id}`	GET	获取 master wallet 某条规则的详情	Get Rule
`/v1/wallets/{walletId}/auto-settlements/rules/{id}`	PATCH	更新已有的 master wallet 规则	Update Rule
`/v1/wallets/{walletId}/auto-settlements/rules/{id}`	DELETE	删除 master wallet 的结算规则	Delete Rule
`/v1/wallets/{walletId}/auto-settlements`	GET	获取 master wallet 的结算历史	Get Settlement
`/v1/wallets/{walletId}/auto-settlements`	PATCH	更新 master wallet 的结算设置	Update Settlement

Child Address 自动结算

端点	方法	说明	API 参考
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules`	GET	列出某个特定地址的所有结算规则	Get All Rules
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules`	POST	为某个特定地址创建新的结算规则	Create Rule
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules/{id}`	GET	获取某个特定地址下某条规则的详情	Get Rule
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules/{id}`	PATCH	更新已有的地址规则	Update Rule
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules/{id}`	DELETE	删除地址的结算规则	Delete Rule
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements`	GET	获取地址的结算历史	Get Settlement
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements`	PATCH	更新地址的结算设置	Update Settlement

child address 没有对应的复制端点:复制的目标始终是 master wallet,尽管被复制的规则本身可以来自某个 child address。

不同层级的更新语义不同

端点	body 处理方式
`PATCH /wallets/{walletId}/auto-settlements/rules/{id}`	部分合并。只需发送要修改的字段,其余字段保持当前值。`source` 和 `destination` 等嵌套对象会被整体替换,因此发送时请发送完整对象
`PATCH /wallets/{walletId}/addresses/{addressId}/auto-settlements/rules/{id}`	完整规则。 `source` 和 `destination` 为必填,且您省略的任何可选字段都会被重置为默认值:`order` 变为 `RECOMMENDED`,`slippageTolerance` 与 `deductionPercentage` 变为 `"0"`,`useTransactionAmount` 变为 `false`,`isActive` 变为 `true`,`source.minAmount` 变为 `"0"`,`source.maxAmount` 变为 `"-1"`

更新 child address 规则时,请先读取该规则,再把完整对象发送回去。只发送想要修改的那个字段,会静默地把规则的其余部分重置为默认值。

两种情况下,合并后的规则都会被重新校验,因此更新可能因为某个您并未发送的字段而被拒绝。

规则参数

参数	类型	是否必填	说明
`type`	string	否	结算流程:`withdraw`、`swap`、`gateway` 或 `earn`。请在每条新规则上发送
`name`	string	否	用于标识规则的名称
`isActive`	boolean	否	规则是否启用。默认为 `true`
`order`	string	否	路由偏好(FASTEST/CHEAPEST/RECOMMENDED/NO_SLIPPAGE)。默认为 `RECOMMENDED`;gateway 和 earn 规则会忽略
`slippageTolerance`	string	否	可接受的最大滑点(%)。使用 `-1` 表示不限制。swap 规则请显式发送
`isGateway`	boolean	否	通过 Circle Gateway 路由。搭配 `type: gateway` 时必填
`isReward`	boolean	否	路由到 Earn 仓位。搭配 `type: earn` 时必填。仅限主网
`rewardProvider`	string	条件必填	`fija` 或 `aave`。当 `isReward` 为 `true` 时必填
`rewardType`	string	条件必填	`fija` 对应 `regulated`,`aave` 对应 `defi`。当 `isReward` 为 `true` 时必填
`useTransactionAmount`	boolean	否	`false`(默认)结算地址余额;`true` 仅结算触发本次规则的存款
`deductionPercentage`	string	否	从结算金额中扣留的百分比。默认为 `"0"`
`inheritance.mode`	string	否	`master_only`、`all_children` 或 `selected_children`。仅适用于 master wallet 规则
`inheritance.childAddressIds`	array	条件必填	当模式为 `selected_children` 时必填且非空
`source.assets`	array	是	待自动结算的源资产数组
`source.minAmount`	string	否	触发结算的最小金额。默认为 `"0"`
`source.maxAmount`	string	否	单次结算的最大金额。使用 `-1` 表示不限制(默认)
`source.blockchain`	string	否	创建时会被忽略——始终设置为该 wallet 自身的区块链
`destination.blockchain`	string	是	目标区块链网络。`withdraw` 规则必须与源链相同
`destination.asset`	string	是	转换的目标资产。gateway 规则会强制为 USDC
`destination.address`	string	条件必填	`withdraw` 规则必填。其他情况下可选,将采用智能回退逻辑(见上文)

快速开始

1. 启用自动结算

进入您的 wallet 设置
启用自动结算功能
配置默认偏好

2. 创建您的第一条规则

从一条简单的 USDT 到 ETH 的规则开始(或您偏好的任意资产)
设置较保守的滑点容忍度
选择您偏好的目标链与目标资产

3. 测试与监控

先在测试网部署
监控结算成功率
按需调整参数

4. 逐步扩展

为更多资产添加规则
引入批量处理
针对您的用例进行优化

支持与资源

获取帮助

电子邮件:[email protected]
API 参考:Auto Settlement Rules
文档:Gateway 配置

自动结算是自动化资金库管理的强大方式。请从简单的规则开始,在熟悉系统后再逐步增加复杂度。

​前提条件

​工作原理

规则管理

资产转换

跨链

风险管理

​自动结算如何运作

​1. 创建规则

​2. 检测存款

​3. 资产转换

​4. 余额统一

​结算类型

​按类型的校验规则

​gateway 规则可能回退为 swap

​自动结算规则

​规则组成部分

​实际结算多少金额

​Earn 结算规则

​规则配置选项

​金额阈值

​滑点保护

​目标地址(可选)

​执行偏好

​规则的层级与优先级

​规则的应用方式

​规则应用顺序

​按规则的继承设置

​针对特定区块链的规则

​各级别的使用场景

​Master Wallet 规则

​Child Address 规则

​创建自动结算规则

​通过控制台

​通过 API

​在多个 wallet 之间复制规则

​部分成功是正常情况

​使用场景

​资金库管理

​业务运营

​DeFi 集成

​最佳实践

​规则配置

​风险管理

​运营效率

​监控与告警

​控制台监控

​Webhook 通知

​Webhook 负载示例

​识别自动结算交易

​关键 Webhook 数据字段

​API 参考

​端点

​Master Wallet 自动结算

​Child Address 自动结算

​不同层级的更新语义不同

​规则参数

​快速开始

​1. 启用自动结算

​2. 创建您的第一条规则

​3. 测试与监控

​4. 逐步扩展

​支持与资源

​获取帮助

前提条件

工作原理

自动结算如何运作

1. 创建规则

2. 检测存款

3. 资产转换

4. 余额统一

结算类型

按类型的校验规则

gateway 规则可能回退为 swap

自动结算规则

规则组成部分

实际结算多少金额

Earn 结算规则

规则配置选项

金额阈值

滑点保护

目标地址(可选)

执行偏好

规则的层级与优先级

规则的应用方式

规则应用顺序

按规则的继承设置

针对特定区块链的规则

各级别的使用场景

Master Wallet 规则

Child Address 规则

创建自动结算规则

通过控制台

通过 API

在多个 wallet 之间复制规则

部分成功是正常情况

使用场景

资金库管理

业务运营

DeFi 集成

最佳实践

规则配置

风险管理

运营效率

监控与告警

控制台监控

Webhook 通知

Webhook 负载示例

识别自动结算交易

关键 Webhook 数据字段

API 参考

端点

Master Wallet 自动结算

Child Address 自动结算

不同层级的更新语义不同

规则参数

快速开始

1. 启用自动结算

2. 创建您的第一条规则

3. 测试与监控

4. 逐步扩展

支持与资源

获取帮助