Skip to content

docs: 澄清自动归集任务与钱包配置语义 #384

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rcsh1 wants to merge 8 commits into
base: master
Choose a base branch
from
Open

docs: 澄清自动归集任务与钱包配置语义 #384

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
fdfc5dc
Recover doc-writing-core run_8d40a6d96746 edits from trace log
rcsh1 Jun 19, 2026
33a1710
docs: address review feedback
rcsh1 Jun 24, 2026
360989a
docs: refine transaction routing wording
rcsh1 Jun 25, 2026
a7e5658
docs: address remaining review comments on transaction lifecycle PR
rcsh1 Jul 2, 2026
4e80c33
docs: remove redundant Note on force_internal/force_external mutual e…
rcsh1 Jul 2, 2026
f126b4b
docs: remove code examples from transfer-routing pages
rcsh1 Jul 2, 2026
70f19ef
docs: 澄清自动归集任务与钱包配置语义
rcsh1 Jul 21, 2026
7307c32
docs: address review feedback
rcsh1 Jul 24, 2026
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
8 changes: 1 addition & 7 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,6 @@
"v2/guides/transactions/sources-and-destinations",
"v2/guides/transactions/transfer-routing",
"v2/guides/transactions/estimate-fees",
"v2/guides/transactions/solana-token-account-rent",
{
"group": "Transaction statuses",
"pages": [
Expand All @@ -66,7 +65,6 @@
},
"v2/guides/transactions/manage-transactions",
"v2/guides/transactions/rbf-transaction-lifecycle",
"v2/guides/transactions/validate-addresses",
{
"group": "Smart contract call samples",
"pages": [
Expand Down Expand Up @@ -119,7 +117,6 @@
]
},
"v2/guides/mpc-wallets/server-co-signer/key-share-verify",
"v2/guides/mpc-wallets/server-co-signer/troubleshooting",
"v2/guides/mpc-wallets/server-co-signer/appendix"
]
},
Expand Down Expand Up @@ -348,7 +345,7 @@
"v2/api-references/autosweep/create-auto-sweep-task",
"v2/api-references/autosweep/list-auto-sweep-tasks",
"v2/api-references/autosweep/get-auto-sweep-task-details",
"v2/api-references/autosweep/cancel-auto-sweep-task"
"v2/api-references/autosweep/cancel-auto-sweep-task-by-id"
]
},
{
Expand Down Expand Up @@ -867,7 +864,6 @@
"v2_cn/guides/transactions/sources-and-destinations",
"v2_cn/guides/transactions/transfer-routing",
"v2_cn/guides/transactions/estimate-fees",
"v2_cn/guides/transactions/solana-token-account-rent",
{
"group": "交易状态",
"pages": [
Expand All @@ -878,7 +874,6 @@
},
"v2_cn/guides/transactions/manage-transactions",
"v2_cn/guides/transactions/rbf-transaction-lifecycle",
"v2_cn/guides/transactions/validate-addresses",
{
"group": "智能合约调用示例",
"pages": [
Expand Down Expand Up @@ -931,7 +926,6 @@
]
},
"v2_cn/guides/mpc-wallets/server-co-signer/key-share-verify",
"v2_cn/guides/mpc-wallets/server-co-signer/troubleshooting",
"v2_cn/guides/mpc-wallets/server-co-signer/appendix"
]
},
Expand Down
87 changes: 73 additions & 14 deletions v2/cobo_waas2_openapi_spec/dev_openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6150,11 +6150,11 @@ paths:
operationId: create_auto_sweep_task
summary: Create auto-sweep task
description: |
This operation creates an auto-sweep task for the specified wallet and token. The task triggers transactions to sweep the full balance of the specified token to the configured sweep-to address.
This operation creates an on-demand sweep task for the specified token. Unlike automatic sweeping, this task does not wait for the wallet's automatic policy trigger conditions. It is accepted for processing immediately.

<Note>A sweep requires native chain coin to pay for gas. The gas must be available either in the source (deposit) address, or supplied by a configured Fee Station or Auto-Fuel. Reaching the deposit threshold alone does not trigger a sweep. If no gas is available, the sweep is blocked (for example, with an insufficient-balance error) or the Fee Station quota check fails. When a sweep is blocked, the reason is reported in the `failed_reasons` array of the auto-sweep task.</Note>
During execution, Cobo evaluates the request's `min_balance_threshold` and other eligibility constraints for each address, including available gas, reserved balances and fees, and any pending transaction on the address. As a result, execution may create no transaction if no address is eligible.

<Info>This operation is asynchronous. When the task is created, it is returned with `status` set to `Submitted` and an empty `transaction_ids` array; this is expected and does not indicate a failure. The `transaction_ids` array is populated only after `status` becomes `TransactionCreated`. To retrieve the transaction IDs, poll [Get auto-sweep task details](https://www.cobo.com/developers/v2/api-references/autosweep/get-auto-sweep-task-details) using the returned `task_id` until the status changes.</Info>
A `Submitted` status means the task has been accepted for asynchronous processing. It does not guarantee that a sweep transaction will be created. Poll [Get auto-sweep task details](https://www.cobo.com/developers/v2/api-references/autosweep/get-auto-sweep-task-details) and check `status`, `transaction_ids`, and `failed_reasons` together to determine the task's current state. Once `transaction_ids` contains an ID, call [Get transaction information](https://www.cobo.com/developers/v2/api-references/transactions/get-transaction-information) to determine that transaction's outcome.
security:
- CoboAuth: []
- OAuth2:
Expand Down Expand Up @@ -6989,7 +6989,20 @@ components:
example: f47ac10b-58cc-4372-a567-0e02b2c3d479
enable_auto_sweep:
type: boolean
description: Enable the auto sweep feature for the wallet
description: |
Whether the auto-sweep capability has been enabled for this wallet.
- `true`: Auto-sweep has been enabled for this wallet.
- `false`: Auto-sweep has not been enabled for this wallet.

This field reports whether the capability itself has been enabled. It does not indicate whether automatic sweep triggers are currently paused. To pause or resume automatic triggers in Cobo Portal:
- For a Custodial Web3 Wallet, go to **Wallets > Custodial Wallets > Web3 Wallets**, select the wallet, click **Auto-Sweep Settings**, and then click **Pause Auto-Sweep** or **Resume Auto-Sweep**.
- For an Organization-Controlled MPC Wallet, go to **Wallets > MPC Wallets > Organization-Controlled Wallets**, select the vault and wallet, click **Auto-Sweep Settings**, and then click **Pause Auto-Sweep** or **Resume Auto-Sweep**.

Pausing or resuming automatic triggers does not change this field's value.

<Note>
Once enabled, deposit addresses in this wallet cannot initiate public token transfers or contract calls by default. To restore deposit-address transactions in Cobo Portal, follow the applicable wallet path above, click **Auto-Sweep Settings > Sweep Security**, turn on **Deposit Address Transactions**, and click **Confirm**. This setting applies to the wallet's deposit addresses.
</Note>
MPCWalletInfo:
title: MPC Wallets
allOf:
Expand Down Expand Up @@ -7228,7 +7241,14 @@ components:
$ref: '#/components/schemas/WalletSubtype'
enable_auto_sweep:
type: boolean
description: Enable the auto-sweep feature for the wallet. This parameter only applies to MPC Wallets and Custodial Wallets (Web3 Wallets).
description: |
Whether to enable the auto-sweep capability for this wallet.
- `true`: Enables auto-sweep for the wallet.
- `false`: Does not enable auto-sweep for the wallet.

<Warning>
Enabling auto-sweep is irreversible. After enablement, deposit addresses in this wallet can no longer initiate public token transfers or contract calls by default. To restore deposit-address transactions in Cobo Portal, go to **Wallets > Custodial Wallets > Web3 Wallets**, select the wallet, click **Auto-Sweep Settings > Sweep Security**, turn on **Deposit Address Transactions**, and click **Confirm**. This setting applies to the wallet's deposit addresses.
</Warning>
CreateMpcWalletParams:
title: MPC Wallets
allOf:
Expand Down Expand Up @@ -7373,7 +7393,18 @@ components:
description: The wallet name.
enable_auto_sweep:
type: boolean
description: Enable the auto sweep feature for the wallet
description: |
Whether to enable the auto-sweep capability for this wallet.
- `true`: Enables auto-sweep for the wallet.
- `false`: Does not disable auto-sweep for a wallet that already has it enabled. This field is a one-way enable control.

<Note>
To stop future automatic sweep triggers in Cobo Portal, go to **Wallets > Custodial Wallets > Web3 Wallets**, select the wallet, click **Auto-Sweep Settings**, and then click **Pause Auto-Sweep**. Use **Resume Auto-Sweep** to resume automatic triggers. Pausing automatic triggers does not undo enablement. This field continues to report `true` for a wallet that was enabled and later paused.
</Note>

<Warning>
Enabling auto-sweep is irreversible. After enablement, deposit addresses in this wallet can no longer initiate public token transfers or contract calls by default. To restore deposit-address transactions in Cobo Portal, go to **Wallets > Custodial Wallets > Web3 Wallets**, select the wallet, click **Auto-Sweep Settings > Sweep Security**, turn on **Deposit Address Transactions**, and click **Confirm**. This setting applies to the wallet's deposit addresses.
</Warning>
UpdateMpcWalletParams:
type: object
title: MPC Wallets
Expand All @@ -7389,7 +7420,18 @@ components:
description: The wallet name.
enable_auto_sweep:
type: boolean
description: Enable the auto sweep feature for the wallet
description: |
Whether to enable the auto-sweep capability for this wallet.
- `true`: Enables auto-sweep for the wallet.
- `false`: Does not disable auto-sweep for a wallet that already has it enabled. This field is a one-way enable control.

<Note>
To stop future automatic sweep triggers in Cobo Portal, go to **Wallets > MPC Wallets > Organization-Controlled Wallets**, select the vault and wallet, click **Auto-Sweep Settings**, and then click **Pause Auto-Sweep**. Use **Resume Auto-Sweep** to resume automatic triggers. Pausing automatic triggers does not undo enablement. This field continues to report `true` for a wallet that was enabled and later paused.
</Note>

<Warning>
Enabling auto-sweep is irreversible. After enablement, deposit addresses in this wallet can no longer initiate public token transfers or contract calls by default. To restore deposit-address transactions in Cobo Portal, go to **Wallets > MPC Wallets > Organization-Controlled Wallets**, select the vault and wallet, click **Auto-Sweep Settings > Sweep Security**, turn on **Deposit Address Transactions**, and click **Confirm**. This setting applies to the wallet's deposit addresses.
</Warning>
UpdateSmartContractWalletParams:
type: object
title: Smart Contract Wallets
Expand Down Expand Up @@ -21454,13 +21496,24 @@ components:
type: string
example: 0011039d-27fb-49ba-b172-6e0aa80e37ec
description: |
IDs of the transactions triggered by the task. This array is empty while the task `status` is `Submitted`, and is populated only after the status becomes `TransactionCreated`. Poll [Get auto-sweep task details](https://www.cobo.com/developers/v2/api-references/autosweep/get-auto-sweep-task-details) until the transaction IDs are available.
The IDs of the sweep transactions created for this task.

An empty array means that no sweep transaction has been created for this task yet. It does not mean that submission failed or that funds have already been swept. Check this field together with `failed_reasons` and `status` to determine the task's current state. Poll [Get auto-sweep task details](https://www.cobo.com/developers/v2/api-references/autosweep/get-auto-sweep-task-details) to retrieve the latest task information.
failed_reasons:
type: array
items:
type: string
example: exist pending transaction
description: Reasons why the task creation failed.
example: Insufficient balance to cover network fees.
description: |
A list of human-readable diagnostic messages explaining why this task did not create a sweep transaction for one or more addresses. Each message is free-text, and its exact wording may change. Do not parse it for exact text, transaction IDs, or exception strings. Instead, classify messages using the following general categories:
- Insufficient balance to cover the sweep after transaction fees are reserved.
- Insufficient gas balance to fund the sweep transaction.
- The transaction fee would exceed a configured fee cap.
- Another transaction from the same address is already pending.
- The address balance does not meet the configured minimum-balance threshold.
- Chain-specific fee-handling requirements were not met, for example, on TRON.
- Fee Station declined to fund the transaction.
- The sweep transaction could not be created.
created_timestamp:
type: integer
format: int64
Expand All @@ -21478,9 +21531,11 @@ components:
- TransactionCreated
example: Submitted
description: |
Auto-sweep task status:
- `Submitted`: The auto-sweep task has been submitted.
- `TransactionCreated`: The auto-sweep task triggered one or more token sweeping transactions.
The status of the auto-sweep task. Possible values:
- `Submitted`: The task has been accepted and is still awaiting transaction creation. Check `failed_reasons` and `transaction_ids` for the latest task details.
- `TransactionCreated`: Task processing created, or completed its attempt to create, a sweep transaction. Check `transaction_ids` for the resulting transaction IDs and `failed_reasons` for any diagnostic messages.

Task-level failure is not represented by a dedicated `Failed` status. If a task cannot proceed, the reason is recorded in `failed_reasons`. Once `transaction_ids` contains an ID, retrieve that transaction separately to determine its own success or failure. This status does not reflect downstream transaction outcomes.
CreateAutoSweepTask:
type: object
description: Wallet and token information required to create an auto-sweep task.
Expand All @@ -21499,7 +21554,11 @@ components:
min_balance_threshold:
type: string
description: |
The minimum token balance threshold for auto sweep. If the token balance of an address is less than this threshold, the address will not be swept.
The per-request minimum balance threshold used to filter addresses when this task executes. During execution, any address whose balance is below this threshold is skipped for this task.

This field only filters which addresses are considered for this task. It does not override other execution checks such as gas requirements, reserved balances, transaction fees, or an existing pending transaction on the same address. If you omit this field, address selection still passes through those other checks.

It applies only to this manual task.
example: '0.01'
parameters:
sortByParam:
Expand Down
Loading