> ## Documentation Index > Fetch the complete documentation index at: https://docs.blockradar.co/llms.txt > Use this file to discover all available pages before exploring further. # 自动结算 > 在区块链网络之间自动完成资产结算与转换 简而言之
自动结算会自动将到账存款转换为您在任意区块链上偏好的资产。规则只需定义一次,所有匹配的存款都会被自动兑换并路由到您的目标链——无需任何手动干预。 自动结算 ## 前提条件 在配置自动结算规则之前,请确保具备以下条件: 在 [Blockradar 控制台](https://dashboard.blockradar.co)获取您的 API 密钥。前往 **Developers** 进行生成。 通过 [Create Wallet API](/en/api-reference/wallets/create-wallet) 或控制台创建一个 master wallet。规则按 wallet 进行配置。 如需进行跨链结算,请确保在目标区块链上已有可用于接收已转换资产的 wallet。 请向您的 wallet 充值原生代币(ETH、BNB、MATIC 等),以支付 swap 与转账的手续费。 设置 webhook 以接收结算通知。根据具体操作,您将收到 `swap.success`/`swap.failed`、`gateway.success`/`gateway.failed` 或 `withdraw.success`/`withdraw.failed` 等事件。详见 [Webhooks](/en/essentials/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 规则 | ### **规则应用顺序** 1. **检查 Child Address 规则**:若收款地址有自身规则,则仅使用这些规则 2. **回退到 Master Wallet 规则**:若不存在 child address 规则,则应用 master wallet 规则 3. **没有规则**:若两个层级都未配置规则,则不会进行任何自动结算 当 child address 拥有自己的规则时,master wallet 的规则对该地址将被**完全忽略**——不会进行规则的合并或叠加。 ### **针对特定区块链的规则** **重要**:规则相互隔离并绑定到各自的区块链。为某条区块链(例如 Ethereum)配置的规则不会影响其他区块链(例如 Base 或 Optimism)上的存款。 这意味着: * 您必须为每条希望自动结算的源区块链分别创建规则 * 一条针对 "Ethereum 上的 USDC" 的规则不会对 "Base 上的 USDC" 生效 * 这样可以按链对结算行为实现细粒度控制 **示例**:如果您希望同时将 Ethereum 与 Base 上的 USDC 自动结算到 Optimism,需要创建两条独立规则: 1. Ethereum USDC → Optimism USDC 的规则 2. Base USDC → Optimism USDC 的规则 ### **各级别的使用场景** #### **Master Wallet 规则** * **统一策略**:所有 child address 采用相同的结算行为 * **简化管理**:在单一位置配置默认行为 * **批量操作**:一次性应用规则到多个地址 * **标准化**:确保合规与一致性 #### **Child Address 规则** * **测试**:在特定地址上尝试不同的结算策略 * **定制需求**:满足特定地址的结算需求 * **覆盖默认**:针对特定用例修改行为 * **细粒度控制**:对特定地址精细调整结算 ## 创建自动结算规则 ### **通过控制台** 1. 进入您 wallet 的 Auto Settlements 区域 2. 点击 "Create New Rule" 3. 配置规则参数 4. 设置金额阈值与滑点容忍度 5. 选择源/目标资产与链 6. 保存并启用规则 ### **通过 API** 可使用 Auto Settlement Rules API 以编程方式创建结算规则: ```bash theme={null} curl --request POST \ --url https://api.blockradar.co/v1/wallets/{walletId}/auto-settlements/rules \ --header 'Content-Type: application/json' \ --header 'x-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` 被省略。系统会自动使用智能回退逻辑来确定收款地址。 **带有显式目标地址的示例:** ```bash theme={null} curl --request POST \ --url https://api.blockradar.co/v1/wallets/{walletId}/auto-settlements/rules \ --header 'Content-Type: application/json' \ --header 'x-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 负载示例** ```json theme={null} { "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](/en/api-reference/auto-settlements/master-wallet-get-rules) | | `/v1/wallets/{walletId}/auto-settlements/rules` | POST | 为 master wallet 创建新的结算规则 | [Create Rule](/en/api-reference/auto-settlements/master-wallet-create-rule) | | `/v1/wallets/{walletId}/auto-settlements/rules/{id}` | GET | 获取 master wallet 某条规则的详情 | [Get Rule](/en/api-reference/auto-settlements/master-wallet-get-rule) | | `/v1/wallets/{walletId}/auto-settlements/rules/{id}` | PATCH | 更新已有的 master wallet 规则 | [Update Rule](/en/api-reference/auto-settlements/master-wallet-update-rule) | | `/v1/wallets/{walletId}/auto-settlements/rules/{id}` | DELETE | 删除 master wallet 的结算规则 | [Delete Rule](/en/api-reference/auto-settlements/master-wallet-delete-rule) | | `/v1/wallets/{walletId}/auto-settlements` | GET | 获取 master wallet 的结算历史 | [Get Settlement](/en/api-reference/auto-settlements/master-wallet) | | `/v1/wallets/{walletId}/auto-settlements` | PATCH | 更新 master wallet 的结算设置 | [Update Settlement](/en/api-reference/auto-settlements/master-wallet-update) | #### **Child Address 自动结算** | 端点 | 方法 | 说明 | API 参考 | | -------------------------------------------------------------------------- | ------ | ---------------- | ---------------------------------------------------------------------------- | | `/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules` | GET | 列出某个特定地址的所有结算规则 | [Get All Rules](/en/api-reference/auto-settlements/child-address-get-rules) | | `/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules` | POST | 为某个特定地址创建新的结算规则 | [Create Rule](/en/api-reference/auto-settlements/child-address-create-rule) | | `/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules/{id}` | GET | 获取某个特定地址下某条规则的详情 | [Get Rule](/en/api-reference/auto-settlements/child-address-get-rule) | | `/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules/{id}` | PATCH | 更新已有的地址规则 | [Update Rule](/en/api-reference/auto-settlements/child-address-update-rule) | | `/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules/{id}` | DELETE | 删除地址的结算规则 | [Delete Rule](/en/api-reference/auto-settlements/child-address-delete-rule) | | `/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements` | GET | 获取地址的结算历史 | [Get Settlement](/en/api-reference/auto-settlements/child-address) | | `/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements` | PATCH | 更新地址的结算设置 | [Update Settlement](/en/api-reference/auto-settlements/child-address-update) | ### **规则参数** | 参数 | 类型 | 是否必填 | 说明 | | ------------------------ | ------- | ---- | ------------------------------------------------ | | `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. 逐步扩展** * 为更多资产添加规则 * 引入批量处理 * 针对您的用例进行优化 ## 支持与资源 ### **获取帮助** * **电子邮件**:[support@blockradar.co](mailto:support@blockradar.co) * **API 参考**:[Auto Settlement Rules](/en/api-reference/auto-settlements/master-wallet) * **文档**:[Gateway 配置](/en/essentials/gateway) 自动结算是自动化资金库管理的强大方式。请从简单的规则开始,在熟悉系统后再逐步增加复杂度。