Package Exports

etherscan-sdk
etherscan-sdk/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (etherscan-sdk) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Etherscan SDK

A comprehensive TypeScript SDK for the Etherscan API that works in both Node.js and browser environments.

Features

Complete coverage of all Etherscan API modules and endpoints
TypeScript support with full type definitions
Works in both Node.js and browser environments
Zero dependencies
Promise-based API

Installation

npm install etherscan-sdk
# or
yarn add etherscan-sdk

Quick Start

import { EtherscanSDK } from 'etherscan-sdk';

// Initialize with your Etherscan API key
const etherscan = new EtherscanSDK({
  apiKey: 'YOUR_ETHERSCAN_API_KEY',
  network: 'mainnet' // Optional: defaults to mainnet
});

// Example: Get ETH balance for an address
async function getBalance() {
  try {
    const balance = await etherscan.accounts.getBalance({
      address: '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
    });
    console.log('Balance:', balance);
  } catch (error) {
    console.error('Error:', error);
  }
}

getBalance();

Supported Networks

Ethereum Mainnet (mainnet)
Goerli Testnet (goerli)
Sepolia Testnet (sepolia)

Modules

The SDK is organized into modules that correspond to Etherscan's API categories:

accounts: Account-related operations
contracts: Smart contract related operations
transactions: Transaction-related operations
blocks: Block-related operations
logs: Event logs operations
proxy: Proxy methods for web3 compatibility
tokens: Token-related operations
gas: Gas tracker operations
stats: Stats and metrics

Examples

Account Module

// Get ETH balance for an address
const balance = await etherscan.accounts.getBalance({
  address: '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
});

// Get list of transactions for an address
const txList = await etherscan.accounts.getTransactions({
  address: '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae',
  startBlock: 0,
  endBlock: 99999999,
  page: 1,
  offset: 10,
  sort: 'asc'
});

Contract Module

// Get contract ABI
const abi = await etherscan.contracts.getAbi({
  address: '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
});

// Get contract source code
const sourceCode = await etherscan.contracts.getSourceCode({
  address: '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
});

Token Module

// Get ERC-20 token balance
const tokenBalance = await etherscan.tokens.getTokenBalance({
  contractAddress: '0x57d90b64a1a57749b0f932f1a3395792e12e7055',
  address: '0xe04f27eb70e025b78871a2ad7eabe85e61212761'
});

Configuration Options

You can configure the SDK with the following options:

const etherscan = new EtherscanSDK({
  apiKey: 'YOUR_ETHERSCAN_API_KEY',   // Required
  network: 'mainnet',                 // Optional: defaults to mainnet
  timeout: 10000,                     // Optional: request timeout in ms (default: 30000)
  rateLimitEnabled: true,             // Optional: enable rate limiting (default: true)
  maxRequestsPerSecond: 5             // Optional: max requests per second (default: 5)
});

Error Handling

The SDK throws errors with descriptive messages for API errors, network issues, or validation errors:

try {
  const balance = await etherscan.accounts.getBalance({
    address: '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
  });
  console.log('Balance:', balance);
} catch (error) {
  if (error instanceof EtherscanSDK.APIError) {
    console.error('API Error:', error.message, error.code);
  } else if (error instanceof EtherscanSDK.ValidationError) {
    console.error('Validation Error:', error.message);
  } else {
    console.error('Unexpected Error:', error);
  }
}

License

MIT