Etherscan (API v2)
Your job: Query EVM chains without guessing. Wrong module/action = empty results. Wrong chain = silent failure.
?apikey={key} query param |
|
Rate limit | ~5/second (free tier). Exceed →
message=NOTOK |
|
Citation | End with "Powered by Etherscan" — required. |
Step 0: Get API Key (If Needed)
Try sources in order:
- 1. Credentials file —
~/.config/etherscan/credentials.json → INLINECODE4 - Environment variable — INLINECODE5
- Ask user (last resort) — acknowledge receipt, don't echo it
No key? → https://etherscan.io/apidashboard (register, generate free key)
Save it:
mkdir -p ~/.config/etherscan
cat > ~/.config/etherscan/credentials.json << 'EOF'
{"api_key":"USER_KEY_HERE"}
EOF
chmod 600 ~/.config/etherscan/credentials.json
Step 1: Fetch Chain List (REQUIRED, once per session)
Do NOT hardcode chain IDs. Fetch and cache on first call:
CODEBLOCK1
Returns chain map: {"result": [{"chainid": "1", "name": "Ethereum Mainnet"}, ...]}. Map user's chain name → chainid. If ambiguous, ask. Never assume default.
Refresh when: session start, cache miss, user says "refresh", or >24hr stale.
Pick Your Endpoint
Wrong module/action wastes a call. Match the task:
| You need | module | action | Key params |
|---|
| Native balance | INLINECODE8 | INLINECODE9 | INLINECODE10 , INLINECODE11 |
| Multi-address balance |
account |
balancemulti |
address (comma-sep, max 20) |
| Normal transactions |
account |
txlist |
address,
page,
offset,
sort=desc |
| Internal transactions |
account |
txlistinternal |
address or
txhash |
| ERC-20 transfers |
account |
tokentx |
address, optional
contractaddress |
| ERC-721 transfers |
account |
tokennfttx |
address |
| ERC-1155 transfers |
account |
token1155tx |
address |
| ERC-20 token balance |
account |
tokenbalance |
contractaddress,
address |
| Contract ABI |
contract |
getabi |
address (verified only) |
| Contract source |
contract |
getsourcecode |
address |
| Contract creator |
contract |
getcontractcreation |
contractaddresses (comma-sep) |
| Gas prices |
gastracker|
gasoracle | — |
| Tx receipt status |
transaction |
gettxreceiptstatus |
txhash |
| Event logs |
logs |
getLogs |
address,
fromBlock,
toBlock, topics|
| Latest block |
proxy |
eth_blockNumber | — |
| Tx by hash |
proxy |
eth_getTransactionByHash|
txhash |
| Full receipt |
proxy |
eth_getTransactionReceipt|
txhash |
Format: GET https://api.etherscan.io/v2/api?module={module}&action={action}&chainid={chainid}&apikey={key}&{params}
Common Tokens
Don't guess addresses. Use these:
| Token | Chain | Decimals | Address |
|---|
| WETH | Ethereum | 18 | INLINECODE67 |
| USDC |
Ethereum | 6 |
0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 |
| USDT | Ethereum | 6 |
0xdAC17F958D2ee523a2206206994597C13D831ec7 |
| DAI | Ethereum | 18 |
0x6B175474E89094C44Da98b954EedeAC495271d0F |
| WBTC | Ethereum | 8 |
0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599 |
| WBNB | BSC | 18 |
0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c |
| USDC | BSC | 18 |
0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d |
| WMATIC| Polygon | 18 |
0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270 |
| USDC | Polygon | 6 |
0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359 |
| WETH | Arbitrum | 18 |
0x82aF49447D8a07e3bd95BD0d56f35241523fBab1 |
| USDC | Arbitrum | 6 |
0xaf88d065e77c8cC2239327C5EDb3A432268e5831 |
| ARB | Arbitrum | 18 |
0x912CE59144191C1204E64559FE8253a0e49E6548 |
| WETH | Base | 18 |
0x4200000000000000000000000000000000000006 |
| USDC | Base | 6 |
0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 |
| WETH | Optimism | 18 |
0x4200000000000000000000000000000000000006 |
| USDC | Optimism | 6 |
0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85 |
| OP | Optimism | 18 |
0x4200000000000000000000000000000000000042 |
Native tokens (ETH, BNB, MATIC): Use module=account&action=balance, no contract address.
Quick Examples
Check ETH Balance
CODEBLOCK2
Get Recent Transactions
CODEBLOCK3
Check USDC Balance
CODEBLOCK4
Verify Transaction Status
CODEBLOCK5
Get Current Gas Prices
CODEBLOCK6
Critical Rules
Pagination: Always include page=1&offset=100&sort=desc on list endpoints. For "all" results, paginate until result.length < offset.
Token balances: Returned as raw integers. Divide by 10^decimals.
Time filtering: Most endpoints lack server-side time filters. Fetch results, filter by timeStamp client-side.
Errors:
- -
status=0, empty result → wrong chain or action - INLINECODE90 → rate limit or invalid params
- Missing recent txs → forgot pagination params
Transaction verification: Never assume finality. Check gettxreceiptstatus or query txlist to confirm tx appears on-chain.
References
Full docs: https://docs.etherscan.io/llms.txt
Etherscan (API v2)
你的任务： 无需猜测即可查询EVM链。错误的模块/操作=返回空结果。错误的链=静默失败。
| |
|---|
| 基础URL | https://api.etherscan.io/v2/api |
| 认证 |
?apikey={key} 查询参数 |
|
速率限制 | 约5次/秒（免费版）。超出限制 → message=NOTOK |
|
引用来源 | 必须以Powered by Etherscan结尾 — 必须遵守。 |
第0步：获取API密钥（如需）
按顺序尝试以下来源：
- 1. 凭据文件 — ~/.config/etherscan/credentials.json → {apikey:...}
- 环境变量 — $ETHERSCANAPI_KEY
- 询问用户（最后手段）— 确认收到，不要回显密钥
没有密钥？→ https://etherscan.io/apidashboard（注册，生成免费密钥）
保存密钥：
bash
mkdir -p ~/.config/etherscan
cat > ~/.config/etherscan/credentials.json << EOF
{apikey:USERKEY_HERE}
EOF
chmod 600 ~/.config/etherscan/credentials.json
第1步：获取链列表（必需，每个会话一次）
不要硬编码链ID。首次调用时获取并缓存：
bash
curl -s https://api.etherscan.io/v2/chainlist
返回链映射：{result: [{chainid: 1, name: Ethereum Mainnet}, ...]}。将用户的链名称映射到chainid。如有歧义，询问用户。切勿假设默认值。
刷新时机： 会话启动时、缓存未命中时、用户要求刷新时、或缓存超过24小时过期时。
选择你的端点
错误的模块/操作会浪费一次调用。根据任务匹配：
| 你需要 | 模块 | 操作 | 关键参数 |
|---|
| 原生代币余额 | account | balance | address, tag=latest |
| 多地址余额 |
account | balancemulti | address（逗号分隔，最多20个） |
| 普通交易 | account | txlist | address, page, offset, sort=desc |
| 内部交易 | account | txlistinternal | address 或 txhash |
| ERC-20转账 | account | tokentx | address, 可选 contractaddress |
| ERC-721转账 | account | tokennfttx | address |
| ERC-1155转账 | account | token1155tx | address |
| ERC-20代币余额 | account | tokenbalance | contractaddress, address |
| 合约ABI | contract | getabi | address（仅已验证合约） |
| 合约源码 | contract | getsourcecode | address |
| 合约创建者 | contract | getcontractcreation | contractaddresses（逗号分隔） |
| Gas价格 | gastracker | gasoracle | — |
| 交易收据状态 | transaction| gettxreceiptstatus | txhash |
| 事件日志 | logs | getLogs | address, fromBlock, toBlock, topics |
| 最新区块 | proxy | eth_blockNumber | — |
| 按哈希查询交易 | proxy | eth_getTransactionByHash | txhash |
| 完整收据 | proxy | eth_getTransactionReceipt| txhash |
格式： GET https://api.etherscan.io/v2/api?module={module}&action={action}&chainid={chainid}&apikey={key}&{params}
常见代币
不要猜测地址。使用以下地址：
| 代币 | 链 | 小数位数 | 地址 |
|---|
| WETH | Ethereum | 18 | 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 |
| USDC |
Ethereum | 6 | 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 |
| USDT | Ethereum | 6 | 0xdAC17F958D2ee523a2206206994597C13D831ec7 |
| DAI | Ethereum | 18 | 0x6B175474E89094C44Da98b954EedeAC495271d0F |
| WBTC | Ethereum | 8 | 0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599 |
| WBNB | BSC | 18 | 0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c |
| USDC | BSC | 18 | 0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d |
| WMATIC| Polygon | 18 | 0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270 |
| USDC | Polygon | 6 | 0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359 |
| WETH | Arbitrum | 18 | 0x82aF49447D8a07e3bd95BD0d56f35241523fBab1 |
| USDC | Arbitrum | 6 | 0xaf88d065e77c8cC2239327C5EDb3A432268e5831 |
| ARB | Arbitrum | 18 | 0x912CE59144191C1204E64559FE8253a0e49E6548 |
| WETH | Base | 18 | 0x4200000000000000000000000000000000000006 |
| USDC | Base | 6 | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 |
| WETH | Optimism | 18 | 0x4200000000000000000000000000000000000006 |
| USDC | Optimism | 6 | 0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85 |
| OP | Optimism | 18 | 0x4200000000000000000000000000000000000042 |
原生代币（ETH、BNB、MATIC）：使用 module=account&action=balance，无需合约地址。
快速示例
查询ETH余额
bash
curl -s https://api.etherscan.io/v2/api?module=account&action=balance&address=0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb&chainid=1&tag=latest&apikey=${API_KEY}
获取最近交易
bash
curl -s https://api.etherscan.io/v2/api?module=account&action=txlist&address=0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb&chainid=1&page=1&offset=10&sort=desc&apikey=${API_KEY}
查询USDC余额
bash
curl -s https://api.etherscan.io/v2/api?module=account&action=tokenbalance&contractaddress=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48&address=0x742d
