Etherscan (API v2)

Your job: Query EVM chains without guessing. Wrong module/action = empty results. Wrong chain = silent failure.

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:

mkdir -p ~/.config/etherscan
cat > ~/.config/etherscan/credentials.json \x3C\x3C '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:

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:

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:

Native tokens (ETH, BNB, MATIC): Use module=account&action=balance, no contract address.

Quick Examples

Check ETH Balance

curl -s "https://api.etherscan.io/v2/api?module=account&action=balance&address=0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb&chainid=1&tag=latest&apikey=${API_KEY}"

Get Recent Transactions

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

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

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

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 \x3C 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