Skip to main content
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

VariableRequiredDescription
HEDERA_NETWORKyesmainnet, testnet, previewnet, or an IP map for a custom network.
CHAIN_IDyesHex-encoded chain ID. 0x127 (mainnet, 295), 0x128 (testnet, 296), 0x129 (previewnet, 297), 0x12a (local node, 298).
MIRROR_NODE_URLyesBase URL of the mirror node REST API the relay reads from. Defaults to "" (must be set).

​
Operator account

VariableRequiredDescription
OPERATOR_ID_MAINyesHedera account ID that pays for relay-issued transactions (e.g. 0.0.1234).
OPERATOR_KEY_MAINyesOperator private key in the format specified by OPERATOR_KEY_FORMAT. Keep secret.
OPERATOR_KEY_FORMATnoOne 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

VariableDefaultDescription
SERVER_PORT7546TCP 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.
VariableDefaultDescription
RATE_LIMIT_DISABLEDtrueWhen true, IP-based rate limiting is off. Set to false to enforce the tier limits below.
TIER_1_RATE_LIMIT100Max request count per LIMIT_DURATION for the most expensive endpoints.
TIER_2_RATE_LIMIT800Max request count per LIMIT_DURATION for moderate-cost endpoints.
TIER_3_RATE_LIMIT1600Max request count per LIMIT_DURATION for cheap static-return endpoints.
LIMIT_DURATION60000Window length in milliseconds.
DEFAULT_RATE_LIMIT200Fallback 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.
VariableDefaultDescription
CACHE_MAX1000Maximum number of items the in-memory cache will hold before evicting.
CACHE_TTL3600000Default cache TTL in milliseconds (1 hour).
MIRROR_NODE_LIMIT_PARAM100Max 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.

​
See also

Setup

Initial install and Docker Compose bring-up.