Etherscan

Query EVM chain data via Etherscan API v2. Use for on-chain lookups where Etherscan v2 applies: balances, transactions, token transfers (ERC-20/721/1155), co...

Security Scan

The skill's requests and runtime instructions are coherent with its stated purpose (querying Etherscan API); it only asks for an Etherscan API key (file or env) and makes HTTP GET calls — no unrelated credentials, installs, or surprising system access.

Purpose & Capability

Name/description match the instructions: all documented endpoints, chain list fetch, and API key usage are directly tied to querying Etherscan v2. No unrelated services or credentials are requested.

Instruction Scope

SKILL.md instructs the agent to read an API key from ~/.config/etherscan/credentials.json or $ETHERSCAN_API_KEY, to cache a chain list fetched from Etherscan, and to persist the API key to disk (example bash snippet). These actions are within scope for an API client, but they introduce persistent storage of a secret which the user should be aware of.

Install Mechanism

No install spec and no code files — instruction-only skill. That minimizes disk writes/install risk.

Credentials

Only an Etherscan API key is referenced (via env var or credentials file). The number and type of secrets requested are proportionate to the stated functionality; no unrelated environment variables or cloud credentials are requested.

Persistence & Privilege

Skill is not always-included and uses normal autonomous invocation defaults. It does instruct storing the API key to ~/.config/etherscan/credentials.json (with suggested chmod 600) — this is expected but the user should note the persistent secret on disk and where it is written.

Assessment

This skill appears coherent and only needs an Etherscan API key. Before installing: (1) Prefer providing the key via an environment variable rather than letting the agent write a credentials file, or review/accept the exact file path (~/.config/etherscan/credentials.json) and its permissions if you want persistence. (2) Use a dedicated, limited Etherscan key (read-only) you can revoke if needed. (3) Be cautious about pasting secrets into chat — the SKILL.md says 'don't echo it', but copy/paste can leak into logs; if asked for the key interactively, supply it via the environment or the designated file instead. (4) Note the skill can run autonomously (normal default); because it only uses the Etherscan key and public HTTP calls, the blast radius is limited, but revoke the key if you see unexpected behavior. (5) If you require stricter guarantees, ask the publisher for more details or prefer transient keys rather than persistent files.

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