Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 26 additions & 1 deletion v2/guides/custodial-wallets/get-started-asset-wallets.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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

<Note>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. </Note>

Expand Down Expand Up @@ -640,4 +641,28 @@ public class ListTokenBalancesExample {
}
}
```
</Accordion>
</Accordion>

## 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.

<Note>
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.
</Note>

### 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.

<Info>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.</Info>
27 changes: 26 additions & 1 deletion v2_cn/guides/custodial-wallets/get-started-asset-wallets.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx';
3. 向钱包存入代币并跟踪交易状态
4. 从钱包提取代币
5. 查询钱包余额
6. 自动将资金归集到指定地址

<Note>本指南在所有代码示例中都使用[开发环境](/v2_cn/guides/overview/environments)。建议您先在开发环境中测试新功能,然后再将其部署到生产环境。</Note>

Expand Down Expand Up @@ -645,4 +646,28 @@ public class ListTokenBalancesExample {
}
}
```
</Accordion>
</Accordion>

## 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` 控制最低归集金额。

<Note>
归集会将代币从充币地址转出,因此需要链上原生代币支付 gas 费。请确保源充币地址中有足够的原生代币,或已配置 Fee Station 或自动加油(Auto Fueling)来提供 gas。仅达到充币阈值并不会完成归集:如果没有可用的 gas,归集交易将无法广播。当归集无法进行时,原因会显示在任务详情返回的 `failed_reasons` 数组中。
</Note>

### 获取归集交易

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 或未完成签名的任务会在超时后自动取消,相关资金会保留在源地址中,您可以稍后重新归集。

<Info>对于 EVM 兼容链(如 Ethereum 和 BNB Smart Chain),所有 EVM 链共用同一个地址。因此,当您使用 [List sweep-to addresses](/v2/api-references/autosweep/list-sweep-to-addresses) 列出归集目标地址时,所有 EVM 兼容链只会返回一个地址条目(显示在 Ethereum 下)。请勿期望每条 EVM 链都有单独的地址条目。</Info>