Etherscan API Client

Common errors

• { status: '0', message: 'NOTOK', result: 'Invalid API Key' }

  cause The provided API key is either incorrect, expired, or missing in the `init` call.
  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')`.

• { status: '0', message: 'NOTOK', result: 'Max rate limit reached, please use API Key for higher rate limit' }

  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.
  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.

• UnhandledPromiseRejectionWarning: Unhandled promise rejection.

  cause The promise returned by API methods (e.g., `api.account.balance()`) was not caught, meaning errors are not handled.
  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));`

• Error: Network Error / Request failed with status code 404

  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.
  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.

Warnings

• breaking 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+.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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').
  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.

Install

• npm install etherscan-api npm
• yarn add etherscan-api yarn
• pnpm add etherscan-api pnpm

Imports

• init
  wrong:

  import EtherscanApi from 'etherscan-api'; // 'init' is a named export, not a default export

  correct:

  import { init } from 'etherscan-api';
  // For CommonJS:
  const { init } = require('etherscan-api');

  The primary function to initialize the API client. It is exposed as a named export within the CommonJS module.
• pickChainUrl
  wrong:

  import pickChainUrl from 'etherscan-api'; // 'pickChainUrl' is a named export

  correct:

  import { pickChainUrl } from 'etherscan-api';
  // For CommonJS:
  const { pickChainUrl } = require('etherscan-api');

  A utility function for programmatically selecting the base URL for different supported blockchain explorers (e.g., Etherscan, Arbiscan, Snowtrace) based on network name.
• EtherscanClientInstance
  wrong:

  const api = new EtherscanAPI(); // 'etherscan-api' does not export a class constructor, 'init' returns the instance

  correct:

  import { init } from 'etherscan-api';
  const api = init('YOUR_API_KEY', 'homestead');

  The `init` function returns the API client instance, which is then used to access specific API modules and methods (e.g., `api.account.balance`).

Quickstart

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);
  });