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`   | `balan...