TronScan Data Lookup

TronScan 数据查询技能

概述

此技能可让 AI Agent 通过 TronScan API 查询 TRON 区块链。它提供 8 个 Node.js 脚本，涵盖所有主要数据查询操作：通用搜索、账户详情、交易、代币信息、区块、智能合约、转账历史和链级统计。

所有脚本都会将结构化 JSON 输出到 stdout，并将进度日志写入 stderr，遵循 bankofai 技能规范。

前置条件

• Node.js ^22.23.4 || ^24.22.1 || >=26.12.1
• npm（用于安装依赖）
• 首次使用前，在技能根目录运行 npm install

API 密钥（可选）

如果未配置 API 密钥，脚本会自动使用 BofAI 代理（ts.bankofai.io），无需进行设置。

如需改用自己的 TronScan API 密钥（可获得更高的速率限制），请设置环境变量：

export TRONSCAN_API_KEY="your-api-key-here"

前往 https://tronscan.org/#/myaccount/apiKeys 获取免费密钥。

速率限制

• 每秒最多 5 个请求
• 免费层级密钥总计最多 100,000 个请求
• 所有端点均使用 HTTP GET（合约事件批量查询除外）
• 每个请求的 limit 最大为 200（部分端点允许最大值为 500）
• 对于分页端点，start + limit 必须 <= 10,000

使用说明

1. 通用搜索

搜索地址、代币、合约、交易和区块。

node scripts/search.js <term> [--type <type>] [--limit <n>]

参数：

参数	说明	值
term	搜索查询（位置参数，必填）	任意字符串
--type	按结果类型筛选	token、address、contract、transaction、block
--limit	结果数量上限	1–50，默认 20

适用场景： 已知部分名称、地址或哈希，或需要确认某个对象在 TRON 上是什么时。

---

2. 账户详情

查询账户信息、余额、代币持仓和资源使用情况。

node scripts/account.js <address>                          # Full account details
node scripts/account.js <address> --tokens [--limit <n>]   # Token holdings
node scripts/account.js <address> --wallet                 # Portfolio with USD values
node scripts/account.js <address> --resources              # Bandwidth & energy
node scripts/account.js <address> --analysis --type <0-4>  # Daily analytics

模式：

标志	说明
(none)	完整账户详情（余额、创建日期、权限、见证人状态）
--tokens	所有代币余额。使用 --show 1 仅查看 TRC20，2 查看 TRC721，3 查看全部，4 查看 TRC1155
--wallet	显示以 USD 计价的投资组合
--resources	带宽／能量分配（Stake 2.0）
--analysis	每日分析。--type：0=余额，1=转账，2=能量，3=带宽，4=交易

适用场景： 用户询问 TRON 钱包余额、代币持仓、质押资源或账户历史时。

---

3. 交易查询

按哈希检索单笔交易，或按筛选条件列出交易。

node scripts/transaction.js <hash>                                  # By hash
node scripts/transaction.js --list [--from <addr>] [--to <addr>]    # Filtered list
node scripts/transaction.js --stats                                 # Network stats

列表选项：

参数	说明
--from	按发送方地址筛选
--to	按接收方地址筛选
--block	按区块编号筛选
--start_timestamp	开始时间（毫秒）
--end_timestamp	结束时间（毫秒）
--sort	排序字段（默认：-timestamp）
--limit	每页结果数（默认 20，最多 200）
--start	分页偏移量

适用场景： 用户想查询特定交易哈希，或查询某个地址的近期交易时。

---

4. 代币信息

获取代币详情、价格、持有人列表、供应量数据和排名。

node scripts/token.js --list [--filter <type>] [--sort <field>]   # Token rankings
node scripts/token.js --trc20 <contract_address>                  # TRC20 detail
node scripts/token.js --trc10 <token_id>                          # TRC10 detail
node scripts/token.js --price [symbol]                            # Current price
node scripts/token.js --holders <contract_address> [--limit <n>]  # Top holders
node scripts/token.js --supply <contract_address>                 # Total supply
node scripts/token.js --distribution <token_id>                   # Holdings distribution

列表筛选项： trc10、trc20、trc721、trc1155、all、top 排序字段： priceInTrx、gain、volume24hInTrx、holderCount、marketcap

适用场景： 用户询问特定代币（价格、持有人、供应量），或想浏览 TRON 上的热门代币时。

---

5. 区块信息

查询区块详情、近期区块或区块统计信息。

node scripts/block.js                                     # Latest block
node scripts/block.js <number>                            # By block number
node scripts/block.js --list --limit <n>                  # Recent blocks
node scripts/block.js --producer <address>                # By block producer
node scripts/block.js --stats                             # Network block stats

适用场景： 用户想查看最新区块、查询特定区块或查看区块生成统计信息时。

---

6. 智能合约详情

查询合约信息、能量使用情况、调用统计和调用方分析。

node scripts/contract.js <address>                         # Contract detail
node scripts/contract.js --list [--search <term>]          # Search/list contracts
node scripts/contract.js <address> --energy                # Energy consumption
node scripts/contract.js <address> --calls                 # Call statistics
node scripts/contract.js <address> --callers               # Caller list
node scripts/contract.js <address> --analysis --type <0-5> # Daily analytics

分析类型： 0=调用方，1=调用，2=能量，3=带宽，4=trx_transfers，5=token_transfers

使用场景： 用户询问智能合约的代码验证状态、使用情况、能量成本或调用方时。

---

7. 转账历史

查询地址和合约的 TRX、TRC10 和 TRC20 转账历史。

node scripts/transfer.js --trx <address>                             # TRX transfers
node scripts/transfer.js --trc20 <address> [--token <contract>]      # TRC20 transfers
node scripts/transfer.js --trc10 <address> [--token <token_id>]      # TRC10 transfers
node scripts/transfer.js --trc20-contract <contract> [--addr <addr>] # By contract
node scripts/transfer.js --internal <address>                        # Internal txns

常用选项：

参数	描述
--direction	0=全部，1=转入，2=转出
--start_timestamp	开始时间（毫秒）
--end_timestamp	结束时间（毫秒）
--limit	每页结果数（默认 20，最大 200）

使用场景： 用户想查看钱包的转账历史，包括转入/转出的 TRX、USDT 或其他代币时。

---

8. 链概览与统计数据

获取 TRON 网络高级数据、超级代表、治理和市场数据。

node scripts/overview.js                         # Full chain dashboard
node scripts/overview.js --tps                   # Current transactions per second
node scripts/overview.js --witnesses              # Super Representative list
node scripts/overview.js --params                 # Chain parameters
node scripts/overview.js --proposals              # Governance proposals
node scripts/overview.js --daily-accounts [days]  # New account growth
node scripts/overview.js --funds                  # TRX supply & burn data
node scripts/overview.js --trx-volume             # TRX price/volume history
node scripts/overview.js --nodes                  # Network node map

使用场景： 用户询问 TRON 网络状态、TPS、超级代表、治理、TRX 供应量或市场数据时。

示例

查询 TRON 钱包及其 USDT 余额

# Get full account info
node scripts/account.js TDqSquXBgUCLYvYC4XZgrprLK589dkhSCf

# Get token holdings with USD values
node scripts/account.js TDqSquXBgUCLYvYC4XZgrprLK589dkhSCf --wallet

检查交易

node scripts/transaction.js 7f4a6d28e3c5f1b2a9d8e7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b7a6

获取当前 TRX 价格

node scripts/token.js --price trx

按市值列出排名前 10 的 TRC20 代币

node scripts/token.js --list --filter trc20 --sort marketcap --limit 10

获取某地址近期的 USDT 转账记录

node scripts/transfer.js --trc20 TDqSquXBgUCLYvYC4XZgrprLK589dkhSCf --token TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t --limit 10

获取链概览

node scripts/overview.js

错误处理

所有脚本均以统一方式处理错误：

错误	原因	解决方案
Missing required argument	未提供必需的位置参数	查看脚本头部中的用法说明
Request failed with status 403	API 密钥无效或请求频率受限	检查 TRONSCAN_API_KEY，降低请求频率
Request failed with status 404	未找到端点或参数无效	验证地址/哈希格式
timeout of 15000ms exceeded	API 服务响应缓慢或无法访问	几秒后重试
ENOTFOUND	无网络连接	检查互联网连接

脚本出错时以代码 1 退出，并将 { "error": "message" } 输出到标准输出，以供机器解析。

安全注意事项

• API 密钥为只读，无法修改区块链状态
• API 密钥仅从 TRONSCAN_API_KEY 环境变量加载，绝不会硬编码
• 未设置 API 密钥时，请求将通过 BofAI 代理（ts.bankofai.io）发送，且不包含密钥标头
• 切勿在脚本调用中嵌入私钥或钱包机密
• 所有查询均为针对公开 TronScan API 的只读 GET 请求
• 如果 API 密钥曾暴露在日志或公开代码仓库中，应立即轮换
• 将请求频率限制在每秒最多 5 次，以避免密钥被撤销

常见代币地址

resources/common_tokens.json 文件包含常见主网代币地址。主要代币：

符号	合约地址	小数位数
TRX	(原生代币)	6
USDT	TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t	6
USDC	TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8	6
USDD	TPYmHEhy5n8TCEfYGqW2rPxsghSfzghPDn	18
WTRX	TNUC9Qb1rRpS5CbWLmNMxXBjyFoydXjWFR	6
BTT	TAFjULxiVgT4qWk6UZwjqwZXTSaGaqnVp4	18
JST	TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9	18
SUN	TSSMHYeV2uE9qYH95DqyoCuNCzEL1NvU3S	18

Agent 可以直接使用这些地址，无需搜索。

---

版本 2.0.0 — 由 M2M Agent Registry 为 Bank of AI 创建