diff --git a/snippets/error-codes-cn.mdx b/snippets/error-codes-cn.mdx index dbe15e49..5c2bb818 100644 --- a/snippets/error-codes-cn.mdx +++ b/snippets/error-codes-cn.mdx @@ -10,7 +10,7 @@ | 1003, 2003 | 请求中缺少一个或多个必填参数。 | 提供所有必填参数。 | | 1006, 2006 | 一个或多个参数格式无效或包含不支持的值。 | 以预期格式提供有效参数。 | | 12002 | Cobo 不支持指定的代币。 | 选择支持的代币。调用 [List supported tokens](/v2/api-references/wallets/list-supported-tokens) 接口获取完整的支持代币列表。 | -| 12007, 30012 | 余额不足，无法执行请求的操作。 | 确保源地址有足够的余额支付转账金额。 | +| 12007, 30012 | 余额不足，无法执行请求的操作。 | 确保源地址有足够的可用余额来支付提币金额加上交易费用。当资金处于待处理、锁定、合规筛查中或被冻结时，可用余额可能低于当前余额。有关详情，请参见 [MPC 钱包的余额和交易金额](/v2_cn/guides/mpc-wallets/balance-amounts)。如果金额非常小，它可能会以错误 30010（低于尘埃阈值）被拒绝。 | | 12009, 30001 | 重复的请求 ID。 | 使用唯一的请求 ID。 | | 12025 | 在 `included_utxos` 或 `excluded_utxos` 中指定的 UTXO 无效。 | 验证 `included_utxos` 或 `excluded_utxos` 中指定的 UTXO。 | | 2000 | 处理过程中发生内部错误。 | 请稍后重试。 | @@ -24,7 +24,7 @@ | 2051 | 当前套餐已过期。 | 续订您的套餐以继续使用服务。更多信息，请参见[账单和付款介绍](https://manuals.cobo.com/cn/portal/bills-and-payments/introduction)。 | | 30007 | 金额无效。该值不是有效数字或不符合所需格式或范围。 | 提供符合预期格式和范围的有效金额。 | | 30008 | 绝对金额无效。金额的绝对值太小、太大，或在需要非零值时为零。 | 确保金额的绝对值满足所需条件。 | -| 30010 | 提供的金额低于尘埃阈值。金额太小，无法处理或转账。 | 增加金额以超过尘埃阈值。 | +| 30010 | 提供的金额低于尘埃阈值。金额太小，无法处理或转账。 | 增加金额以超过该代币的尘埃阈值。尘埃阈值按代币配置。此错误表示金额太小无法转账，与错误 12007（余额不足）不同。 | | 30011 | 提供的金额低于最低充币阈值。 | 增加充币金额以满足最低阈值。 | | 30013 | 余额不足以支付所需的交易费用。 | 确保源地址有足够的余额支付交易费用。 | | 30014 | 目标地址无效。 | 提供有效的目标地址。 | diff --git a/snippets/error-codes.mdx b/snippets/error-codes.mdx index f69d8555..685d08a9 100644 --- a/snippets/error-codes.mdx +++ b/snippets/error-codes.mdx @@ -8,7 +8,7 @@ This article explains the common error codes and HTTP status codes you may encou | 1003, 2003 | One or more required parameters are missing in the request. | Provide all required parameters. | | 1006, 2006 | One or more parameters are in an invalid format or contain unsupported values. | Provide valid parameters in the expected format. | | 12002 | The specified token is not supported by Cobo. | Choose a supported token. Call the [List supported tokens](/v2/api-references/wallets/list-supported-tokens) operation to get the full list of supported tokens. | -| 12007, 30012 | Insufficient balance to perform the requested operation. | Ensure the source address has sufficient balance to cover the transferred amount. | +| 12007, 30012 | Insufficient balance to perform the requested operation. | Ensure the source address has enough available balance to cover the withdrawal amount plus the transaction fee. The available balance can be lower than the current balance when funds are pending, locked, held for compliance screening, or frozen. For details, see [Balances and transaction amounts for MPC Wallets](/v2/guides/mpc-wallets/balance-amounts). If the amount is very small, it may instead be rejected with error 30010 (below the dust threshold). | | 12009, 30001 | Duplicate request ID. | Use a unique request ID. | | 12025 | The UTXOs specified in `included_utxos` or `excluded_utxos` are invalid. | Verify the UTXOs specified in `included_utxos` or `excluded_utxos`. | | 2000 | Internal error occurred during processing. | Please try again later. | @@ -22,7 +22,7 @@ This article explains the common error codes and HTTP status codes you may encou | 2051 | The current pricing plan has expired. | Renew your pricing plan to continue using the service. For more information, see [Introduction to Bills & Payments](https://manuals.cobo.com/en/portal/bills-and-payments/introduction). | | 30007 | Invalid amount. The value is not a valid number or does not meet the required format or range. | Provide a valid amount that meets the expected format and range. | | 30008 | Invalid absolute amount. The absolute value of the amount is either too small, too large, or zero when a non-zero value is required. | Ensure the absolute value of the amount meets the required conditions. | -| 30010 | The provided amount is below the dust threshold. It is too small to be processed or transferred. | Increase the amount to exceed the dust threshold. | +| 30010 | The provided amount is below the dust threshold. It is too small to be processed or transferred. | Increase the amount to exceed the token's dust threshold. The dust threshold is configured per token. This error means the amount is too small to transfer and is distinct from error 12007 (insufficient balance). | | 30011 | The provided amount is below the minimum deposit threshold. | Increase the deposit amount to meet the minimum threshold. | | 30013 | Insufficient balance to cover the required transaction fee. | Ensure the source address has enough balance to cover transaction fees. | | 30014 | The destination address is invalid. | Provide a valid destination address. | diff --git a/v2/guides/mpc-wallets/balance-amounts.mdx b/v2/guides/mpc-wallets/balance-amounts.mdx index f077f1db..eaa902f7 100644 --- a/v2/guides/mpc-wallets/balance-amounts.mdx +++ b/v2/guides/mpc-wallets/balance-amounts.mdx @@ -24,6 +24,22 @@ This diagram illustrates the relationship between these values: Definitions of several types of balances and amounts +## Balance availability model + +The values in [Definitions](#definitions) are the public fields returned by the [List token balances by address](/v2/api-references/wallets/list-token-balances-by-address) operation. When a withdrawal is rejected for insufficient balance, the error response may report internal field names. The following table maps those internal field names to the public balance fields. + +| Error response field | Public balance field | Meaning | +| -------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------- | +| `using_amount` | `data.balance.pending` | Amount reserved by in-flight transactions (withdrawal amount plus transaction fee). | +| `locked_amount` | `data.balance.locked` | Value of funds locked for in-flight transactions; for UTXO chains, the combined value of selected UTXOs. | +| `spendable` | `data.balance.available` | Amount ready to be spent. | + +The available balance is derived as follows: + +`spendable = on-chain balance - using_amount - amount pending compliance screening - net frozen amount` + +The available balance can be lower than the current balance even when there is no obvious pending withdrawal, for example when funds are held for compliance screening or are frozen. + ## Update time These values are updated at different times during a deposit and withdrawal transaction. @@ -61,6 +77,15 @@ These values are updated at different times during a deposit and withdrawal tran - Locked amount: Equal to 0 - Available balance: Equal to the current balance +## Fund locking + +Funds are locked when you create and sign a withdrawal or other outgoing transaction. Locking happens in two stages: + +1. When the transaction is created and signed, the required amount moves from available to locked. This is why the available balance drops as soon as a withdrawal is submitted, before on-chain confirmation. For the corresponding balance changes, see the `PendingSignature` step in [Update time](#withdrawals). +2. Locked funds are released only when the transaction succeeds, or when a failure is confirmed on-chain. A confirmed failure means the network has finalized that the transaction will not be included (for example, the transaction is reverted or dropped), at which point the funds return to available. + +For UTXO chains such as Bitcoin, a single withdrawal can lock UTXOs across multiple addresses at once when coin selection spans more than one address. All selected UTXOs are locked together, scoped to that transaction, and released together when the transaction settles or fails. + ## Replace-By-Fee (RBF) transactions If you speed up a transaction with an RBF transaction, the RBF transaction will be used in calculating the pending amount and locked amount. @@ -73,4 +98,37 @@ The maximum amount you can withdraw is affected by the transaction fee, availabl - (Withdrawal amount + transaction fee) > Available balance: The withdrawal request cannot be submitted. - (Withdrawal amount + transaction fee) ≤ (Current balance - locked amount): Your withdrawal request will be handled immediately. -- (Current balance - locked amount) < (Withdrawal amount + transaction fee) ≤ Available balance: You can successfully submit your withdrawal request, but your transaction will be queued. \ No newline at end of file +- (Current balance - locked amount) < (Withdrawal amount + transaction fee) ≤ Available balance: You can successfully submit your withdrawal request, but your transaction will be queued. + +## Bitcoin and UTXO considerations + +### Available balance after a deposit + +For Bitcoin and other UTXO-based chains, the available balance is derived from indexed on-chain UTXO data. After a deposit, the current balance can already reflect the deposit while the available balance still reads 0 until the new UTXOs finish indexing. Wait for indexing to complete before withdrawing the deposited funds. + +### Minimum transfer amount (dust threshold) + +Each token has a configurable dust threshold. A withdrawal whose amount is below that token's dust threshold is rejected with error `30010` (amount below the dust threshold), not error `12007` (insufficient balance). To proceed, increase the amount above the threshold. The dust threshold is configured per token. + +### Consolidating UTXOs + +A withdrawal that spends many small UTXOs produces a larger transaction and higher network fees. Consolidate small UTXOs ahead of large withdrawals to reduce transaction size and fees. + +## Payment balances + +Payment balances follow a different model from MPC Wallet balances. The following concepts apply to payment accounts: + +- **Total balance**: The available balance plus the frozen amount. +- **Available balance**: The balance that can be withdrawn. +- **Frozen amount**: The portion held for in-flight payouts. + +For full details on payments, see the [Payments documentation](https://www.cobo.com/payments/en/guides/overview). + +## Troubleshooting insufficient balance + +When a withdrawal is rejected with error `12007` (insufficient balance), work through the following checks: + +1. **Genuine shortfall**: Compare the withdrawal amount plus the transaction fee against `data.balance.available`. If it exceeds the available balance, the address lacks spendable funds. Deposit more funds or reduce the amount. +2. **Locked, pending, screening, or frozen funds**: If `data.balance.available` is lower than `data.balance.total`, funds are reserved in `data.balance.pending`, held in `data.balance.locked` by in-flight transactions, or held for compliance screening or frozen. Wait for them to settle or be released. For details, see [Balance availability model](#balance-availability-model) and [Fund locking](#fund-locking). +3. **Un-indexed UTXOs**: On Bitcoin and other UTXO chains, if the available balance reads 0 shortly after a deposit, the new UTXOs may still be indexing. Wait and recheck. For details, see [Bitcoin and UTXO considerations](#bitcoin-and-utxo-considerations). +4. **Dust**: If the amount is very small, it may instead be rejected with error `30010` (below the dust threshold) rather than `12007`. Increase the amount above the token's dust threshold. \ No newline at end of file diff --git a/v2_cn/guides/mpc-wallets/balance-amounts.mdx b/v2_cn/guides/mpc-wallets/balance-amounts.mdx index cddf650f..ce806eaa 100644 --- a/v2_cn/guides/mpc-wallets/balance-amounts.mdx +++ b/v2_cn/guides/mpc-wallets/balance-amounts.mdx @@ -23,6 +23,22 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; 多种类型余额和金额的定义 +## 余额可用性模型 + +[定义](#定义)中的值是 [按地址列出代币余额](/v2/api-references/wallets/list-token-balances-by-address) 操作返回的公开字段。当提币因余额不足被拒绝时，错误响应可能会报告内部字段名。下表将这些内部字段名映射到公开余额字段。 + +| 错误响应字段 | 公开余额字段 | 含义 | +| ------------ | ------------------------ | ------------------------------------------------------------------- | +| `using_amount` | `data.balance.pending` | 进行中交易预留的金额（提币金额加上交易费用）。 | +| `locked_amount` | `data.balance.locked` | 为进行中交易锁定的资金价值；对于 UTXO 链，为所选 UTXO 的总值。 | +| `spendable` | `data.balance.available` | 准备花费的金额。 | + +可用余额的计算方式如下： + +`spendable = 链上余额 - using_amount - 待合规筛查的金额 - 净冻结金额` + +即使没有明显的待处理提币，可用余额也可能低于当前余额，例如当资金处于合规筛查中或被冻结时。 + ## 更新时间 这些值在充币和提币交易期间在不同时间更新。 @@ -60,6 +76,15 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; - 锁定金额：等于 0。 - 可用余额：等于当前余额。 +## 资金锁定 + +当您创建并签署提币或其他出金交易时，资金会被锁定。锁定分两个阶段进行： + +1. 当交易创建并签署时，所需金额从可用余额转移到锁定金额。这就是为什么在提币提交后、链上确认之前，可用余额会立即下降。有关相应的余额变化，请参见 [更新时间](#提币) 中的 `PendingSignature` 步骤。 +2. 锁定资金仅在交易成功，或链上确认失败时才会释放。已确认失败是指网络已最终确定该交易不会被打包（例如交易被回滚或丢弃），此时资金返还至可用余额。 + +对于比特币等 UTXO 链，当币种选择跨越多个地址时，单笔提币可以同时锁定多个地址上的 UTXO。所有选定的 UTXO 一起锁定，仅限于该笔交易，并在交易结算或失败时一起释放。 + ## Replace-By-Fee (RBF) 交易 如果您使用 RBF 交易加速交易，则 RBF 交易将用于计算待处理金额和锁定金额。 @@ -72,4 +97,37 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; - (提币金额 + 交易费用) > 可用余额：无法提交提币请求。 - (提币金额 + 交易费用) ≤ (当前余额 - 锁定金额)：您的提币请求将被立即处理。 -- (当前余额 - 锁定金额) < (提币金额 + 交易费用) ≤ 可用余额：您可以成功提交提币请求，但您的交易将被排队。 \ No newline at end of file +- (当前余额 - 锁定金额) < (提币金额 + 交易费用) ≤ 可用余额：您可以成功提交提币请求，但您的交易将被排队。 + +## 比特币与 UTXO 注意事项 + +### 充币后的可用余额 + +对于比特币和其他基于 UTXO 的链，可用余额来自已建立索引的链上 UTXO 数据。充币后，当前余额可能已经反映该笔充币，而可用余额仍显示为 0，直到新的 UTXO 完成索引。请等待索引完成后再提取已充入的资金。 + +### 最低转账金额（尘埃阈值） + +每个代币都有可配置的尘埃阈值。金额低于该代币尘埃阈值的提币将以错误 `30010`（金额低于尘埃阈值）被拒绝，而非错误 `12007`（余额不足）。要继续操作，请将金额增加到超过该阈值。尘埃阈值按代币配置。 + +### UTXO 归集 + +消耗大量小额 UTXO 的提币会产生更大的交易和更高的网络费用。请在进行大额提币前归集小额 UTXO，以减小交易大小并降低费用。 + +## 支付余额 + +支付余额遵循与 MPC 钱包余额不同的模型。以下概念适用于支付账户： + +- **当前余额（Total balance）**：可用余额加上冻结金额。 +- **可用余额（Available balance）**：可以提取的余额。 +- **冻结金额（Frozen amount）**：为进行中的付款所保留的部分。 + +有关支付的完整详情，请参见 [支付文档](https://www.cobo.com/payments/cn/guides/overview)。 + +## 排查余额不足 + +当提币以错误 `12007`（余额不足）被拒绝时，请依次进行以下检查： + +1. **真实的余额不足**：将提币金额加上交易费用与 `data.balance.available` 进行比较。如果超过可用余额，则该地址缺少可花费的资金。请充入更多资金或减少金额。 +2. **锁定、待处理、筛查中或冻结的资金**：如果 `data.balance.available` 低于 `data.balance.total`，说明资金被预留在 `data.balance.pending` 中、被进行中的交易锁定在 `data.balance.locked` 中，或处于合规筛查中或被冻结。请等待其结算或释放。有关详情，请参见 [余额可用性模型](#余额可用性模型) 和 [资金锁定](#资金锁定)。 +3. **未建立索引的 UTXO**：在比特币和其他 UTXO 链上，如果充币后不久可用余额显示为 0，则新的 UTXO 可能仍在建立索引中。请稍后重新检查。有关详情，请参见 [比特币与 UTXO 注意事项](#比特币与-utxo-注意事项)。 +4. **尘埃**：如果金额非常小，它可能会以错误 `30010`（低于尘埃阈值）而非 `12007` 被拒绝。请将金额增加到超过该代币的尘埃阈值。 \ No newline at end of file