Etherscan API V2

Overview

Core model:

• One base URL: https://api.etherscan.io/v2/api
• One API key
• Switch chains via chainid

• Ethereum mainnet: https://etherscan.io/
• Ethereum hoodi: https://hoodi.etherscan.io/
• Taiko mainnet: https://taikoscan.io/
• Taiko hoodi: https://hoodi.taikoscan.io/

• references/network-map.md
• references/endpoint-cheatsheet.md
• references/rate-limits.md
• references/explorer-url-patterns.md

Required Inputs

• ETHERSCAN_API_KEY
• Target chainid
• Address / tx hash / block range
• Endpoint intent (activity, logs, source, ABI, status)

Deterministic Workflow

• Pick chainid from references/network-map.md.
• Choose endpoint by intent from references/endpoint-cheatsheet.md.
• Build request on https://api.etherscan.io/v2/api with required params.
• Parse status, message, result.
• If contract endpoint returns proxy metadata (Proxy == "1"), follow Implementation.
• For large history, paginate (page, offset) and/or narrow block ranges.

Method Selection

Quick Commands

export ETHERSCAN_API_KEY="<your_key>"

Get ABI (Taiko mainnet example):

curl -s "https://api.etherscan.io/v2/api?chainid=167000&module=contract&action=getabi&address=<contract>&apikey=$ETHERSCAN_API_KEY"

Get source + proxy metadata (Taiko hoodi example):

curl -s "https://api.etherscan.io/v2/api?chainid=167013&module=contract&action=getsourcecode&address=<contract>&apikey=$ETHERSCAN_API_KEY"

Get address activity in block window:

curl -s "https://api.etherscan.io/v2/api?chainid=1&module=account&action=txlist&address=<address>&startblock=<from>&endblock=<to>&page=1&offset=100&sort=desc&apikey=$ETHERSCAN_API_KEY"

Get logs for a contract in block window:

curl -s "https://api.etherscan.io/v2/api?chainid=560048&module=logs&action=getLogs&address=<contract>&fromBlock=<from>&toBlock=<to>&page=1&offset=1000&apikey=$ETHERSCAN_API_KEY"

Proxy-Aware Contract Handling

• Proxy: "1"
• non-empty Implementation

• Keep runtime call target as proxy address.
• Fetch ABI/source from implementation address.
• Decode selectors against implementation ABI.
• Re-check implementation before privileged write analysis.

Safety Rails

• Always set correct chainid; wrong chain silently yields wrong context.
• Respect plan limits and add client-side throttling/retries.
• Treat status: "0" as non-success even with HTTP 200.
• For analytics windows, lock startblock/endblock explicitly.
• For logs, remember offset max is 1000 per query and paginate.
• Keep retries idempotent and resume scans from stored cursors/block checkpoints.

Expected Output

• exact URL/query used (without exposing secret key)
• chain (chainid + explorer)
• endpoint (module/action)
• parsed status/result summary
• proxy follow-up decisions (Proxy, Implementation) when contract-related