Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
init
✓ import { init } from 'etherscan-api';
// For CommonJS:
const { init } = require('etherscan-api');
✗ import EtherscanApi from 'etherscan-api'; // 'init' is a named export, not a default export
The primary function to initialize the API client. It is exposed as a named export within the CommonJS module.
pickChainUrl
✓ import { pickChainUrl } from 'etherscan-api';
// For CommonJS:
const { pickChainUrl } = require('etherscan-api');
✗ import pickChainUrl from 'etherscan-api'; // 'pickChainUrl' is a named export
A utility function for programmatically selecting the base URL for different supported blockchain explorers (e.g., Etherscan, Arbiscan, Snowtrace) based on network name.
EtherscanClientInstance
✓ import { init } from 'etherscan-api';
const api = init('YOUR_API_KEY', 'homestead');
✗ const api = new EtherscanAPI(); // 'etherscan-api' does not export a class constructor, 'init' returns the instance
The `init` function returns the API client instance, which is then used to access specific API modules and methods (e.g., `api.account.balance`).
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.
const { init } = require('etherscan-api');
const API_KEY = process.env.ETHERSCAN_API_KEY ?? ''; // Always use environment variables for sensitive data
if (!API_KEY) {
console.error('Error: Please set the ETHERSCAN_API_KEY environment variable.');
process.exit(1);
}
// Initialize the API for Ethereum Mainnet (homestead). 'null' or 'homestead' can be used for mainnet.
const api = init(API_KEY, 'homestead');
const targetAddress = '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'; // Example: Ethereum Foundation address
console.log(`Fetching balance for address: ${targetAddress} on Ethereum Mainnet...`);
api.account.balance(targetAddress)
.then(balanceData => {
if (balanceData && balanceData.status === '1' && balanceData.result) {
const wei = BigInt(balanceData.result);
const ether = Number(wei) / (10**18); // Convert Wei to Ether
console.log(`Balance in Wei: ${balanceData.result}`);
console.log(`Balance in Ether: ${ether.toFixed(4)}`);
} else {
console.error('Error fetching balance:', balanceData);
}
})
.catch(error => {
console.error('An unexpected error occurred:', error.message);
});
Debug
Known issues
breakingThe 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+.fixMonitor the official GitHub repository for announcements regarding the NEXTGEN version's release, migration guides, and specific breaking changes. Plan for potential refactoring when upgrading.
affects: >=10.3.0 (future versions)
gotchaEtherscan 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.fixImplement 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.
affects: >=1.0.0
gotchaUsing 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.fixEnsure 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.
affects: >=1.0.0
gotchaIncorrectly 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').fixAlways 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.
affects: >=1.0.0
Errors
Common errors & fixes
{ status: '0', message: 'NOTOK', result: 'Invalid API Key' }
The provided API key is either incorrect, expired, or missing in the `init` call.
fixVerify 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')`. { status: '0', message: 'NOTOK', result: 'Max rate limit reached, please use API Key for higher rate limit' }
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.
fixObtain 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.
UnhandledPromiseRejectionWarning: Unhandled promise rejection.
The promise returned by API methods (e.g., `api.account.balance()`) was not caught, meaning errors are not handled.
fixAlways 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));`
Error: Network Error / Request failed with status code 404
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.
fixDouble-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.
Audit
Dependencies
axiosrequiredHTTP client used internally for API requests, though a custom instance can be provided.