diff --git a/docs.json b/docs.json index 1a46808e..ec53f022 100644 --- a/docs.json +++ b/docs.json @@ -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": [ @@ -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": [ @@ -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" ] }, @@ -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" ] }, { @@ -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": [ @@ -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": [ @@ -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" ] }, diff --git a/v2/cobo_waas2_openapi_spec/dev_openapi.yaml b/v2/cobo_waas2_openapi_spec/dev_openapi.yaml index 46128aeb..61de0a4f 100644 --- a/v2/cobo_waas2_openapi_spec/dev_openapi.yaml +++ b/v2/cobo_waas2_openapi_spec/dev_openapi.yaml @@ -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. - 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. + 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. - 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. + 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: @@ -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. + + + 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. + MPCWalletInfo: title: MPC Wallets allOf: @@ -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. + + + 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. + CreateMpcWalletParams: title: MPC Wallets allOf: @@ -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. + + + 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. + + + + 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. + UpdateMpcWalletParams: type: object title: MPC Wallets @@ -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. + + + 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. + + + + 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. + UpdateSmartContractWalletParams: type: object title: Smart Contract Wallets @@ -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 @@ -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. @@ -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: diff --git a/v2/guides/custodial-wallets/get-started-asset-wallets.mdx b/v2/guides/custodial-wallets/get-started-asset-wallets.mdx index f7e0a38d..e47c346a 100644 --- a/v2/guides/custodial-wallets/get-started-asset-wallets.mdx +++ b/v2/guides/custodial-wallets/get-started-asset-wallets.mdx @@ -703,24 +703,30 @@ public class ListTokenBalancesExample { ## 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: +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 on-demand sweep task for a specific token, 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. +- `min_balance_threshold`: (Optional) The minimum balance an address must hold to be eligible for this sweep request. Addresses holding less than this value are skipped. This threshold only filters which address balances are considered for the request; it does not override other execution checks such as available gas, required fees, reserved balances, or an existing pending transaction on the address. -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. +Meeting `min_balance_threshold` does not by itself guarantee a sweep transaction is created. A sweep moves tokens out of a deposit address, which requires native chain coin to pay for gas, so make sure that gas is available either in the source deposit address or through a configured Fee Station or Auto Fueling. Cobo also checks required fees, reserved balances, and whether the address already has a pending transaction before creating a sweep transaction. When any of these checks prevents a sweep, 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 Create auto-sweep task operation returns immediately with a `task_id`, accepting your request for asynchronous processing. This does not guarantee that a sweep transaction will ultimately be created for the request. -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`. +Poll the [Get auto-sweep task details](/v2/api-references/autosweep/get-auto-sweep-task-details) operation with your `task_id`, and check `status`, `transaction_ids`, and `failed_reasons` together rather than relying on any single field: + +- `status` of `Submitted` means the task is accepted and still awaiting its transaction-creation attempt. `TransactionCreated` means that attempt has completed. +- `transaction_ids` stays empty while the task is `Submitted`. An empty array under `TransactionCreated` means the attempt completed without creating a transaction, for example because no address balance remained eligible after gas, fee, reserve, or pending-transaction checks — not that a sweep was submitted and failed, and not that funds were already swept. +- `failed_reasons` explains why a sweep could not be created for one or more addresses. Treat these as diagnostic text and do not parse the exact wording. + +Once `transaction_ids` is populated, those sweep transactions still need to confirm on-chain. Poll [Get transaction information](/v2/api-references/transactions/get-transaction-information) with each transaction ID to track its final outcome, the same way you would for any other transaction created through the WaaS 2.0 API. ### 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. +Auto-sweep task processing is asynchronous rather than instant, so expect a short delay between submitting the Create auto-sweep task request and `status` reaching `TransactionCreated`. There is no fixed schedule that guarantees when, or whether, a given task leaves `Submitted`; rely on polling `status`, `transaction_ids`, and `failed_reasons` to determine the outcome. If a sweep cannot proceed, for example because gas is unavailable, the affected funds remain in the source address and you can submit a new sweep task for that address 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/guides/overview/changelog.mdx b/v2/guides/overview/changelog.mdx index edf53ba9..97316e7a 100644 --- a/v2/guides/overview/changelog.mdx +++ b/v2/guides/overview/changelog.mdx @@ -30,7 +30,7 @@ This version was released on July 9, 2026. - Deprecated `Raw_Message_Signature` in the [Sign message](/v2/api-references/transactions/sign-message) operation due to security concerns. It is no longer allowed and must not be used. It may be removed in a future version. - Clarified wallet name constraints in the [Create wallet](/v2/api-references/wallets/create-wallet) operation: the `name` field is required and cannot be empty; special characters such as `@` are not accepted and will return `400 Bad Request`. - Clarified that fee estimates from [Estimate transaction fee](/v2/api-references/transactions/estimate-transaction-fee) are point-in-time and short-lived. Re-estimate immediately before submitting a withdrawal to avoid rejection due to insufficient fees. -- Clarified async behavior of [Create auto sweep task](/v2/api-references/autosweep/create-auto-sweep-task): returned tasks have `status` set to `Submitted` with an empty `transaction_ids` array; poll [Get auto sweep task details](/v2/api-references/autosweep/get-auto-sweep-task-details) until `status` becomes `TransactionCreated`. Sweeps require native chain coin for gas from the deposit address, Fee Station, or Auto-Fuel. +- Clarified async behavior of [Create auto-sweep task](/v2/api-references/autosweep/create-auto-sweep-task): the task is accepted for asynchronous processing and returns with `status` set to `Submitted` and an empty `transaction_ids` array. Poll [Get auto-sweep task details](/v2/api-references/autosweep/get-auto-sweep-task-details) and check `status`, `transaction_ids`, and `failed_reasons` together; not every task is guaranteed to leave `Submitted`. Sweeps require native chain coin for gas from the deposit address, Fee Station, or Auto-Fuel. - Clarified that `transaction_hash` in [Get transaction information](/v2/api-references/transactions/get-transaction-information) and [List all transactions](/v2/api-references/transactions/list-all-transactions) responses may be `null` or absent before on-chain broadcast. - Clarified Solana transaction fee fields: `fee_used` covers on-chain network fees only and excludes ATA activation rent. `rent_amount` in fee estimate responses is reserved for future ATA activation rent and is currently not populated. @@ -829,4 +829,4 @@ This release includes support for [Custodial Wallets](https://manuals.cobo.com/e - [General wallet operations](/v2/api-references/wallets/list-supported-chains) - [MPC Wallets-specific operations](/v2/api-references/wallets--mpc-wallets/list-all-cobo-key-share-holders) - [Transactions operations](/v2/api-references/transactions/estimate-transaction-fee) -- [Webhook operations](/v2/api-references/developers--webhooks/list-webhook-endpoints) \ No newline at end of file +- [Webhook operations](/v2/api-references/developers--webhooks/list-webhook-endpoints) diff --git a/v2/guides/transactions/estimate-fees.mdx b/v2/guides/transactions/estimate-fees.mdx index dd4f6872..d88beeec 100644 --- a/v2/guides/transactions/estimate-fees.mdx +++ b/v2/guides/transactions/estimate-fees.mdx @@ -109,7 +109,6 @@ On Solana, you can use either the native model or the Legacy model. In the nativ | Base fee | A fixed fee charged per signature (default 5,000 lamports per signature). | | CU price | The price paid per CU (compute unit) to increase transaction priority, in lamports. | | CU limit | The maximum number of compute units your transaction is allowed to consume. A higher limit may increase priority but also increases the fee. | -| Rent | A one-time fee required to activate a Solana token sub-address (Associated Token Account, or ATA) before that token can be used. It is not included in the base fee or compute unit fee and is paid by the source address. | You can customize the following values: - CU price @@ -117,8 +116,6 @@ You can customize the following values: Refer to the response of the [Estimate transaction fee](/v2/api-references/transactions/estimate-transaction-fee) operation for details. -Activating a Solana token sub-address (Associated Token Account) incurs a one-time rent paid by the source address, separate from the network transaction fee. For details, see [Solana token account rent](/v2/guides/transactions/solana-token-account-rent). - Solana and Filecoin both support two fee models: their native model and the Legacy model. When calling transaction API operations, you can choose which model to use. However, for Replace-By-Fee (RBF) transactions, you must use the same fee model as the original transaction. ### Filecoin 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 4ce598a6..d4b96e44 100644 --- a/v2_cn/guides/custodial-wallets/get-started-asset-wallets.mdx +++ b/v2_cn/guides/custodial-wallets/get-started-asset-wallets.mdx @@ -708,24 +708,30 @@ public class ListTokenBalancesExample { ## 6. 自动归集资金（auto-sweep） -自动归集（auto-sweep）会自动将充币地址中的代币归集到指定的归集目标地址，您无需手动从每个充币地址转出资金。要创建自动归集任务，请调用 [Create auto-sweep task](/v2/api-references/autosweep/create-auto-sweep-task)，并指定以下参数： +自动归集（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` 控制最低归集金额。 +- `min_balance_threshold`：（可选）本次归集请求中，地址需达到的最低余额。余额低于此值的地址会被跳过。该阈值仅用于筛选本次请求中纳入考虑的地址余额，不会影响其他执行检查，例如可用 gas、所需手续费、保留余额，或该地址是否已有一笔待处理交易。 -归集会将代币从充币地址转出，因此需要链上原生代币支付 gas 费。请确保源充币地址中有足够的原生代币，或已配置 Fee Station 或自动加油（Auto Fueling）来提供 gas。仅达到充币阈值并不会完成归集：如果没有可用的 gas，归集交易将无法广播。当归集无法进行时，原因会显示在任务详情返回的 `failed_reasons` 数组中。 +满足 `min_balance_threshold` 并不能保证一定会创建归集交易。归集会将代币从充币地址转出，因此需要链上原生代币支付 gas 费，请确保源充币地址中有足够的原生代币，或已配置 Fee Station 或自动加油（Auto Fueling）来提供 gas。在创建归集交易之前，Cobo 还会检查所需手续费、保留余额，以及该地址是否已存在待处理交易。当以上任一检查未通过时，原因会显示在任务详情返回的 `failed_reasons` 数组中。 ### 获取归集交易 -Create auto-sweep task 会立即返回 `task_id`。此时任务 `status` 为 `Submitted`，`transaction_ids` 数组为空。这是预期行为，并不表示失败。 +Create auto-sweep task 会立即返回 `task_id`，表示请求已被接受并进入异步处理，但这并不保证最终一定会为该请求创建归集交易。 -当任务触发一个或多个归集交易后，其状态会变为 `TransactionCreated`，此时 `transaction_ids` 会被填充。要获取交易 ID，请使用 `task_id` 轮询 [Get auto-sweep task details](/v2/api-references/autosweep/get-auto-sweep-task-details)，直到 `status` 变为 `TransactionCreated`。 +请使用 `task_id` 轮询 [Get auto-sweep task details](/v2/api-references/autosweep/get-auto-sweep-task-details)，并同时查看 `status`、`transaction_ids` 和 `failed_reasons`，而不要只依赖其中一个字段： + +- `status` 为 `Submitted` 表示任务已被接受，仍在等待交易创建的处理结果；为 `TransactionCreated` 表示该处理已经完成。 +- 当任务处于 `Submitted` 时，`transaction_ids` 为空。当状态变为 `TransactionCreated` 后，`transaction_ids` 仍为空，则表示处理完成但未创建交易，例如在经过 gas、手续费、保留余额或待处理交易等检查后，没有余额符合归集条件——这并不代表已提交但归集失败，也不代表资金已被归集。 +- `failed_reasons` 说明了为何某个地址未能创建归集交易。请将其视为诊断性文本，不要解析具体措辞。 + +`transaction_ids` 被填充后，这些归集交易仍需在链上得到确认。请使用每个交易 ID 轮询 [Get transaction information](/v2/api-references/transactions/get-transaction-information)，跟踪其最终结果，方式与您跟踪 WaaS 2.0 API 创建的其他交易相同。 ### 时间与生命周期 -自动归集基于轮询机制，并非即时执行。归集会在满足触发条件后不久发起，因此充币与归集交易之间存在短暂延迟属于正常现象。无法继续的任务不会一直处于等待状态：长时间缺少 gas 或未完成签名的任务会在超时后自动取消，相关资金会保留在源地址中，您可以稍后重新归集。 +自动归集任务的处理是异步的，并非即时完成，因此从提交 Create auto-sweep task 请求到 `status` 变为 `TransactionCreated` 之间存在短暂延迟属于正常现象。系统并不保证某个任务会在固定时间内、或最终一定会脱离 `Submitted` 状态；请通过轮询 `status`、`transaction_ids` 和 `failed_reasons` 来判断结果。如果归集因故无法进行（例如 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 diff --git a/v2_cn/guides/overview/changelog.mdx b/v2_cn/guides/overview/changelog.mdx index a88e37bf..664bc255 100644 --- a/v2_cn/guides/overview/changelog.mdx +++ b/v2_cn/guides/overview/changelog.mdx @@ -30,7 +30,7 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; - 出于安全考虑，[签署消息](/v2/api-references/transactions/sign-message) 接口中的 `Raw_Message_Signature` 已废弃，不再允许使用，未来版本可能移除。 - 澄清 [创建钱包](/v2/api-references/wallets/create-wallet) 接口的钱包名称约束：`name` 为必填且不能为空；不支持 `@` 等特殊字符，否则返回 `400 Bad Request`。 - 澄清 [估算交易费用](/v2/api-references/transactions/estimate-transaction-fee) 接口返回的手续费预估为瞬时数据、时效较短。提交提现前应重新估算，避免因手续费不足导致交易被拒绝。 -- 澄清 [创建自动归集任务](/v2/api-references/autosweep/create-auto-sweep-task) 接口的异步行为：任务创建后 `status` 为 `Submitted` 且 `transaction_ids` 为空属正常；请轮询 [获取自动归集任务详情](/v2/api-references/autosweep/get-auto-sweep-task-details) 直至 `status` 变为 `TransactionCreated`。归集需要原生链币支付 gas，可从充币地址、Fee Station 或 Auto-Fuel 获取。 +- 澄清 [Create auto-sweep task](/v2/api-references/autosweep/create-auto-sweep-task) 接口的异步行为：请求会被异步接受处理，返回时 `status` 为 `Submitted` 且 `transaction_ids` 为空属正常。请轮询 [Get auto-sweep task details](/v2/api-references/autosweep/get-auto-sweep-task-details)，并结合 `status`、`transaction_ids` 与 `failed_reasons` 共同判断任务状态；并非每个任务都保证会脱离 `Submitted` 状态。归集需要原生链币支付 gas，可从充币地址、Fee Station 或 Auto-Fuel 获取。 - 澄清 [查询交易详情](/v2/api-references/transactions/get-transaction-information) 和 [查询交易列表](/v2/api-references/transactions/list-all-transactions) 响应中的 `transaction_hash` 仅在链上广播后才有值，广播前可能为 `null` 或缺失。 - 澄清 Solana 交易费用字段：`fee_used` 仅包含链上网络手续费，不含 ATA 激活租金；费用预估响应中的 `rent_amount` 为 ATA 激活租金预留字段，当前不返回。 @@ -818,4 +818,4 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; - [通用钱包操作](/v2/api-references/wallets/list-supported-chains) - [MPC 钱包特定操作](/v2/api-references/wallets--mpc-wallets/list-all-cobo-key-share-holders) - [交易操作](/v2/api-references/transactions/estimate-transaction-fee) -- [Webhook 操作](/v2/api-references/developers--webhooks/list-webhook-endpoints) \ No newline at end of file +- [Webhook 操作](/v2/api-references/developers--webhooks/list-webhook-endpoints) diff --git a/v2_cn/guides/transactions/estimate-fees.mdx b/v2_cn/guides/transactions/estimate-fees.mdx index 0060b391..1055d6db 100644 --- a/v2_cn/guides/transactions/estimate-fees.mdx +++ b/v2_cn/guides/transactions/estimate-fees.mdx @@ -111,7 +111,6 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; | Base Fee | 每个签名固定收取的费用（默认每个签名 5,000 Lamports）。 | | CU Price | 每个 CU（Compute Unit，计算单元）的费用，用于提升交易优先级。单位为 Lamports。 | | CU Limit | 交易允许消耗的最大CU数量。值越高优先级越高，但费用也越高。 | -| Rent | 激活 Solana 代币子地址（Associated Token Account，简称 ATA）所需的一次性费用，代币在使用前必须先激活该地址。该费用不包含在 Base Fee 或计算单元费用中，由交易来源地址支付。 | 你可以自定义以下参数的值： - CU Price @@ -119,8 +118,6 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; 请参考[估算交易费用](/v2/api-references/transactions/estimate-transaction-fee) 操作的响应结果获取详细字段信息。 -激活 Solana 代币子地址（Associated Token Account）会产生一次性租金，由交易来源地址支付，与网络交易手续费相互独立。详情请参阅 [Solana 代币账户租金](/v2_cn/guides/transactions/solana-token-account-rent)。 - Solana 和 Filecoin 均支持两种费用模型：其原生模型和 Legacy 模型。调用交易相关 API 时，你可以自行选择使用哪种模型。但对于 Replace-By-Fee（RBF）交易，必须使用与原始交易相同的费用模型。 ### Filecoin 链 diff --git a/v2_cn/guides/transactions/manage-transactions.mdx b/v2_cn/guides/transactions/manage-transactions.mdx index 2f9077bd..24f9f2f1 100644 --- a/v2_cn/guides/transactions/manage-transactions.mdx +++ b/v2_cn/guides/transactions/manage-transactions.mdx @@ -10,24 +10,6 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; 本指南概述了取消、加速和放弃交易的过程。掌握这些技术可以确保您的交易得到及时准确的处理。 -## 对交易列表分页 - -[List all transactions](/v2/api-references/transactions/list-all-transactions) 操作每次返回一页结果。分页由两个独立的游标参数 `before` 和 `after` 控制，它们分别向相反的方向移动分页窗口。`direction` 参数与分页无关，仅控制排序顺序。 - -- `after`：向前翻到下一页。传入上一个响应的 `pagination` 对象中返回的 `after` 值。 -- `before`：向后翻到上一页。传入上一个响应的 `pagination` 对象中返回的 `before` 值。 - -首次请求时，请勿包含 `before` 或 `after`。Cobo 会返回第一页，并附带一个 `pagination` 对象，其中包含用于翻页的 `before` 和 `after` 游标值。使用 `limit` 参数设置每页的记录数。 - -`direction` 参数是独立的排序控制，不会移动分页窗口。它接受 `ASC`（升序，默认值）或 `DESC`（降序），仅决定记录返回的顺序。向前和向后翻页始终由 `after` 和 `before` 控制。 - -### 分页操作步骤 - -1. 发送首次请求，不带 `before` 和 `after` 参数。响应会返回第一页以及包含 `before`、`after` 和 `total_count` 的 `pagination` 对象。 -2. 要向前翻到下一页，请发送另一个请求，并将 `after` 设置为上一个响应中的 `after` 值。 -3. 要向后翻到上一页，请发送另一个请求，并将 `before` 设置为上一个响应中的 `before` 值。 -4. 当响应返回的 `after` 值为空时，表示您已到达结果的末尾。当响应返回的 `before` 值为空时，表示您已到达结果的开头。 - ## 取消交易 取消交易是在交易仍处于待处理状态时停止它。 @@ -151,4 +133,4 @@ RBF 的两个最常见用例是加速和放弃交易。 | SafeTxMessage | 由 MPC 钱包发起的消息签名交易，用于授权智能合约钱包（Safe{Wallet}）的操作。 | | StellarChangeTrust | 在 Stellar 网络上建立 trustline 的交易。 | | NonceAccountSign | 使用 Solana nonce account 进行签名的交易，支持确定性且防重放的执行模式。 | -| FeePayerSign | 由 Solana 指定 fee payer 账户代付交易费用的交易，该账户与主签名账户相互独立。 | +| FeePayerSign | 由 Solana 指定 fee payer 账户代付交易费用的交易，该账户与主签名账户相互独立。 | \ No newline at end of file