预估归集手续费
读取确认余额及链上资源参数，预估所选钱包归集的能量、免费带宽、钱包 TRX 费用和 CatFee 租赁费用；不签名、不广播、不占用钱包。
POST /open/v1/sweeps/estimate
请求头
| 字段 | 类型 | 必填 | 说明 | 示例值 |
|---|---|---|---|---|
| X-App-Id | string | 是 | 平台appID，规范正int64，只传一次。 | 123456789012345001 |
| X-Timestamp | string | 是 | 当前秒级时间戳，服务器时间前后300秒内。 | 1893456000 |
| X-Sign | string | 是 | 本次HMAC-SHA256签名，64位小写十六进制；按签名规则生成。 | 按本次请求计算 |
| Authorization | string | 是 | 当前有效accessToken，格式为 Bearer 后加令牌。 | Bearer <ACCESS_TOKEN> |
| Content-Type | string | 是 | 单个UTF-8 JSON对象。 | application/json |
认证只使用上表请求头；不要发送 Idempotency-Key。示例凭据、ID和地址是演示值，签名必须按实际参数和当前时间重新计算。
请求参数
无路径参数，不接受任何Query（包括仅有问号的URL）。以下字段全部放JSON，额外字段返回400。
| 字段 | 类型 | 必填 | 说明 | 示例值 |
|---|---|---|---|---|
| wallet_ids | string[] | 是 | 1–20 个钱包，按输入顺序预估。 | [] |
| sweep_mode | string | 是 | all 全额归集；fixed 每钱包指定金额。 可选 all, fixed。 | "all" |
| requested_amount | string / null | 是 | all 必须明确为 null；fixed 必须为规范正 int64 字符串，最大 9223372036854775807，表示每个钱包的 USDT 最小单位金额。 | null |
json
{
"wallet_ids": [
"123456789012345678"
],
"sweep_mode": "all",
"requested_amount": null
}业务规则
每次1–20个规范正int64钱包ID，不允许重复；所有ID必须属于当前租户和网络，否则整体404。先用钱包预览固定确认清单，较大批次分组预估。
sweep_mode=all 时 requested_amount 必须明确为 null，金额取预估时已确认余额；fixed 时传每个钱包相同的正int64最小单位金额，不足时失败，不降额。未配置归集目标返回409；预估服务暂不可用返回 503；链上查询或 CatFee 报价失败按实际失败阶段返回整体错误或逐钱包失败。
单个钱包忙碌、向自身归集、余额不足或节点查询失败可返回HTTP200下的逐项failed；必须检查每一项的status和reason。
能量、带宽数量也使用整数字符串，但不是金额；标注SUN的字段才按六位精度换算为TRX。rental_cost 是预计平台租赁费用；estimated_fee、energy_fee 是预计钱包 TRX 支出；bandwidth_fee 始终为0。fee_limit 是完整能量准备额度对应的交易保护上限，不是扣款。
预估不创建、签名或广播交易，不锁定地址或余额，也不会保存费用报价。目标、余额、链上价格和钱包状态都可能在创建任务前变化；destination_version仅用于识别本次配置，不能把预估当作转账保证。创建归集仍须独立校验，本接口不需要request_id。
成功响应
HTTP 200，外层code=0、message为空字符串。
json
{
"code": 0,
"message": "",
"data": {
"network": "nile",
"destination": "TAt8Du9Xw2CmrTHRawGETwiEKpNuKDSjE8",
"destination_version": "1",
"sweep_mode": "all",
"requested_amount": null,
"estimated_at": "2030-01-01T00:00:00Z",
"items": [
{
"wallet_id": "123456789012345678",
"address": "TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM",
"amount": "100000000",
"status": "estimated",
"reason": "",
"estimate": {
"energy_required": "65000",
"energy_from_origin": "0",
"caller_energy_required": "65000",
"energy_available": "0",
"energy_from_resources": "0",
"energy_burned": "65000",
"energy_fee": "6500000",
"bandwidth_required": "350",
"staked_bandwidth_available": "0",
"free_bandwidth_available": "600",
"bandwidth_from_resources": "350",
"bandwidth_burned": "0",
"bandwidth_fee": "0",
"energy_price": "100",
"bandwidth_price": "1000",
"fee_limit": "7150000",
"estimated_fee": "6500000",
"balance_usdt": "100000000",
"balance_trx": "30000000",
"activation_required": "false",
"bandwidth_source": "free",
"rental_quantity": "0",
"rental_cost": "0",
"fee_source": "wallet_trx",
"prepared_energy": "71500",
"max_wallet_trx_fee": "7150000",
"free_bandwidth_limit": "600"
}
}
]
}
}| 字段 | 类型 | 必填 | 说明 | 示例值 |
|---|---|---|---|---|
| code | integer | 是 | 业务成功。 | 0 |
| message | string | 是 | 成功时为空字符串。 | "" |
| data | object | 是 | 当前统一归集目标、预估时间和逐钱包手续费预估结果。 | "见 JSON 示例" |
| data.network | string | 是 | 资产所属网络：main 或 nile。 | "nile" |
| data.destination | string | 是 | 本次预估使用的租户归集地址。 | "TAt8Du9Xw2CmrTHRawGETwiEKpNuKDSjE8" |
| data.destination_version | string | 是 | 本次预估使用的归集配置版本，不是钱包 ID。 | "1" |
| data.sweep_mode | string | 是 | 与请求一致。 可选 all, fixed。 | "all" |
| data.requested_amount | string / null | 是 | all 必须明确为 null；fixed 必须为规范正 int64 字符串，最大 9223372036854775807，表示每个钱包的 USDT 最小单位金额。 | null |
| data.estimated_at | string | 是 | 本次预估响应开始生成的时间。 | "2030-01-01T00:00:00Z" |
| data.items | object[] | 是 | 逐钱包结果，与请求顺序一致。 | [] |
| data.items[].wallet_id | string | 是 | 本项钱包 ID。 | "123456789012345678" |
| data.items[].address | string | 是 | 本项来源地址。 | "TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM" |
| data.items[].amount | string / null | 是 | 本次预估金额；无法取得金额时为 null；六位精度最小单位的整数字符串。 | null |
| data.items[].status | string | 是 | estimated 已取得费用预估；failed 本项不能预估。 可选 estimated, failed。 | "estimated" |
| data.items[].reason | string | 是 | 失败原因；预估成功为空字符串。 | "" |
| data.items[].estimate | object / null | 是 | "见 JSON 示例" | |
| data.items[].estimate.energy_required | string | 是 | 交易总能量需求，单位能量点。 以非负整数字符串传递。 | "65000" |
| data.items[].estimate.energy_from_origin | string | 是 | 合约部署方分担的能量点数。 以非负整数字符串传递。 | "0" |
| data.items[].estimate.caller_energy_required | string | 是 | 调用钱包需要承担的能量点数。 以非负整数字符串传递。 | "65000" |
| data.items[].estimate.energy_available | string | 是 | 钱包当前可用能量点数。 以非负整数字符串传递。 | "0" |
| data.items[].estimate.energy_from_resources | string | 是 | 实际使用已有资源抵扣的能量点数。 以非负整数字符串传递。 | "0" |
| data.items[].estimate.energy_burned | string | 是 | 当前钱包能量缺口，仅 wallet_trx 路径预计燃烧 TRX 支付。 以非负整数字符串传递。 | "65000" |
| data.items[].estimate.energy_fee | string | 是 | 预计钱包燃烧的 TRX 能量费用，resources/catfee 路径为0，单位SUN。 以非负整数字符串传递。 | "6500000" |
| data.items[].estimate.bandwidth_required | string | 是 | 预计交易所需带宽，单位字节。 以非负整数字符串传递。 | "350" |
| data.items[].estimate.staked_bandwidth_available | string | 是 | 当前可用的质押带宽，单位字节。 以非负整数字符串传递。 | "0" |
| data.items[].estimate.free_bandwidth_available | string | 是 | 当前可用的免费带宽，单位字节。 以非负整数字符串传递。 | "600" |
| data.items[].estimate.bandwidth_from_resources | string | 是 | 本次以已有资源支付的带宽字节数。 以非负整数字符串传递。 | "350" |
| data.items[].estimate.bandwidth_burned | string | 是 | 带宽不足时的交易所需带宽，任务等待恢复。 以非负整数字符串传递。 | "0" |
| data.items[].estimate.bandwidth_fee | string | 是 | 不以TRX支付带宽，值为0。 以非负整数字符串传递。 | "0" |
| data.items[].estimate.energy_price | string | 是 | 每能量点价格，SUN。 以非负整数字符串传递。 | "100" |
| data.items[].estimate.bandwidth_price | string | 是 | 每带宽字节价格，SUN。 以非负整数字符串传递。 | "1000" |
| data.items[].estimate.fee_limit | string | 是 | 完整能量准备额度折算的交易能量费用上限，SUN；不是预计扣款，也不是带宽费用上限。 以非负整数字符串传递。 | "7150000" |
| data.items[].estimate.estimated_fee | string | 是 | 预计钱包TRX支出，等于 energy_fee；平台租赁费另见 rental_cost。 以非负整数字符串传递。 | "6500000" |
| data.items[].estimate.balance_usdt | string | 是 | 预估时查询的已确认 USDT 余额，最小单位。 以非负整数字符串传递。 | "100000000" |
| data.items[].estimate.balance_trx | string | 是 | 已确认余额与当前节点余额中的较小值，排除未确认收入并反映未确认支出，SUN。 以非负整数字符串传递。 | "30000000" |
| data.items[].estimate.bandwidth_source | string | 是 | 本次带宽来源：free 免费额度、waiting 等待恢复或激活。 | "free" |
失败响应
错误JSON没有data；HTTP状态与code一致。
| HTTP | 情况 |
|---|---|
| 400 | 参数缺失、类型/格式无效或存在不支持的字段 |
| 401 | accessToken、签名或签名时间窗口无效 |
| 403 | 租户停用、删除或过期 |
| 404 | 钱包不存在或不属于当前租户/网络 |
| 409 | 归集地址未配置或无效 |
| 413 / 429 | 请求体过大 / 请求频率超限 |
| 500 / 503 / 504 | 内部依赖错误 / 资源或配置不可用 / 请求超时 |
json
{
"code": 401,
"message": "authentication required or expired",
"error_code": "TOKEN_INVALID_OR_EXPIRED",
"trace_id": "0123456789abcdef0123456789abcdef"
}通用错误说明Retry-After及重试处理；写请求不要因超时生成新的request_id。
业务错误示例
HTTP 400：钱包数量不在1至20范围。
json
{
"code": 400,
"message": "每次预估请选择1至20个钱包",
"error_code": "INVALID_ARGUMENT",
"trace_id": "0123456789abcdef0123456789abcdef"
}HTTP 404：至少一个钱包不存在或不属于当前租户及网络。
json
{
"code": 404,
"message": "钱包不存在或不属于当前租户及网络",
"error_code": "RESOURCE_NOT_FOUND",
"trace_id": "0123456789abcdef0123456789abcdef"
}HTTP 409：归集地址尚未配置。
json
{
"code": 409,
"message": "请先配置USDT归集地址",
"error_code": "BUSINESS_CONFLICT",
"trace_id": "0123456789abcdef0123456789abcdef"
}HTTP 503：预估服务暂不可用。
json
{
"code": 503,
"message": "归集预估服务配置不完整",
"error_code": "SERVICE_UNAVAILABLE",
"trace_id": "0123456789abcdef0123456789abcdef"
}CatFee 报价字段
| 字段 | 类型 | 说明 |
|---|---|---|
| data.items[].estimate.rental_quantity | string | 仅CatFee路径需要租赁；模拟能量加10%余量后扣除已有可用能量，最低65000。 |
| data.items[].estimate.rental_cost | string | CatFee 当前预计报价，SUN，由平台支付；预估不下单。 |
能量租期 1 小时，同一任务最多一笔租赁订单。免费带宽不足时等待恢复，期间不购买能量。未激活地址的激活费单独记录；查询失败时以返回的错误或逐项 reason 为准。
未激活地址返回 activation_required: "true"。能量和交易字节数仍来自真实模拟；当前可用资源为零，激活完成后重新核验。预估不会创建租赁订单。
费用选择顺序
免费带宽不足时任务暂停，每分钟复查，不购买能量、不签名、不广播。免费额度必须独立覆盖完整交易；不能用质押带宽补足。未激活钱包沿用CatFee同单激活，完成后检查免费额度。
能量准备额度为模拟总能量乘以110%并向上取整。先使用钱包已有能量，再判断钱包TRX能否覆盖整个剩余准备额度；足够则燃烧钱包TRX，不足则由CatFee租足能量缺口，不安排混合支付。租赁最低65000、租期1小时；一旦建立租赁记录不更换路径、不自动续租。
| 字段 | 类型 | 说明 |
|---|---|---|
| data.items[].estimate.fee_source | string | resources 自身能量；wallet_trx 自身TRX；catfee 平台租赁。 |
| data.items[].estimate.prepared_energy | string | 模拟能量增加10%的准备额度。 |
| data.items[].estimate.max_wallet_trx_fee | string | 当前准备额度的最大预计钱包能量支出，SUN；只有wallet_trx路径非零。 |
| data.items[].estimate.free_bandwidth_limit | string | 免费带宽上限，不能把质押带宽计入。 |
钱包手续费与CatFee租赁费用必须分别展示，不能把CatFee费用标为钱包支出。实际费用见归集记录；预估不会产生订单或扣款。TRON没有单独禁止带宽扣费的交易开关，因此系统签名、广播前检查，回执出现带宽费时记录异常并保持真实转账结果。
费用来源按包含余量的总能量准备额度选择；实际钱包费用同时考虑合约部署方当次分担。因此 fee_source 为 wallet_trx 但 estimated_fee 为 "0" 是可能的：表示钱包 TRX 可承担准备上限，而当前模拟由已有资源或合约承担消耗。不能把 max_wallet_trx_fee 当作预计实扣。
完整字段与状态
查看全部响应字段、嵌套对象及枚举 · 业务状态与处理 · 错误码排查。