Etherscan gives builders one explorer account and one API surface for multichain EVM lookups, contract verification, and debugging workflows. This protocol reference now leads with the setup questions the latest search demand actually signals: which API V2 base URL to use, how chainid changes multichain request builders, and when to jump from high-level protocol evaluation into request-ready implementation details.
- 01Centralize the V2 base URL at https://api.etherscan.io/v2/api, then treat chainid as a required input in every request builder instead of swapping explorer hosts per network.
- 02Use Etherscan first for account history, contract ABI or source lookups, logs, and support-debugging flows where explorer data is faster to wire than a custom indexing stack.
- 03Keep the API key server-side and document request examples for Ethereum, Base, Arbitrum, and Optimism so multichain teams can review one consistent explorer pattern.
- 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.