web3-data

使用 Chainbase API 探索 Web3 链上数据。当用户询问时使用此技能 区块链数据、代币持有者、钱包地址、代币价格、NFT、ENS 域、交易、 DeFi 投资组合或任何链上分析。触发因素包括：“最高持有者”、“谁持有”、 “钱包地址”、“地址标签”、“代币价格”、“代币转账”、“NFT 所有者”、 “ENS域”、“链上数据”、“区块链查询”、“链上SQL查询”或任何请求 查找、分析或探索跨以太坊、BSC、Polygon、Arbitrum 的 Web3/区块链数据， Optimism、Base、Avalanche、zkSync 和其他 EVM 链。

# Web3 Data Explorer (Chainbase)

Query on-chain data via Chainbase Web3 API and SQL API.

## Quick Reference

**API Key**: Use env `CHAINBASE_API_KEY`, falls back to `demo`. If rate-limited, direct user to https://console.chainbase.com to upgrade.

**Script**: `scripts/chainbase.sh <endpoint> [params...]`

```bash
# Top token holders
scripts/chainbase.sh /v1/token/top-holders chain_id=1 contract_address=0xdAC17F958D2ee523a2206206994597C13D831ec7 limit=10

# Address labels
scripts/chainbase.sh /v1/address/labels chain_id=1 address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

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

## Chain IDs

| Chain | ID | Chain | ID |
|---|---|---|---|
| Ethereum | 1 | Optimism | 10 |
| BSC | 56 | Base | 8453 |
| Polygon | 137 | zkSync | 324 |
| Avalanche | 43114 | Merlin | 4200 |
| Arbitrum | 42161 | | |

Default to Ethereum (chain_id=1) unless user specifies otherwise.

## Routing Logic

Match user intent to the right endpoint:

| User wants | Endpoint |
|---|---|
| Top token holders / who holds a token | `GET /v1/token/top-holders` |
| List of holder addresses | `GET /v1/token/holders` |
| Token price | `GET /v1/token/price` |
| Historical token price | `GET /v1/token/price/history` |
| Token info (name, symbol, supply) | `GET /v1/token/metadata` |
| Token transfer history | `GET /v1/token/transfers` |
| Address labels/tags | `GET /v1/address/labels` |
| Wallet transaction history | `GET /v1/account/txs` |
| Single transaction detail | `GET /v1/tx/detail` |
| Native token balance (ETH/BNB) | `GET /v1/account/balance` |
| ERC20 token balances of wallet | `GET /v1/account/tokens` |
| NFTs owned by wallet | `GET /v1/account/nfts` |
| DeFi portfolio positions | `GET /v1/account/portfolios` |
| ENS domain lookup | `GET /v1/ens/records` or `/v1/ens/reverse` |
| NFT metadata/owner/rarity | `GET /v1/nft/metadata`, `/owner`, `/rarity` |
| Trending NFT collections | `GET /v1/nft/collection/trending` |
| **Anything not covered above** | **SQL API** (`POST /query/execute`) |

## Workflow

1. **Identify intent** — Determine what data the user needs
2. **Resolve identifiers** — If user gives token name (e.g. "USDT"), look up the contract address. Common tokens:
   - USDT: `0xdAC17F958D2ee523a2206206994597C13D831ec7` (ETH)
   - USDC: `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` (ETH)
   - WETH: `0xC02aaA39b223FE8D0A0e5c4F27eAD9083C756Cc2` (ETH)
   - DAI: `0x6B175474E89094C44Da98b954EedeAC495271d0F` (ETH)
   - WBTC: `0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599` (ETH)
   - If unknown, use `GET /v1/token/metadata` or ask the user for the contract address
3. **Select endpoint** — Use the routing table above; fall back to SQL API for complex/custom queries
4. **Execute** — Run via `scripts/chainbase.sh` or direct `curl`
5. **Present results** — Format data clearly with tables for lists, highlight key insights

## SQL API Fallback

When fixed endpoints don't cover the query, translate user intent to SQL:

```bash
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"
```

Common table patterns (replace `ethereum` with chain name):
- `{chain}.blocks` — Block data
- `{chain}.transactions` — Transactions
- `{chain}.token_transfers` — ERC20 transfers
- `{chain}.token_metas` — Token metadata
- `{chain}.logs` — Event logs

SQL constraints: max 100,000 results per query.

For complete endpoint parameters and response schemas, read [references/api-endpoints.md](references/api-endpoints.md).

---

## 中文说明

# Web3 数据浏览器（Chainbase）

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

## 速查参考

**API Key**：使用环境变量 `CHAINBASE_API_KEY`，否则回退为 `demo`。如遇限流，引导用户前往 https://console.chainbase.com 升级。

**脚本**：`scripts/chainbase.sh <endpoint> [params...]`

```bash
# Top token holders
scripts/chainbase.sh /v1/token/top-holders chain_id=1 contract_address=0xdAC17F958D2ee523a2206206994597C13D831ec7 limit=10

# Address labels
scripts/chainbase.sh /v1/address/labels chain_id=1 address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

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

## 链 ID

| 链 | ID | 链 | ID |
|---|---|---|---|
| Ethereum | 1 | Optimism | 10 |
| BSC | 56 | Base | 8453 |
| Polygon | 137 | zkSync | 324 |
| Avalanche | 43114 | Merlin | 4200 |
| Arbitrum | 42161 | | |

除非用户另有指定，否则默认使用 Ethereum（chain_id=1）。

## 路由逻辑

将用户意图匹配到正确的端点：

| 用户需求 | 端点 |
|---|---|
| 顶级代币持有者 / 谁持有某代币 | `GET /v1/token/top-holders` |
| 持有者地址列表 | `GET /v1/token/holders` |
| 代币价格 | `GET /v1/token/price` |
| 历史代币价格 | `GET /v1/token/price/history` |
| 代币信息（名称、符号、供应量） | `GET /v1/token/metadata` |
| 代币转账历史 | `GET /v1/token/transfers` |
| 地址标签/标记 | `GET /v1/address/labels` |
| 钱包交易历史 | `GET /v1/account/txs` |
| 单笔交易详情 | `GET /v1/tx/detail` |
| 原生代币余额（ETH/BNB） | `GET /v1/account/balance` |
| 钱包的 ERC20 代币余额 | `GET /v1/account/tokens` |
| 钱包持有的 NFT | `GET /v1/account/nfts` |
| DeFi 投资组合持仓 | `GET /v1/account/portfolios` |
| ENS 域名查询 | `GET /v1/ens/records` 或 `/v1/ens/reverse` |
| NFT 元数据/所有者/稀有度 | `GET /v1/nft/metadata`、`/owner`、`/rarity` |
| 热门 NFT 系列 | `GET /v1/nft/collection/trending` |
| **以上未涵盖的任何内容** | **SQL API**（`POST /query/execute`） |

## 工作流程

1. **识别意图** —— 确定用户需要什么数据
2. **解析标识符** —— 如果用户给出代币名称（如 "USDT"），查找其合约地址。常见代币：
   - USDT：`0xdAC17F958D2ee523a2206206994597C13D831ec7`（ETH）
   - USDC：`0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`（ETH）
   - WETH：`0xC02aaA39b223FE8D0A0e5c4F27eAD9083C756Cc2`（ETH）
   - DAI：`0x6B175474E89094C44Da98b954EedeAC495271d0F`（ETH）
   - WBTC：`0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599`（ETH）
   - 如未知，使用 `GET /v1/token/metadata` 或向用户询问合约地址
3. **选择端点** —— 使用上面的路由表；复杂/自定义查询则回退到 SQL API
4. **执行** —— 通过 `scripts/chainbase.sh` 或直接 `curl` 运行
5. **呈现结果** —— 清晰地格式化数据，列表用表格呈现，突出关键洞察

## SQL API 回退

当固定端点无法覆盖查询时，将用户意图转换为 SQL：

```bash
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](references/api-endpoints.md)。