etherscan-api

name	etherscan-api
description	This skill should be used when the user asks to "check ETH balance", "query ERC-20 balance", "get wallet balance", "check token holdings", "query Etherscan", or mentions Etherscan API, blockchain balance queries, or multi-chain balance lookups.

Etherscan API V2

Overview

Query blockchain balances using Etherscan's unified API V2. This skill covers:

• Native ETH balance queries
• ERC-20 token balance queries
• Multi-chain support via the chainid parameter

Scope: This skill focuses on balance queries for free-tier accounts. For other Etherscan API features, consult the fallback documentation.

Prerequisites

API Key Validation

Before making any API call, verify the ETHERSCAN_API_KEY environment variable is set:

if [ -z "$ETHERSCAN_API_KEY" ]; then
  echo "Error: ETHERSCAN_API_KEY environment variable is not set."
  echo "Get a free API key at: https://etherscan.io/myapikey"
  exit 1
fi

If the environment variable is missing, inform the user and halt execution.

Chain Inference

Do not default to Ethereum Mainnet. Always infer the chain from the user's prompt before making any API call.

Inference Rules

1. Explicit chain mention — If the user mentions a chain name (e.g., "on Polygon", "Arbitrum balance", "Base chain"), use that chain.
2. Chain-specific tokens — Some tokens exist primarily on specific chains:
   • POL → Polygon (137)
   • ARB → Arbitrum One (42161)
   • OP → OP Mainnet (10)
   • AVAX → Avalanche C-Chain (43114)
   • BNB → BNB Smart Chain (56)
   • SONIC → Sonic (146)
   • SEI → Sei (1329)
   • MON → Monad (143)
3. Contract address patterns — If the user provides a contract address, consider asking which chain it's deployed on (many contracts exist on multiple chains).
4. Testnet keywords — Words like "testnet", "Sepolia", "Holesky", "Amoy" indicate testnet chains.
5. Ambiguous cases — If the chain cannot be inferred, ask the user before proceeding. Do not assume Ethereum Mainnet.

Unsupported Chains

If the user references a chain not supported by Etherscan (e.g., Solana, Bitcoin), inform them:

The chain "[chain name]" is not supported by Etherscan API V2.

Etherscan supports EVM-compatible chains only. For the full list, see:
https://docs.etherscan.io/etherscan-v2/getting-started/supported-chains

For the complete list of supported chains and their IDs, see ./references/CHAINS.md.

API Base URL

All requests use the unified V2 endpoint:

https://api.etherscan.io/v2/api

The chainid parameter determines which blockchain to query.

ETH Balance Query

Query native ETH (or native token) balance for an address.

Endpoint Parameters

Parameter	Required	Default	Description
chainid	No	1	Chain ID (see CHAINS.md)
module	Yes	-	Set to account
action	Yes	-	Set to balance
address	Yes	-	Wallet address (supports up to 20 comma-separated)
tag	No	latest	Block tag (latest, pending, or hex block number)
apikey	Yes	-	API key from $ETHERSCAN_API_KEY

Single Address Query

curl -s "https://api.etherscan.io/v2/api?chainid=1&module=account&action=balance&address=0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe&tag=latest&apikey=$ETHERSCAN_API_KEY"

Multi-Address Query (up to 20)

curl -s "https://api.etherscan.io/v2/api?chainid=1&module=account&action=balancemulti&address=0xaddress1,0xaddress2,0xaddress3&tag=latest&apikey=$ETHERSCAN_API_KEY"

Response Format

Single address:

{
  "status": "1",
  "message": "OK",
  "result": "172774397764084972158218"
}

Multi-address:

{
  "status": "1",
  "message": "OK",
  "result": [
    {"account": "0xaddress1", "balance": "1000000000000000000"},
    {"account": "0xaddress2", "balance": "2500000000000000000"}
  ]
}

ERC-20 Token Balance Query

Query ERC-20 token balance for an address.

Endpoint Parameters

Parameter	Required	Default	Description
chainid	No	1	Chain ID (see CHAINS.md)
module	Yes	-	Set to account
action	Yes	-	Set to tokenbalance
contractaddress	Yes	-	ERC-20 token contract address
address	Yes	-	Wallet address to query
tag	No	latest	Block tag
apikey	Yes	-	API key from $ETHERSCAN_API_KEY

Example Query

curl -s "https://api.etherscan.io/v2/api?chainid=1&module=account&action=tokenbalance&contractaddress=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48&address=0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe&tag=latest&apikey=$ETHERSCAN_API_KEY"

Response Format

{
  "status": "1",
  "message": "OK",
  "result": "135499000000"
}

Multi-Chain Usage

Specify the chainid parameter to query different blockchains.

Common Chain IDs (Free Tier)

Chain	Chain ID
Ethereum	1
Polygon	137
Arbitrum One	42161
Linea	59144
Scroll	534352
zkSync	324

Example: Polygon Query

curl -s "https://api.etherscan.io/v2/api?chainid=137&module=account&action=balance&address=0x...&tag=latest&apikey=$ETHERSCAN_API_KEY"

For the complete list of supported chains, see ./references/CHAINS.md.

Wei to Human-Readable Conversion

API responses return balances in the smallest unit (wei for ETH, smallest decimals for tokens).

ETH Conversion

Divide by 10^18:

# Using bc for precision
echo "scale=18; 172774397764084972158218 / 1000000000000000000" | bc
# Result: 172774.397764084972158218

ERC-20 Conversion

Divide by 10^decimals (typically 18, but varies per token):

Token	Decimals
Most tokens	18
USDC, USDT	6
WBTC	8

# USDC example (6 decimals)
echo "scale=6; 135499000000 / 1000000" | bc
# Result: 135499.000000

Output Formatting

Default behavior: Present results in a Markdown table:

| Address | Balance (ETH) | Chain |
|---------|---------------|-------|
| 0xde0B...7BAe | 172,774.40 | Ethereum |
| 0xabc1...2def | 50.25 | Polygon |

User preference: If the user requests a specific format (JSON, CSV, plain text, etc.), use that format instead. Do not generate a Markdown table when the user specifies an alternative output format.

Free Tier Limitations

The following chains require a paid Etherscan plan and are not available on free tier:

• Base (8453)
• OP Mainnet (10)
• Avalanche C-Chain (43114)
• BNB Smart Chain (56)

If a user requests a query on these chains, inform them that a paid plan is required.

Error Handling

Common Error Responses

Status	Message	Cause
0	NOTOK	Invalid API key or rate limited
0	Invalid address format	Malformed address
0	No transactions found	Address has no activity

Rate Limits (Free Tier)

• 5 calls/second
• 100,000 calls/day

If rate limited, wait briefly and retry.

Reference Files

• ./references/CHAINS.md - Complete list of supported chains with chain IDs

Fallback Documentation

For use cases not covered by this skill (transaction history, contract verification, gas estimates, etc.), fetch the AI-friendly documentation:

https://docs.etherscan.io/llms.txt

Use WebFetch to retrieve this documentation for extended API capabilities.