npm package: @n4mchun/etherscan-sdk
Description: Type-safe TypeScript SDK for Etherscan V2 API with multichain support
Author: n4mchun
Latest version: 0.1.0

# @n4mchun/etherscan-sdk

Type-safe TypeScript SDK for the [Etherscan V2 API](https://docs.etherscan.io/etherscan-v2) 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

```bash
npm install @n4mchun/etherscan-sdk
```

## Quick Start

```typescript
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

```typescript
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:

```typescript
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

```typescript
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