设置 USDT 归集地址
设置租户统一使用的 USDT 归集地址。仅允许合法的平台外 TRON 地址；不能使用平台钱包表内任何租户的地址，避免循环归集。无需向平台提供目标地址的私钥。实际变化会递增版本并取消尚未签名的旧目标归集任务；已签名交易保留原目标继续确认。
POST /open/v1/settings/addresses/collection
请求头
| 字段 | 类型 | 必填 | 说明 | 示例值 |
|---|---|---|---|---|
| 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。
| 字段 | 类型 | 必填 | 说明 | 示例值 |
|---|---|---|---|---|
| address | string | 是 | 完整 TRON Base58Check 地址，必须通过校验和，且不能是平台内任何租户的钱包地址。不接受空字符串、私钥或钱包 ID。 | "TAt8Du9Xw2CmrTHRawGETwiEKpNuKDSjE8" |
| request_id | string | 是 | 持久化幂等键，JSON 字符串，UTF-8 字节长度16–128，推荐ASCII UUID。创建钱包/归集、修改业务设置、通知重推必填。同租户同操作同键同参数返回原成功结果；同键异参409。只放JSON body，参与签名，不接受Idempotency-Key头。 | "123e4567-e89b-42d3-a456-426614174000" |
json
{
"address": "TAt8Du9Xw2CmrTHRawGETwiEKpNuKDSjE8",
"request_id": "collection-address-20300101-0001"
}业务规则
归集地址必须通过完整 TRON Base58Check 校验；不能用钱包 ID、十六进制地址或私钥代替。只能填写平台之外的地址。所有平台管理的钱包地址均禁止使用，包括当前账户和其他账户的收款地址，避免资金在平台钱包之间循环归集。错误响应不披露钱包所属租户。
当前接口不提供解绑，空字符串无效。实际目标发生变化才递增配置版本，并取消尚未签名的旧目标归集任务；已签名的交易仍按原目标确认。重复保存相同地址不会递增版本；同 request_id 重试返回第一次结果。
设置只保存目标，不创建链上转账。后续创建归集读取当时的配置，不接受临时转账目标。
幂等
JSON request_id 必填，16–128个UTF-8字节，推荐ASCII UUID；与业务参数一起参与签名。同租户同操作同键同参数返回原结果，同键不同参数返回409。超时重试保持原编号，读取最新配置请调用对应GET接口。
成功响应
HTTP 200，外层code=0、message为空字符串。
json
{
"code": 0,
"message": "",
"data": {
"collection_address": "TAt8Du9Xw2CmrTHRawGETwiEKpNuKDSjE8"
}
}| 字段 | 类型 | 必填 | 说明 | 示例值 |
|---|---|---|---|---|
| code | integer | 是 | 业务成功。 | 0 |
| message | string | 是 | 成功时为空字符串。 | "" |
| data | object | 是 | 本次保存的USDT归集地址；幂等重试返回原保存结果。 | "见 JSON 示例" |
| data.collection_address | string | 是 | 保存后的 USDT 归集地址。 | "TAt8Du9Xw2CmrTHRawGETwiEKpNuKDSjE8" |
失败响应
错误JSON没有data；HTTP状态与code一致。
| HTTP | 情况 |
|---|---|
| 400 | 参数格式无效时返回 INVALID_ARGUMENT；目标属于平台钱包时返回 COLLECTION_ADDRESS_MANAGED |
| 401 | accessToken、签名或签名时间窗口无效 |
| 403 | 租户停用、删除或过期 |
| 404 | 当前租户及网络的配置记录不存在 |
| 409 | request_id已被同操作不同业务参数使用，或业务状态冲突 |
| 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：归集地址格式或校验和错误。
json
{
"code": 400,
"message": "请输入有效的TRON地址",
"error_code": "INVALID_ARGUMENT",
"trace_id": "0123456789abcdef0123456789abcdef"
}HTTP 400 / COLLECTION_ADDRESS_MANAGED：地址属于平台管理的钱包。
json
{
"code": 400,
"error_code": "COLLECTION_ADDRESS_MANAGED",
"message": "归集地址不能使用平台内的钱包地址，请填写平台外的钱包地址",
"trace_id": "0123456789abcdef0123456789abcdef"
}请改用由你控制的平台外 TRON 地址，并使用修正后的正文重新签名；不要原样重试。此次拒绝不会修改归集地址、配置版本或旧任务，也不会保存成功的幂等结果；该次失败使用的 request_id 可以在修正后再次提交。已成功使用的编号仍遵守原幂等规则。
HTTP 404：当前账户未开通归集配置，请联系平台处理。
json
{
"code": 404,
"message": "record not found",
"error_code": "RESOURCE_NOT_FOUND",
"trace_id": "0123456789abcdef0123456789abcdef"
}HTTP 409：重复使用编号但更换了地址。
json
{
"code": 409,
"message": "conflict: idempotency key already used with another request",
"error_code": "IDEMPOTENCY_CONFLICT",
"trace_id": "0123456789abcdef0123456789abcdef"
}完整字段与状态
查看全部响应字段、嵌套对象及枚举 · 业务状态与处理 · 错误码排查。