etherscan
# Etherscan (API v2)
**Your job:** Query EVM chains without guessing. Wrong module/action = empty results. Wrong chain = silent failure.
| | |
| -------------- | --------------------------------------------------- |
| **Base URL** | `https://api.etherscan.io/v2/api` |
| **Auth** | `?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` → `{"api_key":"..."}`
2. **Environment variable** — `$ETHERSCAN_API_KEY`
3. **Ask user** (last resort) — acknowledge receipt, don't echo it
No key? → **https://etherscan.io/apidashboard** (register, generate free key)
Save it:
```bash
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:
```bash
curl -s "https://api.etherscan.io/v2/chainlist"
```
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 | `account` | `balance` | `address`, `tag=latest` |
| 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 | `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` |
**Native tokens** (ETH, BNB, MATIC): Use `module=account&action=balance`, no contract address.
---
## Quick Examples
### Check ETH Balance
```bash
curl -s "https://api.etherscan.io/v2/api?module=account&action=balance&address=0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb&chainid=1&tag=latest&apikey=${API_KEY}"
```
### Get Recent Transactions
```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}"
```
### Check USDC Balance
```bash
curl -s "https://api.etherscan.io/v2/api?module=account&action=tokenbalance&contractaddress=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48&address=0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb&chainid=1&tag=latest&apikey=${API_KEY}"
# Returns raw integer — divide by 10^6 for USDC
```
### Verify Transaction Status
```bash
curl -s "https://api.etherscan.io/v2/api?module=transaction&action=gettxreceiptstatus&txhash=0xABC...&chainid=1&apikey=${API_KEY}"
# result.status = "1" → success, "0" → failed
```
### Get Current Gas Prices
```bash
curl -s "https://api.etherscan.io/v2/api?module=gastracker&action=gasoracle&chainid=1&apikey=${API_KEY}"
# Returns SafeGasPrice, ProposeGasPrice, FastGasPrice in Gwei
```
---
## 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
- `message=NOTOK` → 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**
标签
skill
ai
