exploring-blockchain-data

探索区块链数据

概述

通过统一的 CLI 查询和分析多个兼容 EVM 的网络上的区块链数据，包括 Ethereum、Polygon、Arbitrum、Optimism 和 BSC。支持通过统一的 CLI 查询交易、检查地址余额、检查区块、查询代币余额、获取交易历史记录，以及追踪巨鲸钱包。

先决条件

• Python 3.8+，并安装 requests 和 web3 库（pip install requests web3）
• Etherscan API 密钥（免费套餐支持每秒 5 次请求；通过 ETHERSCAN_API_KEY 环境变量设置）
• 可选：Polygonscan、Arbiscan 及其他特定链的区块浏览器 API 密钥，以获得更高的速率限制
• 插件目录中需提供 blockchain_explorer.py CLI 脚本、chain_client.py 和 token_resolver.py 模块
• RPC 端点访问权限（公共端点可用；建议使用 Alchemy、Infura、Chainstack 或 QuickNode 等专用服务提供商，以提高可靠性）

说明

1. 将 Etherscan API 密钥设为环境变量：export ETHERSCAN_API_KEY=<key>，以突破默认每秒 5 次请求的速率限制。
2. 运行 python blockchain_explorer.py tx <hash>，按哈希查询交易，并返回状态、区块号、发送方/接收方地址、转账金额和 Gas 详情。
3. 在交易查询中添加 --detailed，以解码函数调用、识别交互协议并显示输入参数。
4. 如果在 Ethereum 上找不到该哈希，可指定 --chain polygon、--chain arbitrum 或 --chain bsc，查询其他 EVM 链上的交易。
5. 运行 python blockchain_explorer.py address <address>，检查钱包的原生代币余额和交易总数。
6. 在地址查询中添加 --history --limit 50，获取最近 50 笔交易及其时间戳、金额和交易对手方。
7. 在地址查询中添加 --tokens，通过 CoinGecko 价格解析列出所有 ERC-20 代币持仓及其余额、符号和 USD 价值。
8. 运行 python blockchain_explorer.py block latest 检查最新区块，或运行 python blockchain_explorer.py block <number> 检查指定区块。
9. 运行 python blockchain_explorer.py token <wallet> <contract>，查询指定钱包地址中某个 ERC-20 代币的余额，并自动解析精度和符号。
10. 使用 --format json 或 --format csv 将任意查询结果导出为 JSON 或 CSV 格式，并重定向到文件以供后续处理。
11. 使用 --verbose 启用详细模式，以显示 API 请求 URL、响应时间、缓存命中/未命中状态和速率限制计数器，便于调试。

完整的四步实现工作流请参见 ${CLAUDE_SKILL_DIR}/references/implementation.md。

输出

• 交易详情表，显示哈希、链、状态、区块号、发送方/接收方地址、金额、Gas 价格（Gwei）、Gas 限制、已使用的 Gas 和 Gas 费用
• 解码后的交易数据，包括函数名称、协议识别结果和解析后的输入参数（使用 --detailed 时）
• 地址摘要，包括原生代币余额、交易数量和区块浏览器链接
• 交易历史表，包括时间戳、哈希、发送方/接收方、金额和方向（转入/转出）
• 代币余额列表，包括合约地址、代币名称、符号、原始余额、易读余额和 USD 价值
• 区块详情，包括区块号、时间戳、交易数量、已使用的 Gas 和矿工/验证者
• JSON（output.json）或 CSV（transactions.csv）导出文件，供程序处理

错误处理

错误	原因	解决方案
Transaction not found	交易仍在内存池中待处理、选择了错误的链，或哈希无效	对于待处理的交易，请等待后重试；尝试使用 --chain polygon、--chain arbitrum、--chain bsc；确认哈希长度为 66 个字符且以 0x 开头
Explorer API error: Max rate limit reached	请求过多；未设置 API 密钥或配额已用尽	等待 1-5 秒后重试；设置 ETHERSCAN_API_KEY 以提高限额；生产环境使用时升级到付费套餐
RPC error: execution timeout	RPC 端点过载，或复杂查询超时	更换 RPC 端点后重试；使用专用服务提供商（Alchemy、Infura、QuickNode）；简化查询
Invalid address: 0xinvalid	地址长度错误、校验和无效，或包含非十六进制字符	确认地址为 42 个字符且带有 0x 前缀；使用区块浏览器提供的校验和地址；如果校验和验证失败，则转换为小写
Contract source code not verified	合约源代码未发布在浏览器上	使用已知的函数签名数据库进行解码；检查合约是否为代理，并查找其实现地址
Token: ??? (Unknown Token)	代币太新、过于冷门，或未被 CoinGecko 跟踪	直接在浏览器上查看代币合约；在 DEX（Uniswap、SushiSwap）上查找；如果知道精度，则手动指定
Price: N/A	CoinGecko 上没有该代币、API 请求频率受限，或流动性极低	在 DEX 上查看链上价格；使用其他价格数据源；根据 LP 储备量计算
ImportError: No module named 'requests'	缺少 Python 依赖项	运行 pip install requests web3 安装所需软件包

示例

跨链查询交易

# Try Ethereum first, then Polygon if not found
python blockchain_explorer.py tx 0x1234...abcdef --chain ethereum
python blockchain_explorer.py tx 0x1234...abcdef --chain polygon

返回格式化表格，其中包含交易状态、区块编号、转账金额、 Gas 详情以及区块浏览器链接。添加 --detailed 可解码函数调用（例如 Uniswap 上的 swapExactTokensForTokens）。

完整的钱包分析

python blockchain_explorer.py address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --history --tokens --limit 50

生成钱包摘要（ETH 余额、交易总数）、最近的 50 笔交易及其时间戳和交易对手方，以及完整的 ERC-20 代币持仓列表及其 USD 价值。适用于追踪巨鲸或对钱包进行尽职调查。

检查 USDC 余额并导出为 JSON

python blockchain_explorer.py token 0xYourWallet 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 --format json > usdc_balance.json

解析 USDC 合约，获取钱包余额并正确处理精度（USDC 为 6 位小数），包含当前 USD 价格，并将结果写入 usdc_balance.json，以便集成到仪表板或告警工作流中。

资源

• Etherscan API 文档 -- Ethereum 的主要区块浏览器 API；注册后可使用免费套餐
• CoinGecko API -- 代币价格解析和元数据查询
• web3.py 文档 -- 用于直接与 EVM 链进行 RPC 交互的 Python 库
• Alchemy / Infura / QuickNode -- 提供可靠节点访问的专用 RPC 服务提供商
• 4byte.directory -- 用于解码未验证合约交互的函数签名数据库