{"id":16351,"library":"etherscan-api","title":"Etherscan API Client","description":"This library provides a promise-based client for interacting with the Etherscan.io API, as well as several other blockchain explorers like Arbiscan and Snowtrace. It simplifies fetching blockchain data such as account balances, transaction details, and contract information, abstracting away direct HTTP requests. The current stable version is 10.3.0. The project currently indicates that development has started on a \"NEXTGEN\" version, suggesting future significant changes or a new major release is anticipated. It offers flexibility by allowing users to provide their own Axios instance for custom request configurations, and supports various Ethereum testnets and L2 networks beyond just Etherscan's mainnet, distinguishing it by its multi-chain support and configurable HTTP client.","status":"active","version":"10.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/sebs/etherscan-api","tags":["javascript","arbiscan","ethereum","EtherScan.io","etherscan","blockchain","api","transaction","rest"],"install":[{"cmd":"npm install etherscan-api","lang":"bash","label":"npm"},{"cmd":"yarn add etherscan-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add etherscan-api","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"HTTP client used internally for API requests, though a custom instance can be provided.","package":"axios","optional":false}],"imports":[{"note":"The primary function to initialize the API client. It is exposed as a named export within the CommonJS module.","wrong":"import EtherscanApi from 'etherscan-api'; // 'init' is a named export, not a default export","symbol":"init","correct":"import { init } from 'etherscan-api';\n// For CommonJS:\nconst { init } = require('etherscan-api');"},{"note":"A utility function for programmatically selecting the base URL for different supported blockchain explorers (e.g., Etherscan, Arbiscan, Snowtrace) based on network name.","wrong":"import pickChainUrl from 'etherscan-api'; // 'pickChainUrl' is a named export","symbol":"pickChainUrl","correct":"import { pickChainUrl } from 'etherscan-api';\n// For CommonJS:\nconst { pickChainUrl } = require('etherscan-api');"},{"note":"The `init` function returns the API client instance, which is then used to access specific API modules and methods (e.g., `api.account.balance`).","wrong":"const api = new EtherscanAPI(); // 'etherscan-api' does not export a class constructor, 'init' returns the instance","symbol":"EtherscanClientInstance","correct":"import { init } from 'etherscan-api';\nconst api = init('YOUR_API_KEY', 'homestead');"}],"quickstart":{"code":"const { init } = require('etherscan-api');\nconst API_KEY = process.env.ETHERSCAN_API_KEY ?? ''; // Always use environment variables for sensitive data\n\nif (!API_KEY) {\n  console.error('Error: Please set the ETHERSCAN_API_KEY environment variable.');\n  process.exit(1);\n}\n\n// Initialize the API for Ethereum Mainnet (homestead). 'null' or 'homestead' can be used for mainnet.\nconst api = init(API_KEY, 'homestead');\n\nconst targetAddress = '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'; // Example: Ethereum Foundation address\n\nconsole.log(`Fetching balance for address: ${targetAddress} on Ethereum Mainnet...`);\n\napi.account.balance(targetAddress)\n  .then(balanceData => {\n    if (balanceData && balanceData.status === '1' && balanceData.result) {\n      const wei = BigInt(balanceData.result);\n      const ether = Number(wei) / (10**18); // Convert Wei to Ether\n      console.log(`Balance in Wei: ${balanceData.result}`);\n      console.log(`Balance in Ether: ${ether.toFixed(4)}`);\n    } else {\n      console.error('Error fetching balance:', balanceData);\n    }\n  })\n  .catch(error => {\n    console.error('An unexpected error occurred:', error.message);\n  });","lang":"javascript","description":"This example demonstrates how to initialize the Etherscan API client using an API key and fetch the ETH balance for a specific address on the Ethereum Mainnet, handling the promise resolution and potential errors."},"warnings":[{"fix":"Monitor the official GitHub repository for announcements regarding the NEXTGEN version's release, migration guides, and specific breaking changes. Plan for potential refactoring when upgrading.","message":"The project README explicitly states: \"Development of a NEXTGEN Version has started - please stand by\". This strongly indicates that future major versions will introduce significant breaking changes to the API and internal architecture. Developers should be prepared for migrations when upgrading from v10.x to a potential v11+.","severity":"breaking","affected_versions":">=10.3.0 (future versions)"},{"fix":"Implement retry logic with exponential backoff for failed requests. Configure a custom Axios instance with longer timeouts (as shown in the README) and potentially a custom rate-limiting middleware or library (e.g., `axios-rate-limit`). Ensure your API key is valid and not shared.","message":"Etherscan and other supported blockchain explorers enforce API rate limits. Exceeding these limits without proper handling will result in failed requests and HTTP 429 'Too Many Requests' errors. The default timeout might also not be sufficient for all network conditions.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your `init` call includes a valid API key obtained from Etherscan (or the respective explorer). Store API keys securely using environment variables (`process.env.ETHERSCAN_API_KEY`) and avoid hardcoding them in your codebase.","message":"Using an invalid or missing API key will lead to API request failures, often returning a status '0' with a 'NOTOK' message from the Etherscan API. This is a common setup issue for all supported explorers.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always explicitly pass the desired network string (e.g., `'rinkeby'`, `'arbitrum'`) as the second argument to the `init` function when targeting anything other than Ethereum Mainnet: `init(apiKey, 'rinkeby')`. Use `pickChainUrl` to confirm valid network strings.","message":"Incorrectly specifying the network for testnets or L2 solutions (e.g., Rinkeby, Goerli, Arbitrum) can lead to unexpected data or errors. The default network for `init` without the second argument is usually Ethereum Mainnet ('homestead').","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Verify your API key on Etherscan.io (or other explorer's API page), generate a new one if necessary, and ensure it's correctly passed as the first argument to `etherscanApi.init('YOUR_API_KEY')`.","cause":"The provided API key is either incorrect, expired, or missing in the `init` call.","error":"{ status: '0', message: 'NOTOK', result: 'Invalid API Key' }"},{"fix":"Obtain a valid Etherscan API key and pass it to `init()`. For higher volume, consider Etherscan's premium plans or implement robust rate-limiting and retry logic in your application.","cause":"The client has exceeded the Etherscan API rate limits. This can happen quickly without an API key or with a free-tier key under heavy load.","error":"{ status: '0', message: 'NOTOK', result: 'Max rate limit reached, please use API Key for higher rate limit' }"},{"fix":"Always attach a `.catch()` block to your promise chains or use `try...catch` with `async/await` to handle potential errors from API requests: `api.account.balance(...).then(...).catch(error => console.error(error));`","cause":"The promise returned by API methods (e.g., `api.account.balance()`) was not caught, meaning errors are not handled.","error":"UnhandledPromiseRejectionWarning: Unhandled promise rejection."},{"fix":"Double-check the network string passed to `init()` (e.g., 'rinkeby', 'arbitrum') for typos. Verify your internet connection and that the target explorer's API is operational.","cause":"The API client failed to reach the blockchain explorer server. This could be due to an incorrect chain URL, network connectivity issues, or an unsupported network configuration.","error":"Error: Network Error / Request failed with status code 404"}],"ecosystem":"npm"}