自动结算 - Blockradar

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

前提条件

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

API 密钥

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

已创建 Master Wallet

通过 Create Wallet API 或控制台创建一个 master wallet。规则按 wallet 进行配置。

目标 Wallet

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

充足的 Gas

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

已配置 Webhook

设置 webhook 以接收结算通知。根据具体操作,您将收到 swap.success/swap.failed、gateway.success/gateway.failed 或 withdraw.success/withdraw.failed 等事件。详见 Webhooks。

工作原理

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

规则管理

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

资产转换

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

跨链

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

风险管理

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

自动结算如何运作

1. 创建规则

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

2. 检测存款

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

3. 资产转换

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

4. 余额统一

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

自动结算规则

规则组成部分

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

组件	说明	示例
规则名称	结算规则的描述性名称	”Swap from USDC to Optimism USDC”
Order	执行优先级偏好	FASTEST、CHEAPEST、RECOMMENDED、NO_SLIPPAGE
滑点容忍度	可接受的最大价格偏差(%)。使用 `-1` 表示不限制滑点	5 或 -1
源资产	待自动结算的资产数组	[“USDC”, “USDT”]
源最小/最大金额	控制触发结算的存款规模	最小: $1,最大:$ 1,000
目标区块链	目标区块链网络	optimism、base、ethereum
目标资产	转换的目标资产	USDC、USDT、cNGN、DAI
目标地址	(可选)用于接收已转换资产的特定地址。若未提供,将使用智能回退逻辑	0x2455eC6700092991Ce0782365A89d5Cd89c8Fa22
Is Gateway	为该规则启用 gateway 功能	false

规则配置选项

金额阈值

最小金额:仅结算高于此阈值的存款
最大金额:限制单次结算的金额上限
批量处理:将多笔小额存款合并以提升效率

滑点保护

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

将 slippageTolerance 设为 -1 表示滑点容忍度不受限制。如未指定,这就是默认行为,允许结算无视价格偏差地执行。

目标地址(可选)

destination.address 字段现已变为可选。如果未提供,系统会使用智能回退逻辑来确定收款地址:

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

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

执行偏好

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

规则的层级与优先级

规则的应用方式

关键概念:在 master wallet 上创建的规则会自动应用到该 wallet 下的所有 child address。但若您直接在某个 child address 上创建规则,这些规则将完全覆盖该地址对应的 master wallet 规则。

规则级别	范围	行为
Master Wallet 规则	适用于该 master wallet 及其所有 child address	整个 wallet 层级的默认规则
Child Address 规则	仅适用于该特定地址	存在时完全覆盖 master wallet 规则

规则应用顺序

检查 Child Address 规则:若收款地址有自身规则,则仅使用这些规则
回退到 Master Wallet 规则:若不存在 child address 规则,则应用 master wallet 规则
没有规则:若两个层级都未配置规则,则不会进行任何自动结算

当 child address 拥有自己的规则时,master wallet 的规则对该地址将被完全忽略——不会进行规则的合并或叠加。

针对特定区块链的规则

重要:规则相互隔离并绑定到各自的区块链。为某条区块链(例如 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 '{
    "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 '{
    "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"
    }
}'

使用场景

资金库管理

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

业务运营

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

DeFi 集成

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

最佳实践

规则配置

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

风险管理

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

运营效率

批量处理:将小额存款合并以提升效率
时机优化:考虑网络拥堵规律
成本分析:在速度与成本之间取得平衡
监控:为失败的结算配置告警

监控与告警

控制台监控

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

Webhook 通知

执行自动结算时会触发 webhook 事件:

事件	说明
`swap.success`	自动结算的 swap 已成功执行
`swap.failed`	自动结算的 swap 执行失败

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`	当自动结算触发了一次提现操作时出现

每个 metadata 对象包含:

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

当 swapAutoSettlement、gatewayAutoSettlement 或 withdrawAutoSettlement 中任意一个 metadata 键存在时,该笔交易就是由自动结算规则触发的。rule 字段包含完整的规则配置,而不仅仅是一个 ID。

关键 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/{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

规则参数

参数	类型	是否必填	说明
`name`	string	是	用于标识规则的名称
`order`	string	是	执行优先级(FASTEST/CHEAPEST/RECOMMENDED/NO_SLIPPAGE)
`slippageTolerance`	string	否	可接受的最大滑点(%)。使用 `-1` 表示不限制(默认)
`isGateway`	boolean	否	为该规则启用 gateway 功能
`source.assets`	array	是	待自动结算的源资产数组
`source.minAmount`	string	否	触发结算的最小金额。使用 `-1` 表示无下限
`source.maxAmount`	string	否	单次结算的最大金额。使用 `-1` 表示不限制
`destination.blockchain`	string	是	目标区块链网络
`destination.asset`	string	是	转换的目标资产
`destination.address`	string	否	目标地址。若省略,将采用智能回退逻辑(见上文)

快速开始

1. 启用自动结算

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

2. 创建您的第一条规则

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

3. 测试与监控

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

4. 逐步扩展

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

支持与资源

获取帮助

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

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

​前提条件

​工作原理

规则管理

资产转换

跨链

风险管理

​自动结算如何运作

​1. 创建规则

​2. 检测存款

​3. 资产转换

​4. 余额统一

​自动结算规则

​规则组成部分

​规则配置选项

​金额阈值

​滑点保护

​目标地址(可选)

​执行偏好

​规则的层级与优先级

​规则的应用方式

​规则应用顺序

​针对特定区块链的规则

​各级别的使用场景

​Master Wallet 规则

​Child Address 规则

​创建自动结算规则

​通过控制台

​通过 API

​使用场景

​资金库管理

​业务运营

​DeFi 集成

​最佳实践

​规则配置

​风险管理

​运营效率

​监控与告警

​控制台监控

​Webhook 通知

​Webhook 负载示例

​识别自动结算交易

​关键 Webhook 数据字段

​API 参考

​端点

​Master Wallet 自动结算

​Child Address 自动结算

​规则参数

​快速开始

​1. 启用自动结算

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

​3. 测试与监控

​4. 逐步扩展

​支持与资源

​获取帮助

前提条件

工作原理

自动结算如何运作

1. 创建规则

2. 检测存款

3. 资产转换

4. 余额统一

自动结算规则

规则组成部分

规则配置选项

金额阈值

滑点保护

目标地址(可选)

执行偏好

规则的层级与优先级

规则的应用方式

规则应用顺序

针对特定区块链的规则

各级别的使用场景

Master Wallet 规则

Child Address 规则

创建自动结算规则

通过控制台

通过 API

使用场景

资金库管理

业务运营

DeFi 集成

最佳实践

规则配置

风险管理

运营效率

监控与告警

控制台监控

Webhook 通知

Webhook 负载示例

识别自动结算交易

关键 Webhook 数据字段

API 参考

端点

Master Wallet 自动结算

Child Address 自动结算

规则参数

快速开始

1. 启用自动结算

2. 创建您的第一条规则

3. 测试与监控

4. 逐步扩展

支持与资源

获取帮助