获取交易列表
1. 概述与典型用途
按时间、地址、代币、区块等条件分页查询链上交易列表。
- 典型用途：浏览全链最新交易、按地址查询历史交易、按区块过滤交易记录。
- 何时不要用：查单笔交易详情用「通过交易哈希获取交易详情」；查代币转账用相应的转账列表接口。
2. 接口与鉴权
GET /api/transaction
Base URL 与鉴权见 公共网络与鉴权说明。
3. 请求
字段
| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
start | integer | 否 | 0 | 起始编号（偏移量）；start + limit ≤ 10000，超出被静默处理 |
limit | integer | 否 | 10 | 每页数量，最大 50（超出被静默截断） |
sort | string | 否 | -timestamp | 排序方式，-timestamp 按时间倒序 |
count | boolean | 否 | false | 是否返回交易总数 |
start_timestamp | integer | 否 | — | 起始时间，毫秒时间戳 |
end_timestamp | integer | 否 | — | 结束时间，毫秒时间戳 |
fromAddress | string | 否 | — | 发送方地址 |
toAddress | string | 否 | — | 接收方地址 |
address | string | 否 | — | 账户地址过滤（发送方或接收方匹配） |
tokens | string | 否 | — | 涉及的代币 |
block | integer | 否 | — | 按区块号过滤 |
type | string | 否 | — | 交易类型 |
direction | string | 否 | all | 转账方向：in（转入）、out（转出）、all（全部） |
confirm | string | 否 | — | 确认状态：0 已确认 / 1 未确认 / 2 已回退 / 空 全部；可逗号组合如 0,1 |
dry-run | string | 否 | — | 设为任意非空值时，跳过数据库总数查询，total 返回 0，可提升响应速度 |
4. 响应
字段
顶层
| 字段 | 类型 | 是否必返 | 说明 | 单位/精度 |
|---|---|---|---|---|
total | integer | 必返 | 命中总数（上限 10000，用于分页） | — |
rangeTotal | integer | 必返 | 过滤范围内总数 | — |
data | array | 必返 | 交易记录数组，见下 | — |
wholeChainTxCount | integer | 必返 | 全链交易总数 | — |
contractMap | object | 可选 | 地址 → 是否为合约的映射 | — |
contractInfo | object | 可选 | 合约地址 → 标签信息映射；value schema 见下 | — |
normalAddressInfo | object | 可选 | 非合约地址 → 风险信息映射；每地址 value 实测仅含 risk（boolean），无其他子字段 | — |
data[] 元素
| 字段 | 类型 | 是否必返 | 说明 | 单位/精度 |
|---|---|---|---|---|
block | integer | 必返 | 区块高度 | — |
hash | string | 必返 | 交易哈希 | — |
timestamp | integer | 必返 | 区块时间 | 毫秒时间戳 ms |
ownerAddress | string | 必返 | 发起方地址（Base58，T 开头） | — |
toAddress | string | 必返 | 接收方地址 | — |
toAddressList | array | 必返 | 接收方地址列表 | — |
contractType | integer | 必返 | 合约类型编号 | — |
confirmed | boolean | 必返 | 是否已确认 | — |
revert | boolean | 必返 | 是否已回退 | — |
contractData | object | 必返 | 合约调用数据，子字段见下方 contractData 对象表 | — |
contractRet | string | 必返 | 合约执行结果（如 SUCCESS） | — |
result | string | 必返 | 交易结果 | — |
amount | string | 必返 | 交易金额（原值字符串） | — |
cost | object | 必返 | 资源消耗详情，子字段见下方 cost 对象表 | — |
tokenInfo | object | 必返 | 代币元信息；子字段 schema 见下 | — |
tokenType | string | 必返 | 代币类型标识 | — |
noteLevel | integer | 必返 | 风险级别标注 | — |
cheatStatus | boolean | 必返 | 是否为欺诈交易 | — |
riskTransaction | boolean | 必返 | 风险交易标记 | — |
SmartCalls | string | 必返 | 智能合约调用信息（非合约调用时为空字符串） | — |
Events | string | 必返 | 合约事件信息（非合约调用时为空字符串） | — |
data | string | 必返 | 原始交易数据（通常为空字符串） | — |
fee | string | 必返 | 手续费信息（通常为空字符串） | — |
id | string | 必返 | 记录 ID（通常为空字符串） | — |
trigger_info | object | 可选 | 合约调用方法与入参（仅智能合约调用时出现），schema 与 transaction-info trigger_info 兼容超集 —— 额外含 data（原始 hex 调用数据）+ methodName（人可读方法名） | — |
toAddressTag | string | 可选 | 接收方地址标签；仅当接收方地址有公开标签时 key 出现，值为标签字符串 | — |
ownerAddressTag | string | 可选 | 发送方地址标签；仅当发送方地址有公开标签时 key 出现，值为标签字符串 | — |
contractData 对象
| 字段 | 类型 | 是否必返 | 说明 | 单位/精度 |
|---|---|---|---|---|
owner_address | string | 必返 | 发起方地址 | — |
data | string | 可选 | 调用数据（智能合约调用时出现） | hex |
to_address | string | 可选 | 接收方地址（TRX/TRC10 转账时出现） | — |
amount | integer | 可选 | 转账金额（TRX/TRC10 转账时出现） | sun（TRX）/ 原值（TRC10） |
asset_name | string | 可选 | TRC10 资产名（TRC10 转账时出现） | — |
contract_address | string | 可选 | 被调用合约地址（智能合约调用时出现） | — |
tokenInfo | object | 可选 | 代币元信息（涉及代币时出现）；子字段 schema 见下 | — |
contractInfo[<addr>] 对象 schema（8 字段）：
| 字段 | 类型 | 是否必返 | 说明 |
|---|---|---|---|
tag1 | string | 必返 | 主标签（项目名 / 合约名 / 交易所名） |
tag1Url | string | 必返 | 主标签链接 URL（可为空字符串） |
name | string | 必返 | 合约 / 项目正式名称 |
isToken | boolean | 必返 | 是否代币合约（true / false） |
vip | boolean | 必返 | 是否 VIP 实体（true / false） |
risk | boolean | string | 必返 | 风险标签；多数 endpoint 返回 boolean，部分返回字符串风险类型（blacklist / fraud 等） |
publicTagDesc | string | 必返 | 公开标签描述；多数账户为空字符串 |
publicTag | string | 可选 | 公开标签（如 "USDT Token" / "Binance"）；仅知名实体或部分接口返回 |
data[].tokenInfo / contractData.tokenInfo 对象 schema（通用 9 字段）：
| 字段 | 类型 | 是否必返 | 说明 | 单位/精度 |
|---|---|---|---|---|
tokenId | string | 必返 | 代币合约地址（Base58）；TRX 占位符为 _ | — |
tokenAbbr | string | 必返 | 代币缩写（如 USDT / TRX） | — |
tokenName | string | 必返 | 代币名称 | — |
tokenDecimal | integer | 必返 | 精度位数（amount 字段换算所需） | — |
tokenCanShow | integer | 必返 | 是否可展示（1 是 / 0 否） | — |
tokenType | string | 必返 | 代币类型（trc10 / trc20 / trc721 / trc1155） | — |
tokenLogo | string | 必返 | 代币 logo URL | — |
tokenLevel | string | 必返 | 代币等级（已观测值："0" / "1" / "2" / "4"，具体语义以后端定义为准） | — |
vip | boolean | 必返 | 是否为 VIP 代币 | — |
cost 对象
| 字段 | 类型 | 是否必返 | 说明 | 单位/精度 |
|---|---|---|---|---|
fee | integer | 必返 | 总手续费 | sun |
net_fee | integer | 必返 | 带宽手续费 | sun |
net_usage | integer | 必返 | 带宽消耗 | bytes |
energy_fee | integer | 必返 | 能量手续费 | sun |
energy_usage | integer | 必返 | 调用者能量消耗 | — |
energy_usage_total | integer | 必返 | 总能量消耗 | — |
origin_energy_usage | integer | 必返 | 合约拥有者能量消耗 | — |
energy_penalty_total | integer | 必返 | 能量惩罚总量 | — |
date_created | integer | 可选 | 交易创建时间（部分交易类型返回） | 秒时间戳 s |
5. 错误
HTTP 状态码见 公共错误说明。本接口要点：
- 参数违规不报错：
limit > 50、start + limit > 10000等被静默截断/限制并返回200，不要依赖报错来发现参数问题。 - 空结果 ≠ 错误：无命中返回
200+data: []，属于正常响应。
最后更新于: