JSON-RPC Configuration

The relay is configured through environment variables, typically supplied via a .env file at the project root or set directly in the container runtime. The variables below cover the ones you’re most likely to need. The relay supports well over a hundred variables in total; for the complete list with defaults, see docs/configuration.md in the repo.

Network selection

Variable	Required	Description
`HEDERA_NETWORK`	yes	`mainnet`, `testnet`, `previewnet`, or an IP map for a custom network.
`CHAIN_ID`	yes	Hex-encoded chain ID. `0x127` (mainnet, 295), `0x128` (testnet, 296), `0x129` (previewnet, 297), `0x12a` (local node, 298).
`MIRROR_NODE_URL`	yes	Base URL of the mirror node REST API the relay reads from. Defaults to `""` (must be set).

Operator account

Variable	Required	Description
`OPERATOR_ID_MAIN`	yes	Hedera account ID that pays for relay-issued transactions (e.g. `0.0.1234`).
`OPERATOR_KEY_MAIN`	yes	Operator private key in the format specified by `OPERATOR_KEY_FORMAT`. Keep secret.
`OPERATOR_KEY_FORMAT`	no	One of `DER`, `HEX_ECDSA`, `HEX_ED25519`. Defaults to `DER`.

The operator account pays for the relay’s submitted transactions. It does not need a large balance unless you’re serving high write volume.

Listening interface

Variable	Default	Description
`SERVER_PORT`	`7546`	TCP port the HTTP JSON-RPC server listens on.

For the WebSocket server, use the .env.ws.example template; it ships with its own port and host settings on port 8546 by default.

Rate limiting

IP-based rate limiting is disabled by default. Set RATE_LIMIT_DISABLED=false to turn it on; the relay then applies three tiers, each covering a different cost class of method.

Variable	Default	Description
`RATE_LIMIT_DISABLED`	`true`	When `true`, IP-based rate limiting is off. Set to `false` to enforce the tier limits below.
`TIER_1_RATE_LIMIT`	`100`	Max request count per `LIMIT_DURATION` for the most expensive endpoints.
`TIER_2_RATE_LIMIT`	`800`	Max request count per `LIMIT_DURATION` for moderate-cost endpoints.
`TIER_3_RATE_LIMIT`	`1600`	Max request count per `LIMIT_DURATION` for cheap static-return endpoints.
`LIMIT_DURATION`	`60000`	Window length in milliseconds.
`DEFAULT_RATE_LIMIT`	`200`	Fallback request limit for methods not assigned a specific tier.

Tune these based on traffic and how much operator HBAR you’re willing to spend on writes.

Caching

The relay caches mirror node responses to absorb burst read traffic.

Variable	Default	Description
`CACHE_MAX`	`1000`	Maximum number of items the in-memory cache will hold before evicting.
`CACHE_TTL`	`3600000`	Default cache TTL in milliseconds (1 hour).
`MIRROR_NODE_LIMIT_PARAM`	`100`	Max page size when paginating mirror node lists.

For Redis-backed caching across multiple relay instances, see the REDIS_* variables in the repo’s reference table.

Sanity-check a configuration

After editing variables, restart the relay and confirm chain ID and a simple read both work:

docker compose restart
sleep 5

# 1. Chain ID matches your CHAIN_ID setting
curl -s -X POST http://localhost:7546 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}'

# 2. A balance read against a known account (replace EVM address)
curl -s -X POST http://localhost:7546 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"eth_getBalance","params":["0x0000000000000000000000000000000000000002","latest"]}'

If both return non-error JSON, the relay is reading from the mirror node correctly.

Setup

Initial install and Docker Compose bring-up.

​Network selection

​Operator account

​Listening interface

​Rate limiting

​Caching

​Sanity-check a configuration

​See also