etherscan-api — CLI для получения данных 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: ```bash 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 ```bash 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) ```bash 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:** ```json { "status": "1", "message": "OK", "result": "172774397764084972158218" } ``` **Multi-address:** ```json { "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 ```bash 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 ```json { "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 ```bash 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: ```bash # 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 | ```bash # USDC example (6 decimals) echo "scale=6; 135499000000 / 1000000" | bc # Result: 135499.000000 ``` ## Output Formatting **Default behavior:** Present results in a Markdown table: ```markdown | 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.