归集开放平台
GET/open/v1/deposits/{id}

到账详情 ​

查询一笔已确认USDT到账，返回与到账通知解密正文相同的业务对象。

本页的 ID、地址、交易哈希、时间及金额均为文档示例；请使用自己账户的数据。金额以六位精度的最小单位字符串表示，例如 "100000000" 代表 100 USDT，"1000000" SUN 代表 1 TRX。

请求地址 ​

http
GET /open/v1/deposits/{id}

鉴权请求头 ​

先获取 access token，再按签名规则为实际请求生成签名。四个鉴权头必须且只能提供一次，内容和签名须与实际发送的请求一致。

字段类型必填说明示例值
X-App-Idstring是规范正整数 appID，必须且只能提供一次。1234567890
X-Timestampstring是当前 Unix 秒级时间戳，规范十进制字符串；有效时间窗口见签名指南。1788825600
X-Signstring是本次请求的 64 位小写十六进制 HMAC-SHA256 签名，必须且只能提供一次。<本次请求签名>
Authorizationstring是必须且只能提供一次，使用当前有效 token。Bearer <ACCESS_TOKEN>

路径参数 ​

字段类型必填说明示例值
idstring是到账记录 ID，同一交易日志即使撤销后重新确认也保持不变。
http
GET /open/v1/deposits/123456789012345690

不接受 network 查询参数，GET 请求体必须为空。记录必须属于当前账户和当前网络；不存在、其他账户或其他网络的记录统一返回 404。路径中的 ID 决定查询对象，query 中的 id 不会覆盖它。

成功响应 ​

HTTP 200。

字段类型必填说明示例值
codeinteger是业务请求成功时固定为 0。0
messagestring是成功时固定为空字符串。""
dataobject是完整到账记录对象。见下方 JSON 示例
data.networkstring是资产所属网络：main（主网）或 nile（测试网络）。"nile"

统一到账对象 ​

到账详情的 data、列表中的每个 items 元素以及通知解密正文使用同一结构；同一 id、revision 的内容一致，查询返回当前版本，历史通知保留对应事件版本。以下 24 个字段全部必返；confirmations 与 block_hash 允许为 null，具体条件见字段表。

字段类型必返说明
idstring是到账记录 ID，同一交易日志即使撤销后重新确认也保持不变。
event_idstring是本次状态事件 ID；重试不变，撤销/重新确认产生新事件 ID。按此字段去重。
event_typestring是到账状态事件类型。 deposit.confirmed 表示到账认可；deposit.reverted 表示到账撤销。
statusstring是到账状态：confirmed 表示达到租户确认门槛；reverted 表示因链重组撤销。不是推送状态。
wallet_idstring是收款钱包 ID。
custom_idstring是钱包的租户自定义ID，同一租户内唯一，取到账入库时快照。
chainstring是所属区块链。 固定值："TRON"。
networkstring是资产所属网络：main（主网）或 nile（测试网络）。
assetstring是资产名称；测试网对应测试代币。资产身份以network+contract为准。 固定值："USDT"。
token_standardstring是代币协议。 固定值："TRC20"。
decimalsinteger是金额精度，展示金额=amount÷10^decimals。使用整数或十进制定点计算。 固定值：6。
addressstring是到账收款地址。
sourcestring是链上 Transfer 事件的来源地址。
contractstring是此笔Transfer的实际代币合约。结合network识别资产；Nile为测试代币，Main为Tether发行的USDT。
amountstring是该条到账记录的 USDT 金额，是否有效由 status 决定；最小单位的整数字符串，六位精度，禁止用浮点数处理。
txidstring是该条到账对应的交易哈希。
log_indexinteger是交易收据内的日志索引；与网络、交易哈希一起标识链上事件。
block_numberstring是到账状态对应的区块高度，低确认模式下不代表已固化。
block_timestring是链上区块时间；UTC RFC3339，固定6位小数秒，以Z结尾。不是通知发送时间。
created_atstring是平台确认并保存到账的时间；UTC RFC3339，固定6位小数秒，以Z结尾。确认或同步存在延迟时，可能晚于 block_time。
revisioninteger是同一到账状态版本，从1递增；只应用更高版本，旧版本通知应答成功但不再入账。
confirmation_typestring是该笔到账采用的确认规则：block_1、block_3、block_6、block_12、solidified。仅平台开通的确认规则。
confirmationsinteger / null是通过最新区块确认时的确认数；按固化结果确认时为 null。
block_hashstring / null是本次状态对应的区块哈希；既有历史记录未保存时为null。
json
{
  "code": 0,
  "message": "",
  "data": {
    "id": "123456789012345690",
    "event_id": "123456789012345690",
    "event_type": "deposit.confirmed",
    "status": "confirmed",
    "wallet_id": "123456789012345678",
    "custom_id": "customer-1001",
    "chain": "TRON",
    "network": "nile",
    "asset": "USDT",
    "token_standard": "TRC20",
    "decimals": 6,
    "address": "TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM",
    "source": "TWkz4y25cWK517vSdMP1N4EWHySqwQ6dMb",
    "contract": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf",
    "amount": "100000000",
    "txid": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "log_index": 0,
    "block_number": "34567890",
    "block_time": "2026-09-08T00:00:00.000000Z",
    "created_at": "2026-09-08T00:00:00.000000Z",
    "revision": 1,
    "confirmation_type": "solidified",
    "confirmations": null,
    "block_hash": null
  }
}

id 标识到账记录；txid 标识交易；log_index 标识该交易中的日志位置。不要仅凭交易哈希假定只存在一条到账流水。address 是收款地址，source 是转出地址，contract 是此条到账的 TRC20 合约地址。

到账金额、区块号和 ID 都是字符串，log_index 是整数。status 为 confirmed（达到确认门槛）或 reverted（因链重组撤销）。查询推送状态请用同一个event_id调用通知详情；投递失败不撤销到账。

详情读取当前保存的记录，不需要 request_id；不要发送 Idempotency-Key 请求头。

典型错误 ​

错误响应不包含 data。鉴权、租户状态、限流、超时等通用处理见通用错误说明。

HTTP 400：路径 ID 不是有效正整数 ​

json
{
  "code": 400,
  "message": "invalid request: id required",
  "error_code": "INVALID_ARGUMENT",
  "trace_id": "0123456789abcdef0123456789abcdef"
}

HTTP 404：当前账户和网络下没有该到账记录 ​

json
{
  "code": 404,
  "message": "not found",
  "error_code": "RESOURCE_NOT_FOUND",
  "trace_id": "0123456789abcdef0123456789abcdef"
}

HTTP 401：token 缺失、无效或已过期 ​

json
{
  "code": 401,
  "message": "authentication required or expired",
  "error_code": "TOKEN_INVALID_OR_EXPIRED",
  "trace_id": "0123456789abcdef0123456789abcdef"
}

完整字段与状态 ​

查看全部响应字段、嵌套对象及枚举 · 业务状态与处理 · 错误码排查。

查询与通知共用处理 ​

将同一笔到账的查询结果和通知解密结果交给同一业务函数，按appID+event_id持久化去重。custom_id可直接关联业务，无需再查询钱包。block_time是链上区块时间，created_at是平台入库时间；加密外层timestamp是本次发送时间。

延迟到账与记录核对 ​

同步恢复或完整性核验可能补录较早区块的到账。不要按区块时间距离当前时间的长短拒绝有效通知。已有到账的恢复保持原到账 ID；同一事件及版本不得重复记账。具体规则见到账核对与延迟处理。