# etherscan-api

> API to etherscan with a simple interface (Etherscan V2, multichain)

Latest version **12.1.0** (published 2026-09-20) · MIT license · 0 weekly downloads

## Install

```sh
npm install etherscan-api
pnpm add etherscan-api
yarn add etherscan-api
bun add etherscan-api
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 12.1.0 |
| Published | 2026-09-20 |
| First published | 2016-10-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20 |
| Dependencies | 0 |
| Unpacked size | 88.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 551 |
| Author | Sebastian Schürmann |
| Maintainers | sebs |
| Keywords | arbiscan, ethereum, EtherScan.io, etherscan, blockchain, api, transaction, rest |

## Links

- npm: https://www.npmjs.com/package/etherscan-api
- Repository: https://github.com/sebs/etherscan-api
- Homepage: https://github.com/sebs/etherscan-api#readme
- Issues: https://github.com/sebs/etherscan-api/issues
- Funding: https://github.com/sponsors/sebs
- npm.io page: https://npm.io/package/etherscan-api

## Alternatives

- [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads
- [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads
- [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads
- [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads
- [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads

## Recent versions

- 12.1.0 (latest) — 2026-09-20
- 12.0.5 — 2026-09-20
- 12.0.3 — 2026-07-02
- 12.0.2 — 2026-06-28
- 12.0.1 — 2026-06-03
- 10.3.0 — 2023-01-07
- 10.2.2 — 2023-01-07
- 10.2.1 — 2023-01-06
- 10.2.0 — 2022-07-03
- 10.1.0 — 2022-06-26
- 10.0.9 — 2022-05-28
- 10.0.8 — 2022-05-28
- 10.0.6 — 2022-05-28
- 100.0.0 — 2019-09-30
- 10.0.5 — 2019-09-10
- … 61 more at https://npm.io/package/etherscan-api/versions

## README

# Etherscan API

[![npm](https://img.shields.io/npm/dt/etherscan-api.svg)](https://www.npmjs.com/package/etherscan-api)
[![license](https://img.shields.io/github/license/sebs/etherscan-api.svg)](https://github.com/sebs/etherscan-api/blob/master/LICENSE.md)
[![GitHub tag](https://img.shields.io/github/tag/sebs/etherscan-api.svg)](https://github.com/sebs/etherscan-api)
[![GitHub issues](https://img.shields.io/github/issues/sebs/etherscan-api.svg)](https://github.com/sebs/etherscan-api/issues)

A way to access the [etherscan.io api](https://etherscan.io/apis) using promises. Fetch a diverse set of information about the blockchain.

Written in TypeScript, shipped as an **ES module** with bundled type declarations. Requires Node.js >= 20.

Mainnet


```javascript
import { init } from 'etherscan-api';

const api = init('YourApiKey');
const balance = await api.account.balance('0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae');
console.log(balance);
```

## Example in the wild

* [Polymer3 based example](https://github.com/hiherto-elements/test-app)


## Zero dependencies / custom HTTP transport

This library has **no runtime dependencies** — requests use Node's built-in
`https` module. If you need custom networking (a proxy, retries, a different
agent), pass your own transport as the 4th argument to `init`. It receives the
fully-qualified URL and must resolve with the parsed JSON body:

```js
import { init } from 'etherscan-api';

// (url, { timeout, method, body }) => Promise<object>
// `method`/`body` are only set for the POST contract-verification endpoints;
// for read-only use you can ignore them.
async function request(url, { timeout, method = 'GET', body }) {
  const res = await fetch(url, {
    method,
    body,
    headers: body ? { 'Content-Type': 'application/x-www-form-urlencoded' } : undefined,
    signal: AbortSignal.timeout(timeout),
  });
  return res.json();
}

const api = init('apikey', null, 10000, request);
```

## Security notes

* **The API key travels in the request URL on GET requests.** Etherscan requires
  `apikey` as a query parameter, so it is part of every GET request URL. Treat
  full request URLs as secrets: **do not log them**, and be careful with
  proxies, APM tools, and access logs that capture URLs. A custom transport
  receives the URL containing the key — never write it to logs verbatim. (The
  library itself never puts the URL or key into thrown errors.)
  The POST contract-verification endpoints are the exception: there the key is
  sent in the form body and the URL is a bare `/v2/api`.
* **The default transport refuses cleartext `http://`.** Requests go to
  `https://api.etherscan.io` over TLS with certificate validation on. If a
  request somehow targets an `http://` URL, the default transport rejects rather
  than sending the key unencrypted; pass `{ allowInsecure: true }` in the
  transport options only if you deliberately need cleartext (e.g. a local test
  server).
* **The default transport caps the response body at 50 MB** to guard against a
  memory-exhaustion response. Override with `maxResponseBytes` in the transport
  options if you expect larger payloads.

### Overriding the transport options

`init` only ever passes `timeout` to the transport, so `allowInsecure` and
`maxResponseBytes` are set by wrapping the default transport, which is exported
as `httpTransport`:

```js
import { init, httpTransport } from 'etherscan-api';

const api = init('apikey', 'mainnet', 10000, (url, options) =>
  httpTransport(url, { ...options, maxResponseBytes: 200 * 1024 * 1024 }));
```

## Selecting a chain (Etherscan V2 / multichain)

Etherscan deprecated the V1 API on 2025-08-15. This library now talks to a
single base URL — `https://api.etherscan.io/v2/api` — and selects the network
with a `chainid` query parameter. **One API key works across all chains.**

Pass a chain name (or a numeric chainid) as the second argument to `init`:

```javascript
import { init } from 'etherscan-api';

// apikey, chain, timeout
const api = init('YourApiKey', 'sepolia', 3000);
```

Supported chain names:

| Name                                | chainid    |
| ----------------------------------- | ---------- |
| `mainnet` / `homestead` / `ethereum`| 1          |
| `sepolia`                           | 11155111   |
| `holesky`                           | 17000      |
| `arbitrum`                          | 42161      |
| `optimism`                          | 10         |
| `base`                              | 8453       |
| `polygon`                           | 137        |
| `bsc`                               | 56         |
| `avalanche`                         | 43114      |

Any other chain is reachable by passing its numeric chainid directly, e.g.
`init('YourApiKey', 59144)` for Linea.

Retired testnets (`ropsten`, `rinkeby`, `kovan`, `goerli`, `morden`,
`arbitrum_rinkeby`, `avalanche_fuji`) have been removed and now **throw** an
error with a helpful message — use `sepolia` or `holesky` instead.

## Install

 ```bash
 npm install etherscan-api --save
 ```


## API Documentation

[Full Api Docs](https://sebs.github.io/etherscan-api/)


## Development workflow

Source lives in `./src` (TypeScript) and compiles to `./lib` (ES modules + `.d.ts`).

* `npm run build` - compiles `src` → `lib` with `tsc`
* `npm run typecheck` - type-checks without emitting (replaces the old linter)
* `npm test` - builds, then runs the fully mocked test suite (no API key required)
* `npm run docs` - generates the API docs with TypeDoc
* `npm run preversion` - type-check + changelog before tagging a release
* `npm run changelog` - generates a changelog and pushes it

## Sponsors

This library is maintained in my spare time. If your company relies on it,
consider sponsoring — it directly funds maintenance and new features.
Sponsors at $50/month or more get their logo placed here.

<!-- sponsors -->
_No sponsors yet — [be the first](https://github.com/sponsors/sebs)_
<!-- /sponsors -->

---
_Source: https://npm.io/package/etherscan-api · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._