OpenSkillIndex← back to search
claude-codeopenclawdata

Skills etherscan

install
source · Clone the upstream repo
git clone https://github.com/openclaw/skills
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/0xv4l3nt1n3/etherscan" ~/.claude/skills/openclaw-skills-etherscan && rm -rf "$T"
OpenClaw · Install into ~/.openclaw/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.openclaw/skills && cp -r "$T/skills/0xv4l3nt1n3/etherscan" ~/.openclaw/skills/openclaw-skills-etherscan && rm -rf "$T"
manifest: skills/0xv4l3nt1n3/etherscan/SKILL.md
tags
#blockchain#ethereum#api#evm#etherscan#data-lookup
source content

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
CitationEnd 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 needmoduleactionKey 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:

TokenChainDecimalsAddress
WETHEthereum18
0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2
USDCEthereum6
0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
USDTEthereum6
0xdAC17F958D2ee523a2206206994597C13D831ec7
DAIEthereum18
0x6B175474E89094C44Da98b954EedeAC495271d0F
WBTCEthereum8
0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599
WBNBBSC18
0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c
USDCBSC18
0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d
WMATICPolygon18
0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270
USDCPolygon6
0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359
WETHArbitrum18
0x82aF49447D8a07e3bd95BD0d56f35241523fBab1
USDCArbitrum6
0xaf88d065e77c8cC2239327C5EDb3A432268e5831
ARBArbitrum18
0x912CE59144191C1204E64559FE8253a0e49E6548
WETHBase18
0x4200000000000000000000000000000000000006
USDCBase6
0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
WETHOptimism18
0x4200000000000000000000000000000000000006
USDCOptimism6
0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85
OPOptimism18
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