Web3 数据浏览器（Chainbase）

通过 Chainbase Web3 API 和 SQL API 查询链上数据。

快速参考

API Key：使用环境变量 CHAINBASE_API_KEY，若未设置则回退至 demo。若遭遇速率限制，请引导用户前往 https://console.chainbase.com 升级套餐。

脚本命令：scripts/chainbase.sh [params...]

# 代币持有量排名前 10 的地址
scripts/chainbase.sh /v1/token/top-holders chain_id=1 contract_address=0xdAC17F958D2ee523a2206206994597C13D831ec7 limit=10

# 地址标签信息
scripts/chainbase.sh /v1/address/labels chain_id=1 address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

# 执行 SQL 查询
scripts/chainbase.sh /query/execute --sql="SELECT * FROM ethereum.blocks ORDER BY number DESC LIMIT 5"

链 ID（Chain IDs）

默认使用 Ethereum（chain_id=1），除非用户明确指定其他链。

路由逻辑

根据用户意图匹配最合适的 API 端点：

工作流程

1. 识别用户意图 — 明确用户所需的数据类型
2. 解析标识符 — 若用户提供代币名称（例如 “USDT”），需查找其合约地址。常见代币合约地址如下：
   • USDT：0xdAC17F958D2ee523a2206206994597C13D831ec7（Ethereum 主网）
   • USDC：0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48（Ethereum 主网）
   • WETH：0xC02aaA39b223FE8D0A0e5c4F27eAD9083C756Cc2（Ethereum 主网）
   • DAI：0x6B175474E89094C44Da98b954EedeAC495271d0F（Ethereum 主网）
   • WBTC：0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599（Ethereum 主网）
   • 若未知合约地址，可调用 GET /v1/token/metadata 自动查找，或向用户索取合约地址
3. 选择端点 — 参照上方路由表选择；对复杂或定制化查询，回退至 SQL API
4. 执行请求 — 使用 scripts/chainbase.sh 脚本或直接调用 curl
5. 呈现结果 — 清晰格式化返回数据，列表类结果建议使用表格展示，并突出关键洞察

SQL API 回退机制

当预定义端点无法满足查询需求时，将用户意图转化为 SQL 查询语句：

scripts/chainbase.sh /query/execute --sql="SELECT from_address, SUM(value) as total FROM ethereum.token_transfers WHERE contract_address = '0x...' GROUP BY from_address ORDER BY total DESC LIMIT 20"

常用表结构（将 ethereum 替换为对应链名）：

• {chain}.blocks — 区块数据
• {chain}.transactions — 交易数据
• {chain}.token_transfers — ERC20 转账记录
• {chain}.token_metas — 代币元数据
• {chain}.logs — 合约事件日志

SQL 查询限制：单次查询最多返回 100,000 条结果。

完整端点参数说明与响应结构，请参阅 references/api-endpoints.md。