From b4757226c68d9e93590a63af38a0d2b84242d41f Mon Sep 17 00:00:00 2001 From: rcsh <163504257+rcsh1@users.noreply.github.com> Date: Fri, 19 Jun 2026 10:51:59 +0800 Subject: [PATCH] Recover doc-writing-core run_964261ecdd69 edits from trace log --- .../get-started-asset-wallets.mdx | 27 ++++++++++++++++++- .../get-started-asset-wallets.mdx | 27 ++++++++++++++++++- 2 files changed, 52 insertions(+), 2 deletions(-) diff --git a/v2/guides/custodial-wallets/get-started-asset-wallets.mdx b/v2/guides/custodial-wallets/get-started-asset-wallets.mdx index e9569183..6eea4586 100644 --- a/v2/guides/custodial-wallets/get-started-asset-wallets.mdx +++ b/v2/guides/custodial-wallets/get-started-asset-wallets.mdx @@ -18,6 +18,7 @@ Following this guide, you'll learn how to: 3. Deposit tokens into the wallet and track the transaction status 4. Withdraw tokens from the wallet 5. Query wallet balances +6. Automatically sweep funds to a designated address This guide uses the [development environment](/v2/guides/overview/environments) in all its code samples. It is recommended that you use the development environment to test your new features first before deploying them to the production environment. @@ -640,4 +641,28 @@ public class ListTokenBalancesExample { } } ``` - \ No newline at end of file + + +## 6. Sweep funds automatically (auto-sweep) + +Auto-sweep automatically consolidates tokens from your deposit addresses into a designated sweep-to address, so that you do not need to move funds out of each deposit address manually. To create an auto-sweep task, call the [Create auto-sweep task](/v2/api-references/autosweep/create-auto-sweep-task) operation and specify the following: + +- `wallet_id`: The ID of the wallet you created. +- `token_id`: The ID of the token to sweep. +- `min_balance_threshold`: (Optional) The minimum token balance an address must hold to be swept. Addresses holding less than this value are skipped, which lets you filter out dust. There is no per-address blocklist; use `min_balance_threshold` to control the minimum sweep amount. + + +A sweep moves tokens out of a deposit address, which requires native chain coin to pay for gas. Make sure that gas is available either in the source deposit address or through a configured Fee Station or Auto Fueling. Reaching the deposit threshold alone does not complete a sweep: if no gas is available, the sweep cannot be broadcast. When a sweep cannot proceed, the reason is reported in the `failed_reasons` array returned by the task details. + + +### Retrieve the swept transactions + +The Create auto-sweep task operation returns immediately with a `task_id`. At this point the task `status` is `Submitted` and the `transaction_ids` array is empty. This is expected and does not indicate a failure. + +The task transitions to `TransactionCreated` once it triggers one or more sweep transactions, at which point `transaction_ids` is populated. To retrieve the transaction IDs, poll the [Get auto-sweep task details](/v2/api-references/autosweep/get-auto-sweep-task-details) operation with your `task_id` until `status` becomes `TransactionCreated`. + +### Timing and lifecycle + +Auto-sweep is poll-based rather than instant. A sweep is initiated shortly after its trigger condition is met, so a short delay between the deposit and the sweep transaction is normal. Tasks that cannot proceed do not stay pending indefinitely: a task that remains without gas or without a signature is automatically cancelled after a timeout, and the affected funds remain in the source address so that you can sweep them again later. + +For EVM-compatible chains (such as Ethereum and BNB Smart Chain), the same address is used across all EVM chains. As a result, when you list sweep-to addresses with [List sweep-to addresses](/v2/api-references/autosweep/list-sweep-to-addresses), only one address entry (shown under Ethereum) is returned for all EVM-compatible chains. Do not expect a separate entry for each EVM chain. \ No newline at end of file diff --git a/v2_cn/guides/custodial-wallets/get-started-asset-wallets.mdx b/v2_cn/guides/custodial-wallets/get-started-asset-wallets.mdx index 06bd84da..30ace52b 100644 --- a/v2_cn/guides/custodial-wallets/get-started-asset-wallets.mdx +++ b/v2_cn/guides/custodial-wallets/get-started-asset-wallets.mdx @@ -17,6 +17,7 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; 3. 向钱包存入代币并跟踪交易状态 4. 从钱包提取代币 5. 查询钱包余额 +6. 自动将资金归集到指定地址 本指南在所有代码示例中都使用[开发环境](/v2_cn/guides/overview/environments)。建议您先在开发环境中测试新功能，然后再将其部署到生产环境。 @@ -645,4 +646,28 @@ public class ListTokenBalancesExample { } } ``` - \ No newline at end of file + + +## 6. 自动归集资金（auto-sweep） + +自动归集（auto-sweep）会自动将充币地址中的代币归集到指定的归集目标地址，您无需手动从每个充币地址转出资金。要创建自动归集任务，请调用 [Create auto-sweep task](/v2/api-references/autosweep/create-auto-sweep-task)，并指定以下参数： + +- `wallet_id`：您创建的钱包 ID。 +- `token_id`：要归集的代币 ID。 +- `min_balance_threshold`：（可选）地址被归集所需的最低代币余额。余额低于此值的地址将被跳过，可用于过滤粉尘（dust）。系统不提供按地址设置的黑名单；请使用 `min_balance_threshold` 控制最低归集金额。 + + +归集会将代币从充币地址转出，因此需要链上原生代币支付 gas 费。请确保源充币地址中有足够的原生代币，或已配置 Fee Station 或自动加油（Auto Fueling）来提供 gas。仅达到充币阈值并不会完成归集：如果没有可用的 gas，归集交易将无法广播。当归集无法进行时，原因会显示在任务详情返回的 `failed_reasons` 数组中。 + + +### 获取归集交易 + +Create auto-sweep task 会立即返回 `task_id`。此时任务 `status` 为 `Submitted`，`transaction_ids` 数组为空。这是预期行为，并不表示失败。 + +当任务触发一个或多个归集交易后，其状态会变为 `TransactionCreated`，此时 `transaction_ids` 会被填充。要获取交易 ID，请使用 `task_id` 轮询 [Get auto-sweep task details](/v2/api-references/autosweep/get-auto-sweep-task-details)，直到 `status` 变为 `TransactionCreated`。 + +### 时间与生命周期 + +自动归集基于轮询机制，并非即时执行。归集会在满足触发条件后不久发起，因此充币与归集交易之间存在短暂延迟属于正常现象。无法继续的任务不会一直处于等待状态：长时间缺少 gas 或未完成签名的任务会在超时后自动取消，相关资金会保留在源地址中，您可以稍后重新归集。 + +对于 EVM 兼容链（如 Ethereum 和 BNB Smart Chain），所有 EVM 链共用同一个地址。因此，当您使用 [List sweep-to addresses](/v2/api-references/autosweep/list-sweep-to-addresses) 列出归集目标地址时，所有 EVM 兼容链只会返回一个地址条目（显示在 Ethereum 下）。请勿期望每条 EVM 链都有单独的地址条目。 \ No newline at end of file