diff --git a/snippets/error-codes-cn.mdx b/snippets/error-codes-cn.mdx index dbe15e49..c4281ba1 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 | 余额不足，无法执行请求的操作。 | Cobo 会按可用余额或可花费余额校验请求，而不只是看当前余额或总余额。待处理、锁定、冻结或处于合规筛查中的资金会减少可用余额，因此即使当前余额或总余额看起来充足，也仍可能触发此错误。请使用必填路径参数 `wallet_id` 和 `address` 调用 [List token balances by address](/v2/api-references/wallets/list-token-balances-by-address)，无需提供查询参数。
curl --location --request GET 'https://api.dev.cobo.com/v2/wallets/{wallet_id}/addresses/{address}/tokens' \\
  --header 'Biz-Api-Key: {YOUR_API_KEY}' \\
  --header 'Biz-Api-Nonce: {NONCE}' \\
  --header 'Biz-Api-Signature: {YOUR_API_SIGNATURE}'
响应为列表。请找到 `token_id` 与提币代币匹配的 `data[]` 条目，并读取其中的 `balance.available` 值（即 `data[].balance.available`）。如果提币代币也是费用代币（例如链的原生代币），请将 `balance.available` 与提币金额加上预期交易费用进行比较。如果提币代币与费用代币不同，请将提币代币的 `balance.available` 与提币金额进行比较，然后使用费用代币的 `token_id` 再次调用同一接口，并将其 `balance.available` 与预期费用单独进行比较。对于全托管钱包，此地址级检查可用于排查问题，但最终余额评估在钱包级别进行，并会计入任何可用授信额度，因此结果可能与单个地址的余额不同。在 Cobo Portal 中，您也可以打开源地址，检查待处理、锁定或冻结的资金是否导致可用余额低于当前余额。有关详情，请参见 [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`（余额不足）不同。请使用必填路径参数 `token_id`（例如 `ETH_USDT`）调用 [Get token information](/v2/api-references/wallets/get-token-information)，无需提供查询参数。
curl --location --request GET 'https://api.dev.cobo.com/v2/wallets/tokens/{token_id}' \\
  --header 'Biz-Api-Key: {YOUR_API_KEY}' \\
  --header 'Biz-Api-Nonce: {NONCE}' \\
  --header 'Biz-Api-Signature: {YOUR_API_SIGNATURE}'
读取响应字段 `dust_threshold`。该字段使用代币的显示单位，例如 BTC 而非聪。转账金额必须大于或等于 `dust_threshold`。如果金额低于 `dust_threshold`，请将金额提高到至少等于该值后再重试。对于 UTXO 链，您也可以先归集小额 UTXO 后再重试。背景说明请参见 [MPC 钱包的余额和交易金额](/v2_cn/guides/mpc-wallets/balance-amounts)。 | | 30011 | 提供的金额低于最低充币阈值。 | 增加充币金额以满足最低阈值。 | | 30013 | 余额不足以支付所需的交易费用。 | 确保源地址有足够的余额支付交易费用。 | | 30014 | 目标地址无效。 | 提供有效的目标地址。 | @@ -49,4 +49,3 @@ | 500 | 内部服务器错误。此错误可能由多个问题引起，包括 [Org Access Tokens](/v2/apps/org-access-tokens) 过期。 | 检查您的服务器配置设置，包括 Org Access Tokens 是否已过期，然后稍后重试。 | | 502 | 错误网关。 | 检查连接并稍后重试。 | | 503 | 服务不可用。 | 稍后重试。 | - diff --git a/snippets/error-codes.mdx b/snippets/error-codes.mdx index f69d8555..d29b1080 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. | Cobo validates the request against the available or spendable balance, not just the current or total balance. Pending, locked, frozen, or compliance-screened funds reduce the available balance, so the error can occur even when the current or total balance looks sufficient. Call [List token balances by address](/v2/api-references/wallets/list-token-balances-by-address) with the required `wallet_id` and `address` path parameters; no query parameter is required.
curl --location --request GET 'https://api.dev.cobo.com/v2/wallets/{wallet_id}/addresses/{address}/tokens' \\
  --header 'Biz-Api-Key: {YOUR_API_KEY}' \\
  --header 'Biz-Api-Nonce: {NONCE}' \\
  --header 'Biz-Api-Signature: {YOUR_API_SIGNATURE}'
The response is a list. Locate the `data[]` entry whose `token_id` matches the withdrawal token and read its `balance.available` value (`data[].balance.available`). If the withdrawal token is also the fee token, such as the chain's native token, compare `balance.available` with the withdrawal amount plus the expected transaction fee. If the withdrawal token and fee token differ, compare the withdrawal token's `balance.available` with the withdrawal amount, then call the same operation for the fee token's `token_id` and separately compare its `balance.available` with the expected fee. For Custodial Wallets, this address-level check is a useful diagnostic, but the final balance evaluation occurs at the wallet level and includes any available credit, so it can differ from a single address's balance. In Cobo Portal, you can also open the source address and check whether pending, locked, or frozen funds make the available balance lower than the current balance. 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. | This error means the transfer amount itself is too small to be processed and is distinct from error `12007` (insufficient balance). Call [Get token information](/v2/api-references/wallets/get-token-information) with the required `token_id` path parameter, such as `ETH_USDT`; no query parameter is required.
curl --location --request GET 'https://api.dev.cobo.com/v2/wallets/tokens/{token_id}' \\
  --header 'Biz-Api-Key: {YOUR_API_KEY}' \\
  --header 'Biz-Api-Nonce: {NONCE}' \\
  --header 'Biz-Api-Signature: {YOUR_API_SIGNATURE}'
Read the response field `dust_threshold`, which is expressed in the token's display unit, such as BTC rather than satoshis. The transfer amount must be greater than or equal to `dust_threshold`. If it is lower, increase it to at least `dust_threshold` before retrying. On UTXO chains, you can also consolidate small UTXOs before retrying. For background, see [Balances and transaction amounts for MPC Wallets](/v2/guides/mpc-wallets/balance-amounts). | | 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. | @@ -47,4 +47,3 @@ This article explains the common error codes and HTTP status codes you may encou | 500 | Internal Server Error. This error can be caused by several issues including expired [Org Access Tokens](/v2/apps/org-access-tokens). | Check your server configuration settings, including whether your Org Access Token has expired, and try again later. | | 502 | Bad Gateway. | Check the connectivity and try again later. | | 503 | Service Unavailable. | Try again later. | - diff --git a/v2/guides/mpc-wallets/balance-amounts.mdx b/v2/guides/mpc-wallets/balance-amounts.mdx index f077f1db..cb52a831 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,39 @@ 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 current balance and the available balance may update at different times after a deposit. The current balance can reflect the deposit first, while the available balance may still read 0 because the newly received UTXOs have not yet been processed into the spendable set. In other words, the funds may already appear in the address balance but are not yet ready to spend. Wait for the new UTXOs to finish processing before withdrawing the deposited funds. + +### Minimum transfer amount (dust threshold) + +Each token has a predefined minimum withdrawal amount (dust threshold) maintained by Cobo. 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, call [Get token information](/v2/api-references/wallets/get-token-information) to check the minimum withdrawal amount for the token, then increase the amount above that threshold. + +### 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. **Check the public balance fields first**: Call [List token balances by address](/v2/api-references/wallets/list-token-balances-by-address) for the source address and note `data.balance.total`, `data.balance.pending`, `data.balance.locked`, and `data.balance.available`. +2. **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. +3. **Portal cross-check**: In Cobo Portal, open the source address and compare the available balance with the current balance. If the available balance is lower, continue with the checks below to determine why. +4. **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). +5. **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). +6. **Dust**: If the amount is very small, it may instead be rejected with error `30010` (below the dust threshold) rather than `12007`. Retry with a larger amount. diff --git a/v2_cn/guides/mpc-wallets/balance-amounts.mdx b/v2_cn/guides/mpc-wallets/balance-amounts.mdx index cddf650f..22b7894d 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'; 多种类型余额和金额的定义 +## 余额可用性模型 + +[定义](#定义)中的值是 [List token balances by address](/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。所有选定的 UTXO 一起锁定，仅限于该笔交易，并在交易结算或失败时一起释放。 + ## Replace-By-Fee (RBF) 交易 如果您使用 RBF 交易加速交易，则 RBF 交易将用于计算待处理金额和锁定金额。 @@ -72,4 +97,39 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; - (提币金额 + 交易费用) > 可用余额：无法提交提币请求。 - (提币金额 + 交易费用) ≤ (当前余额 - 锁定金额)：您的提币请求将被立即处理。 -- (当前余额 - 锁定金额) < (提币金额 + 交易费用) ≤ 可用余额：您可以成功提交提币请求，但您的交易将被排队。 \ No newline at end of file +- (当前余额 - 锁定金额) < (提币金额 + 交易费用) ≤ 可用余额：您可以成功提交提币请求，但您的交易将被排队。 + +## 比特币与 UTXO 注意事项 + +### 充币后的可用余额 + +对于比特币和其他基于 UTXO 的链，充币后当前余额和可用余额的更新时间可能不同。当前余额可能会先反映这笔充币，而可用余额仍显示为 0，因为新收到的 UTXO 还没有完成处理并进入可花费集合。换句话说，这笔钱可能已经显示在地址余额中，但暂时还不能用于提币。请等待新的 UTXO 完成处理后，再提取已充入的资金。 + +### 最低转账金额（尘埃阈值） + +每个代币都有由 Cobo 预先维护的最小提币金额（尘埃阈值）。金额低于该代币尘埃阈值的提币将以错误 `30010`（金额低于尘埃阈值）被拒绝，而非错误 `12007`（余额不足）。要继续操作，请调用 [Get token information](/v2/api-references/wallets/get-token-information) 查询该代币的最小提币金额，并将金额提高到超过该阈值。 + +### UTXO 归集 + +消耗大量小额 UTXO 的提币会产生更大的交易和更高的网络费用。请在进行大额提币前归集小额 UTXO，以减小交易大小并降低费用。 + +## 支付余额 + +支付余额遵循与 MPC 钱包余额不同的模型。以下概念适用于支付账户： + +- **当前余额（Total balance）**：可用余额加上冻结金额。 +- **可用余额（Available balance）**：可以提取的余额。 +- **冻结金额（Frozen amount）**：为进行中的付款所保留的部分。 + +有关支付的完整详情，请参见 [支付文档](https://www.cobo.com/payments/cn/guides/overview)。 + +## 排查余额不足 + +当提币以错误 `12007`（余额不足）被拒绝时，请依次进行以下检查： + +1. **先检查公开余额字段**：调用 [List token balances by address](/v2/api-references/wallets/list-token-balances-by-address) 查询源地址余额，并记录 `data.balance.total`、`data.balance.pending`、`data.balance.locked` 和 `data.balance.available`。 +2. **真实的余额不足**：将提币金额加上交易费用与 `data.balance.available` 进行比较。如果超过可用余额，则该地址缺少可花费的资金。请充入更多资金或减少金额。 +3. **Portal 交叉检查**：在 Cobo Portal 中打开源地址，比较可用余额与当前余额。如果可用余额更低，请继续检查下面几项，确认原因。 +4. **锁定、待处理、筛查中或冻结的资金**：如果 `data.balance.available` 低于 `data.balance.total`，说明资金被预留在 `data.balance.pending` 中、被进行中的交易锁定在 `data.balance.locked` 中，或处于合规筛查中或被冻结。请等待其结算或释放。有关详情，请参见 [余额可用性模型](#余额可用性模型) 和 [资金锁定](#资金锁定)。 +5. **未建立索引的 UTXO**：在比特币和其他 UTXO 链上，如果充币后不久可用余额显示为 0，则新的 UTXO 可能仍在建立索引中。请稍后重新检查。有关详情，请参见 [比特币与 UTXO 注意事项](#比特币与-utxo-注意事项)。 +6. **尘埃**：如果金额非常小，它可能会以错误 `30010`（低于尘埃阈值）而非 `12007` 被拒绝。请改用更大的金额重试。