到账记录列表

分页查询当前账户、当前网络已确认的 USDT 到账流水，返回自定义ID、资金信息、来源、合约、区块与时间。

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

请求地址

http

GET /open/v1/deposits

鉴权请求头

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

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

查询参数

GET 请求体必须为空。未提供或值为空的分页参数采用默认值。

字段	类型	必填	说明	示例值
page	integer（query 字符串）	否	页码，从 1 开始，默认 1。	`1`
page_size	integer（query 字符串）	否	每页 1–100 条，默认 20。	`20`
address	string	否	大小写不敏感的收款地址包含查询；只匹配收款钱包地址，不匹配 source 或 contract。	`TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM`

http

GET /open/v1/deposits?page=1&page_size=20

返回顺序固定为到账记录 ID 降序。未知字段直接返回400。地址查询中的 % 匹配任意长度内容，_ 匹配单个字符。

成功响应

HTTP 200。查询无匹配记录时，items=[]、total=0；请求页超出范围时，items=[]，但 total 仍为匹配记录总数。

字段	类型	必填	说明	示例值
code	integer	是	业务请求成功时固定为 0。	`0`
message	string	是	成功时固定为空字符串。	`""`
data	object	是	已确认到账流水的分页结果。	见下方 JSON 示例
data.network	string	是	资产所属网络：main（主网）或 nile（测试网络）。	"nile"
data.items	object[]	是	当前页数据；没有匹配记录时为 []。	`[]`
data.total	integer	是	符合当前筛选条件的记录总数，不是当前页数量。	`1`
data.page	integer	是	当前页码，从 1 开始。	`1`
data.page_size	integer	是	每页数量。	`20`

统一到账对象

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

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

json

{
  "code": 0,
  "message": "",
  "data": {
    "network": "nile",
    "items": [
      {
        "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
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}

到账流水与余额可能存在同步延迟，不能用到账记录的合计代替钱包余额。log_index 是整数，而 block_number、ID 和金额都是字符串；同一 txid 下可能出现多条不同日志索引的到账记录。

status 为 confirmed（达到确认门槛）或 reverted（因链重组撤销），应按 id 和 revision 更新本地到账状态。查询推送状态请调用通知详情，传入同一记录的event_id。到账对象不包含webhook字段。

单条记录可用到账详情查询。本接口不需要 request_id；不要发送 Idempotency-Key 请求头。

典型错误

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

HTTP 400：分页范围无效

json

{
  "code": 400,
  "message": "invalid request: invalid pagination",
  "error_code": "INVALID_ARGUMENT",
  "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；同一事件及版本不得重复记账。具体规则见到账核对与延迟处理。

到账记录列表 ​

请求地址 ​

鉴权请求头 ​

查询参数 ​

成功响应 ​

统一到账对象 ​

典型错误 ​

HTTP 400：分页范围无效 ​

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

完整字段与状态 ​

查询与通知共用处理 ​

延迟到账与记录核对 ​

到账记录列表

请求地址

鉴权请求头

查询参数

成功响应

统一到账对象

典型错误

HTTP 400：分页范围无效

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

完整字段与状态

查询与通知共用处理

延迟到账与记录核对