JSON-RPC Setup

Install and run the Hiero JSON-RPC Relay locally or in a container orchestrator.

This page walks through getting the Hiero JSON-RPC Relay running. For an overview of what the relay is and when you’d want to self-host, see the JSON-RPC Relay overview.

Prerequisites

• Docker 20.10+ and Docker Compose
• A Hedera account on the network you’re targeting (mainnet, testnet, or previewnet) with HBAR to pay for the relay’s internal transactions
• The account’s ECDSA or ED25519 private key in a format the relay supports (DER, HEX_ECDSA, or HEX_ED25519 set via OPERATOR_KEY_FORMAT)

You also need access to a mirror node REST endpoint for the same network. The public Hedera-hosted mirror nodes work fine for getting started:

Network	Mirror node base URL
Mainnet	https://mainnet.mirrornode.hedera.com
Testnet	https://testnet.mirrornode.hedera.com
Previewnet	https://previewnet.mirrornode.hedera.com

Run with Docker Compose

Clone the repo and copy the HTTP example env file:

git clone https://github.com/hiero-ledger/hiero-json-rpc-relay.git
cd hiero-json-rpc-relay
cp .env.http.example .env

The repo ships two env templates: .env.http.example for the JSON-RPC HTTP server (what you usually want) and .env.ws.example for the WebSocket server. Pick the one that matches the workload, or run both.

Edit .env and set the minimum required values:

HEDERA_NETWORK=testnet
CHAIN_ID=0x128                                      # 296 in hex (testnet)
MIRROR_NODE_URL=https://testnet.mirrornode.hedera.com
OPERATOR_ID_MAIN=0.0.1234
OPERATOR_KEY_MAIN=302d300706052b8104000a0322000334...
OPERATOR_KEY_FORMAT=DER

Then bring it up:

docker compose up -d

By default the relay listens on port 7546 for HTTP and 8546 for WebSocket. Verify HTTP with a chain-ID call:

curl -X POST http://localhost:7546 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":"1","method":"eth_chainId","params":[null]}'

Expected response:

{"jsonrpc":"2.0","id":"1","result":"0x128"}

0x128 is 296 in hex, which is Hedera testnet. If you see that, the relay is up and pointed at the right network.

Connect MetaMask or Hardhat

Point your tooling at the relay’s URL and the matching chain ID. For a self-hosted relay against testnet:

Field	Value
RPC URL	http://<your-host>:7546
Chain ID	296
Currency symbol	HBAR
Block explorer	https://hashscan.io/testnet

For the full per-EVM-tool wiring, see the setup guides under EVM Developers.

Next

Configuration

Tune chain ID, mirror node URL, rate limits, caching, and logging.