etherscan

Etherscan (API v2)

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

Base URL	https://api.etherscan.io/v2/api
Auth	?apikey={key} query param
Rate limit	~5/second (free tier). Exceed → message=NOTOK
Citation	End with "Powered by Etherscan" — required.

---

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 << '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:

You need	module	action	Key params
Native balance	account	balance	address, tag=latest
Multi-address balance	account	balancemulti	address (comma-sep, max 20)
Normal transactions	account	txlist	address, page, offset, sort=desc
Internal transactions	account	txlistinternal	address or txhash
ERC-20 transfers	account	tokentx	address, optional contractaddress
ERC-721 transfers	account	tokennfttx	address
ERC-1155 transfers	account	token1155tx	address
ERC-20 token balance	account	tokenbalance	contractaddress, address
Contract ABI	contract	getabi	address (verified only)
Contract source	contract	getsourcecode	address
Contract creator	contract	getcontractcreation	contractaddresses (comma-sep)
Gas prices	gastracker	gasoracle	—
Tx receipt status	transaction	gettxreceiptstatus	txhash
Event logs	logs	getLogs	address, fromBlock, toBlock, topics
Latest block	proxy	eth_blockNumber	—
Tx by hash	proxy	eth_getTransactionByHash	txhash
Full receipt	proxy	eth_getTransactionReceipt	txhash

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:

Token	Chain	Decimals	Address
WETH	Ethereum	18	0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2
USDC	Ethereum	6	0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
USDT	Ethereum	6	0xdAC17F958D2ee523a2206206994597C13D831ec7
DAI	Ethereum	18	0x6B175474E89094C44Da98b954EedeAC495271d0F
WBTC	Ethereum	8	0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599
WBNB	BSC	18	0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c
USDC	BSC	18	0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d
WMATIC	Polygon	18	0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270
USDC	Polygon	6	0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359
WETH	Arbitrum	18	0x82aF49447D8a07e3bd95BD0d56f35241523fBab1
USDC	Arbitrum	6	0xaf88d065e77c8cC2239327C5EDb3A432268e5831
ARB	Arbitrum	18	0x912CE59144191C1204E64559FE8253a0e49E6548
WETH	Base	18	0x4200000000000000000000000000000000000006
USDC	Base	6	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
WETH	Optimism	18	0x4200000000000000000000000000000000000006
USDC	Optimism	6	0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85
OP	Optimism	18	0x4200000000000000000000000000000000000042

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