Providers
Etherscan
The v2 API with one key for ten EVM chains and every operation. Five requests a second on the free tier, and the first choice whenever ETHERSCAN_API_KEY is set.
- provider
- create("etherscan")
- auth
- ETHERSCAN_API_KEY
- chains
- Ethereum, Base, Arbitrum One, Optimism, Polygon PoS, BNB Chain, Avalanche C-Chain, Gnosis Chain, Linea, Berachain
- capabilities
- balance, history, tx detail, contract, tokens, transfers, gas, block
- endpoint
- api.etherscan.io/v2/api
- default chain
- ethereum
Address it
import { create } from "@agntn/explorers";
const etherscan = await create("etherscan"); // ETHERSCAN_API_KEY from the environment
await etherscan.getBalance("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "base");
One key, ten chains. The provider sends the chain id with every request to api.etherscan.io/v2/api, so Base, Arbitrum, Optimism, Polygon, BSC, Avalanche, Gnosis, Linea and Berachain go through the same endpoint as Ethereum. Without the key the constructor throws AuthError before any request goes out.
What it reads
| Operation | Action |
|---|---|
| balance | account.balance |
| history | account.txlist, with startblock, endblock, sort, page, offset |
| one transaction | proxy.eth_getTransactionByHash plus the receipt for status and fee |
| contract | contract.getsourcecode, with proxy and implementation |
| token holdings | account.addresstokenbalance |
| token transfers | account.tokentx, optionally one contractaddress |
| gas | gastracker.gasoracle, in gwei |
| block | proxy.eth_getBlockByNumber |
Gotchas
- The free tier allows five requests a second. Past it the API answers with a rate limit message, which becomes
RateLimitError, and an automatic selection moves the read to Blockscout once. - Some chains keep some reads behind a paid plan. The gas oracle on BNB Chain is one; that is a
PlanRestrictedError, and the fallback pass tries Blockscout if it serves the chain. - "No transactions found" is an empty list, not an error. Etherscan phrases an empty page as a failure and the provider knows the phrasing.
- Amounts arrive as decimal strings and stay strings. Token decimals come with each transfer row.
Where it lives
src/providers/etherscan.ts.