etherscan-api

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