# Etherscan Family Scraper (Multi-Chain EVM Explorer) (`crawlerbros/etherscan-family-scraper`) Actor Query Etherscan and 18+ EVM block explorers (Ethereum, BNB, Polygon, Arbitrum, Optimism, Base, Avalanche, Fantom, etc.) via the unified Etherscan V2 API. Wallet balances, transactions, ERC-20/NFT transfers, contract source/ABI, gas oracle, tx-by-hash - **URL**: https://apify.com/crawlerbros/etherscan-family-scraper.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** Developer tools, Other - **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 11 bookmarks - **User rating**: 5.00 out of 5 stars ## Pricing from $3.00 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Etherscan Family Scraper Query **19 EVM-compatible blockchains** through one unified Etherscan V2 API. A single free Etherscan API key works across **Ethereum, BNB Smart Chain, Polygon, Arbitrum, Optimism, Base, Avalanche, Fantom, Linea, Scroll, Blast, zkSync Era, Polygon zkEVM, Mantle, Celo, Gnosis, Moonbeam, Moonriver, Cronos**. Lookup wallet/contract balances, transactions, ERC-20 transfers, NFT transfers, contract source code, gas oracle, and transaction details by hash — all from one actor. ### Quick Start 1. **Get a free Etherscan API key** at [etherscan.io/apis](https://etherscan.io/apis) — free tier is 5 req/sec and 100k req/day, and the same key works on **all** supported chains via the V2 API. 2. Pick a `chain` (defaults to `ethereum`). 3. Pick a `mode` and supply the relevant input. 4. Run. ```json { "etherscanApiKey": "YOUR_KEY", "chain": "ethereum", "mode": "byAddress", "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "maxItems": 5 } ```` > **Tip — store your key once.** Instead of pasting the key into every run, you can set the actor-level secret environment variable `ETHERSCAN_API_KEY` (Apify Console → your actor → **Source → Environment variables**, mark it secret). The actor uses the input value first and falls back to `ETHERSCAN_API_KEY` if the input is missing or set to a placeholder like `YOUR_ETHERSCAN_API_KEY`. ### Modes | Mode | What it does | Required input | |---|---|---| | `byAddress` | ETH balance + (optional) ERC-20 holdings + (optional) NFT contracts | `address` | | `txList` | Normal transaction history of an address | `address` (+ `startBlock`/`endBlock`/`sort`) | | `internalTxList` | Internal-call transaction history of an address | `address` | | `tokenTransfers` | ERC-20 transfer history of an address | `address` (+ optional `contractAddress` filter) | | `nftTransfers` | NFT (ERC-721 / ERC-1155) transfer history of an address | `address` (+ optional `contractAddress` filter) | | `byTransaction` | Decoded transaction + receipt by hash | `txHash` | | `byBlock` | Block detail by block number | `blockNumber` | | `byContract` | Verified contract source code, ABI, compiler metadata | `contractAddress` | | `tokenInfo` | ERC-20 / ERC-721 token metadata (PRO endpoint) | `contractAddress` | | `gasOracle` | Current safe / propose / fast gas prices | — | | `ethSupply` | Native-coin total supply | — | | `ethPrice` | Native-coin price (USD / BTC) | — | | `byUrl` | Auto-detect chain + mode from any Etherscan-family URL | `url` | ### Supported chains (with chainId) | Slug | Network | Chain ID | Explorer | |---|---|---:|---| | `ethereum` | Ethereum Mainnet | 1 | etherscan.io | | `bsc` | BNB Smart Chain | 56 | bscscan.com | | `polygon` | Polygon | 137 | polygonscan.com | | `arbitrum` | Arbitrum One | 42161 | arbiscan.io | | `optimism` | Optimism | 10 | optimistic.etherscan.io | | `base` | Base | 8453 | basescan.org | | `avalanche` | Avalanche C-Chain | 43114 | snowscan.xyz | | `fantom` | Fantom Opera | 250 | ftmscan.com | | `linea` | Linea | 59144 | lineascan.build | | `scroll` | Scroll | 534352 | scrollscan.com | | `blast` | Blast | 81457 | blastscan.io | | `zksync` | zkSync Era | 324 | era.zksync.network | | `polygonzkevm` | Polygon zkEVM | 1101 | zkevm.polygonscan.com | | `mantle` | Mantle | 5000 | mantlescan.xyz | | `celo` | Celo | 42220 | celoscan.io | | `gnosis` | Gnosis Chain | 100 | gnosisscan.io | | `moonbeam` | Moonbeam | 1284 | moonscan.io | | `moonriver` | Moonriver | 1285 | moonriver.moonscan.io | | `cronos` | Cronos | 25 | cronoscan.com | ### Sample record (`txList`) ```json { "recordType": "transaction", "chain": "ethereum", "chainId": 1, "txHash": "0xabc...", "blockNumber": 18000000, "from": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045", "to": "0x...", "valueWei": "1000000000000000000", "valueNative": 1.0, "nativeSymbol": "ETH", "gas": 21000, "gasPrice": 20000000000, "gasUsed": 21000, "isError": false, "timestamp": "2023-11-14T22:13:20+00:00", "explorerUrl": "https://etherscan.io/tx/0xabc...", "scrapedAt": "2026-05-09T12:00:00+00:00" } ``` ### FAQ **Do I need a separate API key per chain?** No. The Etherscan V2 API (released 2024) accepts a `chainid=` query parameter, so one free Etherscan key works across all 19 supported networks. **Free-tier limits?** 5 requests/second, 100,000 requests/day per key. The actor honors `Retry-After` headers and uses exponential backoff on `429` and `5xx`. **Where do I find an address / tx hash / contract address?** Paste any Etherscan-family URL into `mode=byUrl` and the actor will detect the chain + entity automatically. Examples: - `https://etherscan.io/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045` → ethereum + byAddress - `https://bscscan.com/tx/0x…64-hex` → bsc + byTransaction - `https://polygonscan.com/token/0x…40-hex` → polygon + byContract **Why is `tokenInfo` flagged "PRO"?** The `module=token&action=tokeninfo` endpoint requires Etherscan's paid API plan. Free keys get a "Missing/Invalid API Key" message — the actor reports this gracefully via `Actor.set_status_message`. Upgrade at etherscan.io/apis-pro for full access. **Why does `byAddress` only return a handful of records, not "all token holdings"?** ERC-20 holdings are derived from token-transfer history (the upstream API has no direct "list all balances" endpoint). The actor scans up to 5 pages of recent transfers, dedupes by token contract, then queries each token's current balance. Tokens never received via on-chain transfer (e.g., airdrops only delivered through claim contracts) won't appear. ### Limitations - `tokenInfo` requires a paid Etherscan API plan (PRO). - The V2 API does not support every legacy module on every chain — for example, `gasOracle` is only meaningful on chains with EIP-1559 active. - Source code for unverified contracts returns empty `sourceCode` / `abi` (we omit those fields rather than emit empty strings). - `byAddress` derives ERC-20 holdings from up to 500 most-recent transfers; addresses with very long transfer histories may miss tokens that were last interacted with beyond that window. - Rate limit is per-API-key, not per-chain — running many concurrent calls across different chains still counts against the same 5/sec budget. ### Output schema Every record carries `recordType`, `chain`, `chainId`, `scrapedAt`, plus mode-specific fields. Empty / null fields are stripped before push (no `null`, `""`, `[]`, `{}` in the dataset). ### URL fields Every record includes a verified `explorerUrl` pointing to the canonical Etherscan-family page for the entity (`/address/`, `/tx/`, `/block/`, `/address/.../#code`). # Actor input Schema ## `etherscanApiKey` (type: `string`): FREE Etherscan API key — sign up at https://etherscan.io/apis (one key works across ALL EVM chains via the V2 API). Free tier: 5 req/sec, 100k req/day. The included default works for the daily test; supply your own for production to avoid the shared rate limit. ## `chain` (type: `string`): Which EVM-compatible chain to query. ## `mode` (type: `string`): What to fetch. ## `address` (type: `string`): Wallet or contract address (0x...). Example: `0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045` (vitalik.eth). ## `contractAddress` (type: `string`): Smart-contract address. For tokenTransfers/nftTransfers, this filters to a specific token contract. ## `txHash` (type: `string`): 0x-prefixed 32-byte hex transaction hash. ## `blockNumber` (type: `integer`): Decimal block number. ## `url` (type: `string`): Etherscan-family URL — e.g. https://etherscan.io/address/0x... , https://bscscan.com/tx/0x... , https://polygonscan.com/token/0x... — chain + entity auto-detected. ## `includeErc20Holdings` (type: `boolean`): Fetch all ERC-20 tokens held by the address (derived from token-transfer history). ## `includeNftHoldings` (type: `boolean`): Fetch all NFT contracts the address has interacted with (derived from NFT-transfer history). ## `startBlock` (type: `integer`): Lower bound block number (inclusive). ## `endBlock` (type: `integer`): Upper bound block number (inclusive). ## `sort` (type: `string`): asc = oldest first, desc = newest first. ## `maxItems` (type: `integer`): Hard cap on emitted records. Example: `50`. ## Actor input object example ```json { "etherscanApiKey": "N7FBSTIFCDZE5S4ZY36JHT11U1B9B4YK11", "chain": "ethereum", "mode": "byAddress", "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "includeErc20Holdings": true, "includeNftHoldings": false, "sort": "desc", "maxItems": 5 } ``` # Actor output Schema ## `records` (type: `string`): Dataset containing all scraped Etherscan-family records. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "etherscanApiKey": "N7FBSTIFCDZE5S4ZY36JHT11U1B9B4YK11", "chain": "ethereum", "mode": "byAddress", "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "includeErc20Holdings": true, "includeNftHoldings": false, "sort": "desc", "maxItems": 5 }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/etherscan-family-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "etherscanApiKey": "N7FBSTIFCDZE5S4ZY36JHT11U1B9B4YK11", "chain": "ethereum", "mode": "byAddress", "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "includeErc20Holdings": True, "includeNftHoldings": False, "sort": "desc", "maxItems": 5, } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/etherscan-family-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "etherscanApiKey": "N7FBSTIFCDZE5S4ZY36JHT11U1B9B4YK11", "chain": "ethereum", "mode": "byAddress", "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "includeErc20Holdings": true, "includeNftHoldings": false, "sort": "desc", "maxItems": 5 }' | apify call crawlerbros/etherscan-family-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/etherscan-family-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Etherscan Family Scraper (Multi-Chain EVM Explorer)", "description": "Query Etherscan and 18+ EVM block explorers (Ethereum, BNB, Polygon, Arbitrum, Optimism, Base, Avalanche, Fantom, etc.) via the unified Etherscan V2 API. Wallet balances, transactions, ERC-20/NFT transfers, contract source/ABI, gas oracle, tx-by-hash", "version": "1.0", "x-build-id": "9KvUWN9Sb1oIuV58b" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~etherscan-family-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-etherscan-family-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/crawlerbros~etherscan-family-scraper/runs": { "post": { "operationId": "runs-sync-crawlerbros-etherscan-family-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/crawlerbros~etherscan-family-scraper/run-sync": { "post": { "operationId": "run-sync-crawlerbros-etherscan-family-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "etherscanApiKey", "chain", "mode" ], "properties": { "etherscanApiKey": { "title": "Etherscan API Key", "type": "string", "description": "FREE Etherscan API key — sign up at https://etherscan.io/apis (one key works across ALL EVM chains via the V2 API). Free tier: 5 req/sec, 100k req/day. The included default works for the daily test; supply your own for production to avoid the shared rate limit." }, "chain": { "title": "Chain", "enum": [ "ethereum", "bsc", "polygon", "arbitrum", "optimism", "base", "avalanche", "fantom", "linea", "scroll", "blast", "zksync", "polygonzkevm", "mantle", "celo", "gnosis", "moonbeam", "moonriver", "cronos" ], "type": "string", "description": "Which EVM-compatible chain to query.", "default": "ethereum" }, "mode": { "title": "Mode", "enum": [ "byAddress", "txList", "internalTxList", "tokenTransfers", "nftTransfers", "byTransaction", "byBlock", "byContract", "tokenInfo", "gasOracle", "ethSupply", "ethPrice", "byUrl" ], "type": "string", "description": "What to fetch.", "default": "byAddress" }, "address": { "title": "Address (mode=byAddress / txList / internalTxList / tokenTransfers / nftTransfers)", "type": "string", "description": "Wallet or contract address (0x...). Example: `0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045` (vitalik.eth).", "default": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }, "contractAddress": { "title": "Contract address (mode=byContract / tokenInfo / token-filtered transfers)", "type": "string", "description": "Smart-contract address. For tokenTransfers/nftTransfers, this filters to a specific token contract." }, "txHash": { "title": "Transaction hash (mode=byTransaction)", "type": "string", "description": "0x-prefixed 32-byte hex transaction hash." }, "blockNumber": { "title": "Block number (mode=byBlock)", "minimum": 0, "maximum": 99999999999, "type": "integer", "description": "Decimal block number." }, "url": { "title": "URL (mode=byUrl)", "type": "string", "description": "Etherscan-family URL — e.g. https://etherscan.io/address/0x... , https://bscscan.com/tx/0x... , https://polygonscan.com/token/0x... — chain + entity auto-detected." }, "includeErc20Holdings": { "title": "Include ERC-20 holdings (mode=byAddress)", "type": "boolean", "description": "Fetch all ERC-20 tokens held by the address (derived from token-transfer history).", "default": true }, "includeNftHoldings": { "title": "Include NFT holdings (mode=byAddress)", "type": "boolean", "description": "Fetch all NFT contracts the address has interacted with (derived from NFT-transfer history).", "default": false }, "startBlock": { "title": "Start block (mode=txList / internalTxList / tokenTransfers / nftTransfers)", "minimum": 0, "maximum": 99999999999, "type": "integer", "description": "Lower bound block number (inclusive)." }, "endBlock": { "title": "End block (mode=txList / internalTxList / tokenTransfers / nftTransfers)", "minimum": 0, "maximum": 99999999999, "type": "integer", "description": "Upper bound block number (inclusive)." }, "sort": { "title": "Sort order", "enum": [ "asc", "desc" ], "type": "string", "description": "asc = oldest first, desc = newest first.", "default": "desc" }, "maxItems": { "title": "Max items", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Hard cap on emitted records. Example: `50`.", "default": 50 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```