Etherscan gives builders one explorer account and one API surface for multichain EVM lookups, contract verification, and debugging workflows. This protocol reference now makes the evaluation takeaway explicit up front: when Etherscan fits better than a node provider alone, how the V2 chainid model changes integration planning, and where to jump next for request-ready implementation details.
- 01transaction and log lookups
- 02ABI + contract source verification
- 03gas oracle and block data
- 04ERC-20/721/1155 transfer history
- 05multichain reads with one key
| Variable | Scope | Description |
|---|---|---|
| ETHERSCAN_API_KEY | Server | Etherscan API key (V2 — works across all 60+ supported EVM chains). Server-only. |
Use the Etherscan V2 unified API for any EVM chain reads. Base URL is `https://api.etherscan.io/v2/api` and you target a chain via `chainid` (1=Ethereum, 8453=Base, 42161=Arbitrum, 10=Optimism, 56=BNB, 137=Polygon). Example: `GET https://api.etherscan.io/v2/api?chainid=8453&module=account&action=txlist&address=0x...&apikey=$ETHERSCAN_API_KEY`. The same key works for `module=contract&action=getsourcecode`, `module=logs&action=getLogs`, gas oracle, and verification. Replace any legacy `api.basescan.org` / `api.arbiscan.io` calls with the V2 endpoint plus `chainid`.
- ⚑V1 per-chain endpoints (api.basescan.org, api.arbiscan.io, etc.) were deprecated August 2025 — only V2 with `chainid` is supported for new builds.
- ⚑Free tier rate limit is 5 calls/sec per key; sustained bursts get 429s. Pro tiers go up to 30 calls/sec.
- ⚑Daily quota (typically 100k calls free) is per-key, not per-chain — multichain apps consume the same bucket.
- ⚑Pagination caps at 10,000 records per query; for full history, use `startblock`/`endblock` windowing rather than offset paging.
- ⚑Etherscan V2 is EVM-only — for Solana/Bitcoin/Cosmos use a different provider (Helius, Mempool, etc.).
- ⚑Always URL-encode addresses and keep the API key server-side; never ship it in a client bundle.