> ## Documentation Index > Fetch the complete documentation index at: https://docs.yiksipay.com/llms.txt > Use this file to discover all available pages before exploring further. # 自动结算 > 自动化跨区块链网络的资产结算和转换 概述
自动结算允许您根据配置的规则，将入金自动转换为任何区块链网络上的任何目标资产。这消除了手动交换或桥接资产的需要。 ## 前提条件 在配置自动结算之前，请确保您已完成以下步骤： 从 [Yiksi Pay 控制面板](https://dashboard.yiksipay.com) 获取您的 API 密钥。导航至 **Developers** 生成密钥。 通过 [创建钱包 API](/zh/api-reference/wallets/create-wallet) 或控制面板创建主钱包。 确保您的主钱包有足够的原生代币用于支付结算操作的 Gas 费用。 通过控制面板设置 Webhook 以接收自动结算通知。根据操作类型，您将收到 `swap.success`/`swap.failed` 或 `withdraw.success`/`withdraw.failed` 事件。详情请参阅 [Webhooks](/zh/essentials/webhooks)。 查看 [支持的资产](/zh/essentials/integrations) 以了解可用于自动结算的源资产和目标资产。 自动结算 ## 简介 自动结算允许您根据配置的规则，将入金自动转换为任何区块链网络上的任何目标资产。这消除了手动交换或桥接资产的需要，确保您的资金可以自动转换为您在多条链上首选的资产。 创建和管理自动结算规则以自动化资产转换。 根据您的规则自动将任何稳定币转换为任何其他资产。 无缝地将资产结算到任何区块链网络。 应用滑点容忍度和规则以防止不良执行。 ## 自动结算工作原理 ### **1. 规则创建** 定义结算规则，指定何时以及如何自动转换充值。 ### **2. 充值检测** 当资金到达您的地址时，Yiksi Pay 会自动检测符合规则的充值。 ### **3. 资产转换** 充值会自动交换为您选择链上的目标资产（通常是 USDC）。 ### **4. 余额统一** 所有转换的资产都会合并到您目标链上的单一统一余额中。 ## 自动结算规则 ### **规则组件** 每条自动结算规则定义以下参数： | 组件 | 描述 | 示例 | | ------------ | ------------------------------- | ------------------------------------------ | | **规则名称** | 结算规则的描述性名称 | "从 USDC 交换到 Optimism USDC" | | **顺序** | 执行优先级偏好 | FASTEST、CHEAPEST、RECOMMENDED、NO\_SLIPPAGE | | **滑点容忍度** | 最大可接受的价格偏差 (%)。使用 `-1` 表示无限滑点 | 5 或 -1 | | **源资产** | 要自动结算的资产数组 | \["USDC", "USDT"] | | **源最小/最大金额** | 控制触发结算的充值金额 | 最小: $1，最大: $1,000 | | **目标区块链** | 目标区块链网络 | optimism、base、ethereum | | **目标资产** | 转换的目标资产 | USDC、USDT、cNGN、DAI | | **目标地址** | (可选) 接收转换资产的特定地址。如未提供，将应用智能回退逻辑 | 0x2455eC6700092991Ce0782365A89d5Cd89c8Fa22 | ### **规则配置选项** #### **金额阈值** * **最小金额**：仅结算高于此阈值的充值 * **最大金额**：限制单次结算的金额上限 * **批量处理**：将多笔小额充值分组以提高效率 #### **滑点保护** * **无限**：`-1`（无滑点限制 - 默认行为） * **保守**：0.1% - 0.5%（最小价格影响） * **适中**：0.5% - 1.0%（平衡方法） * **激进**：1.0% - 2.0%（更快执行） 将 `slippageTolerance` 设置为 `-1` 表示无限滑点容忍度。如果未指定，这是默认行为，允许结算在任何价格偏差下执行。 #### **目标地址（可选）** `destination.address` 字段现在是可选的。如果未提供，系统会使用智能回退逻辑来确定接收地址： | 场景 | 回退行为 | | ---------------- | ----------- | | **提供了明确地址** | 使用指定的地址 | | **同链结算** | 使用充值地址（源地址） | | **EVM 到 EVM 跨链** | 在目标链上使用相同地址 | | **跨链（非 EVM 目标）** | 使用目标链的主钱包地址 | 对于大多数用例，您可以省略目标地址，让系统根据结算类型自动将资金路由到适当的地址。 #### **执行偏好** * **最快**：优先考虑速度而非成本 * **最便宜**：优化最低费用 * **推荐**：平衡速度、成本和可靠性 * **无滑点**：仅在无价格偏差时执行 ## 规则层级和优先级 ### **规则如何应用** **关键概念**：在主钱包上创建的规则会自动应用于该钱包下的所有子地址。但是，如果您直接在子地址上创建规则，这些规则将完全覆盖该特定地址的主钱包规则。 | 规则级别 | 范围 | 行为 | | --------- | ------------ | ------------ | | **主钱包规则** | 应用于主钱包和所有子地址 | 整个钱包层级的默认规则 | | **子地址规则** | 仅应用于该特定地址 | 存在时完全覆盖主钱包规则 | ### **规则应用顺序** 1. **检查子地址规则**：如果接收地址有自己的规则，则专门使用这些规则 2. **回退到主钱包规则**：如果没有子地址规则，则应用主钱包规则 3. **无规则**：如果两个级别都没有配置规则，则不进行自动结算 当子地址有自己的规则时，主钱包规则对该地址会被**完全忽略**——不会合并或组合规则。 ### **区块链特定规则** **重要**：规则是隔离的，并与每个区块链绑定。为一个区块链（如 Ethereum）配置的规则不会影响另一个区块链（如 Base 或 Optimism）上的充值。 这意味着： * 您必须为每个想要自动结算的源区块链创建单独的规则 * "Ethereum 上的 USDC" 规则不会触发 "Base 上的 USDC" * 这允许按链对结算行为进行精细控制 **示例**：如果您想将 Ethereum 和 Base 上的 USDC 充值都自动结算到 Optimism，您需要两条单独的规则： 1. Ethereum USDC → Optimism USDC 的规则 2. Base USDC → Optimism USDC 的规则 ### **各级别使用场景** #### **主钱包规则** * **一致策略**：所有子地址相同的结算行为 * **简化管理**：单一位置配置默认行为 * **批量操作**：一次性将规则应用于多个地址 * **标准化**：确保合规性和一致性 #### **子地址规则** * **测试**：在特定地址上尝试不同的结算策略 * **自定义要求**：地址特定的结算需求 * **覆盖默认**：为特定用例修改行为 * **精细控制**：为特定地址微调结算 ## 创建自动结算规则 ### **通过控制面板** 1. 导航到钱包的自动结算部分 2. 点击"创建新规则" 3. 配置规则参数 4. 设置金额阈值和滑点容忍度 5. 选择源资产和目标资产/链 6. 保存并激活规则 ### **通过 API** 使用自动结算规则 API 以编程方式创建结算规则： ```bash theme={null} curl --request POST \ --url https://api.yiksipay.com/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.yiksipay.com/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.failed` | 自动结算交换执行失败 | ### **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" } } } ``` ### **区分自动结算与常规交换** Webhook 载荷包含帮助识别自动结算交易的元数据： | 字段 | 描述 | | ------------------------------------------ | ---------------- | | `metadata.swapAutoSettlement.rule` | 触发此交换的完整自动结算规则载荷 | | `metadata.swapAutoSettlement.settleAmount` | 根据规则结算的金额 | | `metadata.transactionId` | 用于跟踪的内部交易 ID | 当 `metadata.swapAutoSettlement` 存在时，表示交换是由自动结算规则触发的。`rule` 字段包含完整的规则配置，而不仅仅是 ID。 ### **识别自动结算交易** 识别自动结算交易的最佳方式是检查 metadata 字段。根据操作类型，metadata 将包含以下键之一： | 元数据键 | 描述 | | ------------------------ | -------------- | | `swapAutoSettlement` | 当自动结算触发交换操作时存在 | | `withdrawAutoSettlement` | 当自动结算触发提现操作时存在 | ### **关键 Webhook 数据字段** | 字段 | 描述 | | -------------- | ----------------------- | | `toAmount` | 交换后收到的最终金额（扣除费用和滑点后） | | `rate` | 交换使用的汇率 | | `toAsset` | 目标资产详情（此示例中为 USDT） | | `toBlockchain` | 目标区块链网络（此示例中为 Optimism） | | `toWallet` | 接收转换资产的目标钱包 | | `assetSwept` | 转换后原始资产是否被归集 | ## API 参考 ### **端点** #### **主钱包自动结算** | 端点 | 方法 | 描述 | API 参考 | | ---------------------------------------------------- | ------ | ------------ | -------------------------------------------------------------------- | | `/v1/wallets/{walletId}/auto-settlements/rules` | GET | 列出主钱包的所有结算规则 | [获取所有规则](/zh/api-reference/auto-settlements/master-wallet-get-rules) | | `/v1/wallets/{walletId}/auto-settlements/rules` | POST | 为主钱包创建新结算规则 | [创建规则](/zh/api-reference/auto-settlements/master-wallet-create-rule) | | `/v1/wallets/{walletId}/auto-settlements/rules/{id}` | GET | 获取特定主钱包规则详情 | [获取规则](/zh/api-reference/auto-settlements/master-wallet-get-rule) | | `/v1/wallets/{walletId}/auto-settlements/rules/{id}` | PATCH | 更新现有主钱包规则 | [更新规则](/zh/api-reference/auto-settlements/master-wallet-update-rule) | | `/v1/wallets/{walletId}/auto-settlements/rules/{id}` | DELETE | 删除主钱包结算规则 | [删除规则](/zh/api-reference/auto-settlements/master-wallet-delete-rule) | | `/v1/wallets/{walletId}/auto-settlements` | GET | 获取主钱包结算历史 | [获取结算](/zh/api-reference/auto-settlements/master-wallet) | | `/v1/wallets/{walletId}/auto-settlements` | PATCH | 更新主钱包结算设置 | [更新结算](/zh/api-reference/auto-settlements/master-wallet-update) | #### **子地址自动结算** | 端点 | 方法 | 描述 | API 参考 | | -------------------------------------------------------------------------- | ------ | ------------- | -------------------------------------------------------------------- | | `/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules` | GET | 列出特定地址的所有结算规则 | [获取所有规则](/zh/api-reference/auto-settlements/child-address-get-rules) | | `/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules` | POST | 为特定地址创建新结算规则 | [创建规则](/zh/api-reference/auto-settlements/child-address-create-rule) | | `/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules/{id}` | GET | 获取特定地址规则详情 | [获取规则](/zh/api-reference/auto-settlements/child-address-get-rule) | | `/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules/{id}` | PATCH | 更新现有地址规则 | [更新规则](/zh/api-reference/auto-settlements/child-address-update-rule) | | `/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules/{id}` | DELETE | 删除地址结算规则 | [删除规则](/zh/api-reference/auto-settlements/child-address-delete-rule) | | `/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements` | GET | 获取地址结算历史 | [获取结算](/zh/api-reference/auto-settlements/child-address) | | `/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements` | PATCH | 更新地址结算设置 | [更新结算](/zh/api-reference/auto-settlements/child-address-update) | ### **规则参数** | 参数 | 类型 | 必需 | 描述 | | ------------------------ | ------ | -- | ------------------------------------------------ | | `name` | string | 是 | 用于识别的规则名称 | | `order` | string | 是 | 执行优先级（FASTEST/CHEAPEST/RECOMMENDED/NO\_SLIPPAGE） | | `slippageTolerance` | string | 否 | 最大可接受滑点 (%)。使用 `-1` 表示无限（默认） | | `source.assets` | array | 是 | 要自动结算的源资产数组 | | `source.minAmount` | string | 否 | 触发结算的最小金额。使用 `-1` 表示无最小值 | | `source.maxAmount` | string | 否 | 每次结算的最大金额。使用 `-1` 表示无限 | | `destination.blockchain` | string | 是 | 目标区块链网络 | | `destination.asset` | string | 是 | 转换的目标资产 | | `destination.address` | string | 否 | 目标地址。如果省略，使用智能回退逻辑（见上文） | ## 入门指南 ### **1. 启用自动结算** * 导航到钱包设置 * 启用自动结算功能 * 配置默认偏好 ### **2. 创建第一条规则** * 从简单的 USDT 到 ETH 规则开始（或您首选的任何资产） * 设置保守的滑点容忍度 * 选择您首选的目标链和资产 ### **3. 测试和监控** * 首先在测试网部署 * 监控结算成功率 * 根据需要调整参数 ### **4. 逐步扩展** * 为其他资产添加规则 * 实施批量处理 * 针对您的用例优化 ## 支持和资源 ### **获取帮助** * **邮箱**：[partner@yiksi.com](mailto:partner@yiksi.com) * **API 参考**：[自动结算规则](/zh/api-reference/auto-settlements/master-wallet) 自动结算是自动化资金管理的强大方式。从简单的规则开始，随着您对系统越来越熟悉，逐渐增加复杂性。