# etherproxy

> A caching JSON-RPC proxy for Ethereum nodes. Sits in front of a node, deduplicates and caches identical requests for a configurable TTL, and forwards uncached ones upstream.

Latest version **1.6.0** (published 2026-05-25) · ISC license · 0 weekly downloads

## Install

```sh
npm install etherproxy
pnpm add etherproxy
yarn add etherproxy
bun add etherproxy
```

Provides the command `etherproxy`.

## Health

**Score 45/100 (D)** — status: active.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 1.6.0 |
| Published | 2026-05-25 |
| First published | 2023-04-04 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 15 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | cafe137 |

## Links

- npm: https://www.npmjs.com/package/etherproxy
- npm.io page: https://npm.io/package/etherproxy

## Dependencies (1)

- [cafe-utility](https://npm.io/package/cafe-utility.md) ^33.11.0

## Recent versions

- 1.6.0 (latest) — 2026-05-25
- 1.5.0 — 2026-05-25
- 1.4.0 — 2023-10-31
- 1.4.0-beta — 2023-10-31
- 1.3.0 — 2023-08-01
- 1.2.0 — 2023-07-31
- 1.1.0 — 2023-07-27
- 1.0.0 — 2023-04-04

## README

# Etherproxy

A caching JSON-RPC proxy for Ethereum nodes. Sits in front of a node, deduplicates and caches identical requests for a configurable TTL, and forwards uncached ones upstream.

## How it works

- Accepts HTTP POST JSON-RPC requests
- Normalizes request IDs and uses method + params as the cache key (id is excluded)
- Serves cached responses without hitting the upstream node until TTL expires
- Sends a Telegram alert on errors (throttled to once per 30 seconds)

## Install & build

```sh
pnpm install
pnpm build
pnpm test
```

## Usage

```sh
node dist/index.js \
  --hostname 0.0.0.0 \
  --port 8545 \
  --target http://localhost:8546 \
  --ttl 60 \
  --timeout 30
```

### Required arguments

| Argument     | Description                          |
|--------------|--------------------------------------|
| `--hostname` | Interface to bind                    |
| `--port`     | Port to listen on                    |
| `--target`   | Upstream JSON-RPC URL                |
| `--ttl`      | Cache TTL in seconds                 |
| `--timeout`  | Upstream request timeout in seconds  |

### Optional arguments

| Argument              | Env var            | Description                          |
|-----------------------|--------------------|--------------------------------------|
| `--max-body-size`     | `MAX_BODY_SIZE`    | Max request body in bytes (default 1 MB) |
| `--telegram-token`    | `TELEGRAM_TOKEN`   | Bot token for error alerts           |
| `--telegram-chat-id`  | `TELEGRAM_CHAT_ID` | Chat ID for error alerts             |
| `--telegram-name`     | `TELEGRAM_NAME`    | Label prepended to alerts (e.g. node hostname) |
| `--verbose`           |                    | Log every request and response       |
| `--record`            |                    | Write timestamped log file to disk   |
| `--metrics`           |                    | Write `etherproxy-metrics-<timestamp>.json` every 15 minutes |
| `--management-port`   |                    | Start a management server on `127.0.0.1:<port>` (see below) |

## Management API

When `--management-port` is set, a second HTTP server binds exclusively to `127.0.0.1` on that port and exposes a single endpoint for live reconfiguration:

### `PUT /target`

Change the upstream JSON-RPC URL without restarting.

```sh
curl -X PUT http://127.0.0.1:9000/target -d 'http://backup-node:8546'
```

The response body confirms the new target. The change takes effect immediately for all subsequent cache misses.

## Structure

| File | Role |
|------|------|
| `src/proxy.ts` | Core proxy logic — `createProxy(config)` returns an HTTP server |
| `src/index.ts` | CLI entry point — parses args, sets up logging, calls `createProxy` |
| `test/proxy.test.ts` | Integration tests (Vitest) |

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