@n4mchun/etherscan-sdk

Type-safe TypeScript SDK for the Etherscan V2 API with multichain support.

• Single API key for 60+ EVM chains
• Fully typed request params and responses
• Built-in rate limiting
• Zero dependencies (uses native fetch)
• ESM + CJS dual package

Install

npm install @n4mchun/etherscan-sdk

Quick Start

import { EtherscanClient, ChainId } from "@n4mchun/etherscan-sdk";

const client = new EtherscanClient({ apiKey: "YOUR_API_KEY" });

// Get ETH balance
const balance = await client.account.getBalance({
  address: "0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe",
});

// Get transactions on Polygon
const txs = await client.account.getTxList(
  { address: "0x...", page: 1, offset: 10 },
  ChainId.POLYGON,
);

// Gas oracle
const gas = await client.gasTracker.gasOracle();
console.log(`Safe: ${gas.SafeGasPrice} Gwei`);

Configuration

const client = new EtherscanClient({
  apiKey: "YOUR_API_KEY",    // Required
  chainId: ChainId.ETHEREUM, // Default chain (default: 1)
  rateLimit: 5,              // Max requests/sec (default: 5)
});

Every module method accepts an optional chainId parameter as the last argument to override the default chain per-request.

Modules

account

| Method | Description | |---|---| | getBalance | Native token balance (wei) | | getBalanceMulti | Multiple address balances (up to 20) | | getBalanceHistory | Historical balance at block (PRO) | | getTxList | Normal transaction list | | getTxListInternal | Internal transaction list | | getTokenTx | ERC-20 transfer events | | getTokenNftTx | ERC-721 transfer events | | getToken1155Tx | ERC-1155 transfer events | | getTokenBalance | ERC-20 token holdings (PRO) | | getTokenNftBalance | ERC-721 holdings (PRO) | | getTokenNftInventory | NFT inventory by contract (PRO) | | getMinedBlocks | Blocks mined/validated | | getFundedBy | Initial funder of an EOA (PRO) | | getDepositTxs | L2 deposit txs (Arbitrum/OP only) |

contract

| Method | Description | |---|---| | getAbi | Verified contract ABI | | getSourceCode | Verified contract source | | getContractCreation | Creator address & tx (up to 5) | | checkVerifyStatus | Source verification status | | checkProxyVerification | Proxy verification status |

transaction

| Method | Description | |---|---| | getStatus | Execution error status | | getReceiptStatus | Receipt status (1=success) |

block

| Method | Description | |---|---| | getBlockCountdown | Time until target block | | getBlockNoByTime | Block number by timestamp | | getBlockReward | Block & uncle rewards |

logs

| Method | Description | |---|---| | getLogs | Event logs with topic filtering |

stats

| Method | Description | |---|---| | getEthPrice | Current native token price | | getEthSupply | Total supply (wei) | | getEthSupply2 | Supply breakdown | | getEthDailyPrice | Historical daily price (PRO) | | getChainSize | Blockchain size | | getDailyBlockCount | Daily block count (PRO) | | getDailyAvgBlockSize | Daily avg block size (PRO) | | getDailyAvgBlockTime | Daily avg block time (PRO) | | getDailyAvgGasPrice | Daily avg gas price (PRO) | | getDailyGasUsed | Daily gas used (PRO) | | getDailyNetUtilization | Daily network utilization (PRO) | | getDailyNewAddress | Daily new addresses (PRO) | | getDailyTxCount | Daily transaction count (PRO) | | getDailyTxFee | Daily transaction fees (PRO) |

proxy

| Method | Description | |---|---| | ethBlockNumber | Latest block number | | ethCall | Read-only contract call | | ethEstimateGas | Gas estimation | | ethGasPrice | Current gas price | | ethGetBlockByNumber | Block by number | | ethGetBlockTransactionCountByNumber | Tx count in block | | ethGetCode | Contract bytecode | | ethGetStorageAt | Storage slot value | | ethGetTransactionByHash | Transaction by hash | | ethGetTransactionByBlockNumberAndIndex | Tx by block & index | | ethGetTransactionCount | Address nonce | | ethGetTransactionReceipt | Transaction receipt | | ethSendRawTransaction | Broadcast signed tx |

gasTracker

| Method | Description | |---|---| | gasEstimate | Confirmation time estimate | | gasOracle | Safe/Proposed/Fast gas prices |

nametag

| Method | Description | |---|---| | getAddressTag | Name tag & labels (Pro Plus) |

Supported Chains

Use the ChainId constant for type-safe chain selection:

ChainId.ETHEREUM     // 1
ChainId.POLYGON      // 137
ChainId.BASE         // 8453
ChainId.ARBITRUM     // 42161
ChainId.OPTIMISM     // 10
ChainId.BNB          // 56
ChainId.AVALANCHE    // 43114
ChainId.LINEA        // 59144
ChainId.BLAST        // 81457
ChainId.SCROLL       // 534352
ChainId.ZKSYNC       // 324
// ... and 30+ more (see src/chains.ts)

Error Handling

import { EtherscanError, RateLimitError, InvalidApiKeyError } from "@n4mchun/etherscan-sdk";

try {
  const balance = await client.account.getBalance({ address: "0x..." });
} catch (err) {
  if (err instanceof RateLimitError) {
    // Back off and retry
  } else if (err instanceof InvalidApiKeyError) {
    // Check your API key
  } else if (err instanceof EtherscanError) {
    console.error(err.message, err.apiMessage);
  }
}

License

MIT