RPC Service

The Erigon RPC Service: Enabling JSON-RPC, Transports (HTTP/WS/gRPC), and API Namespaces

The Erigon RPC Service, managed by Erigon's modular RPC daemon, supports various API namespaces, which can be enabled or disabled using the --http.api flag. The available namespaces include:

• eth: Standard Ethereum API.

• erigon: Erigon-specific extensions.

• engine: The JSON-RPC Interface for Execution and Consensus Layer Communication.

• web3: Web3 compatibility API.

• net: Network information API.

• debug: Debugging and tracing API.

• trace: Transaction tracing API.

• txpool: Transaction pool API.

• admin: Node administration API

• bor: Polygon Bor-specific API (when running on Polygon)

• ots: These methods are specifically tailored for use with Otterscan, an open-source, fast block explorer.

• internal: Erigon specific API for development and debugging purposes.

• gRPC: API for lower-level data access.

For a complete reference on the standard Ethereum JSON-RPC methods, especially those in the eth, net, and web3 namespaces, it is recommended to consult the general documentation on ethereum.org's JSON-RPC API page. Additionally, for the formal specification of the debug, engine, and eth namespaces, including unique, detailed descriptions for methods like eth_getProof and eth_simulateV1, refer to the Execution APIs documentation.

JSON-RPC API | ethereum.orgethereum.org

https://ethereum.github.io/execution-apis/api-documentation/ethereum.github.io

Erigon RPC Transports

Erigon supports HTTP, HTTPS, WebSockets, IPC, gRPC and GraphQL through its RPC daemon.

HTTP

Using the HTTP transport, clients send a request to the server and immediately get a response back. The connection is closed after the response for a given request is sent.

Because HTTP is unidirectional, subscriptions are not supported.

To start an HTTP server, you can either run Erigon with built-in RPC or use the separate rpcdaemon:

# Built-in RPC (default)
erigon --http

# Or separate RPC daemon
rpcdaemon --http.enabled

The default port is 8545, and the default listen address is localhost. node/nodecfg/defaults.go:30-31

You can configure the listen address and port using --http.addr and --http.port respectively:

erigon --http --http.addr 127.0.0.1 --http.port 12345
# Or with rpcdaemon
rpcdaemon --http.addr 127.0.0.1 --http.port 12345

To enable JSON-RPC namespaces on the HTTP server, pass each namespace separated by a comma to --http.api:

erigon --http --http.api eth,net,debug,trace
# Or with rpcdaemon
rpcdaemon --http.api eth,net,debug,trace

The default APIs enabled are eth and erigon. Available namespaces include: admin, debug, eth, erigon, net, trace, txpool, web3, bor (Polygon only), and internal.

You can also restrict who can access the HTTP server by specifying domains for Cross-Origin requests using --http.corsdomain:

erigon --http --http.corsdomain https://mycoolapp.com

Alternatively, if you want to allow any domain, you can pass *:

erigon --http --http.corsdomain "*"

HTTPS

Erigon supports HTTPS and HTTP/2 out of the box:

rpcdaemon --https.enabled --https.cert /path/to/cert.pem --https.key /path/to/key.pem

WebSockets

WebSockets is a bidirectional transport protocol. Most modern browsers support WebSockets.

A WebSocket connection is maintained until it is explicitly terminated by either the client or the node.

Because WebSockets are bidirectional, nodes can push events to clients, which enables clients to subscribe to specific events, such as new transactions in the transaction pool, and new logs for smart contracts.

The configuration of the WebSocket server follows the same pattern as the HTTP server:

• Enable it using --ws

• Configure the server port by passing --ws.port (default 8546) node/nodecfg/defaults.go:34

• Configure cross-origin requests using --ws.origins (though this maps to --http.corsdomain in Erigon)

• WebSocket APIs inherit from the HTTP API configuration

erigon --http --ws --http.api eth,net,debug,trace

IPC

IPC is a simpler transport protocol for use in local environments where the node and the client exist on the same machine.

Note: IPC is only available through the separate rpcdaemon process, not the main erigon binary. Erigon uses a modular architecture where RPC functionality is handled by a standalone daemon.

Enabling IPC with rpcdaemon

First, start Erigon with the private API enabled:

erigon --datadir=<path-to-datadir> --private.api.addr=localhost:9090

Then, in a separate terminal, start rpcdaemon with IPC enabled:

rpcdaemon --private.api.addr=localhost:9090 --socket.enabled --socket.url unix:///<path-to-datadir>/erigon.ipc

Important: Make sure you have write permissions to the directory where the socket will be created.

On Linux and macOS, Erigon uses UNIX sockets. On Windows, IPC is provided using named pipes (use \\.\pipe\erigon.ipc format). The socket inherits the API namespaces from the --http.api flag passed to rpcdaemon:

rpcdaemon --private.api.addr=localhost:9090 --socket.enabled --socket.url unix:///<path-to-datadir>/erigon.ipc --http.api eth,net,web3,debug,trace

TCP Socket Alternative (Advanced)

You can also serve the raw JSON-RPC2 protocol over TCP instead of Unix sockets:

rpcdaemon --private.api.addr=localhost:9090 --socket.enabled --socket.url tcp://127.0.0.1:8546

Note: This creates a raw JSON-RPC2 socket without HTTP wrapping. Most users should use the HTTP endpoint (enabled by default on port 8545) instead. The TCP socket is for specialized clients that support raw JSON-RPC2 protocol.

Testing IPC Connection

Test your IPC connection using curl:

curl --unix-socket <path-to-datadir>/erigon.ipc \
     -X POST http://localhost/ \
     -H "Content-Type: application/json" \
     --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Or use the HTTP endpoint (enabled by default on port 8545):

curl http://127.0.0.1:8545 \
     -X POST \
     -H "Content-Type: application/json" \
     --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

gRPC

Erigon also supports gRPC for high-performance access to blockchain data:

rpcdaemon --grpc --grpc.addr localhost --grpc.port 9090

GraphQL

Erigon uses the standard GraphQL documented by Geth at https://geth.ethereum.org/docs/interacting-with-geth/rpc/graphql.

Interacting with the RPC

You can easily interact with these APIs using curl, a programming language with a low-level library, or tools like Foundry to interact with the chain at the exposed HTTP or WebSocket port.

To enable all APIs using an HTTP transport:

erigon --http --http.api "admin,debug,eth,erigon,net,trace,txpool,web3"

This allows you to then call:

curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' localhost:8545

# With cast (if using Foundry)
cast block-number
cast rpc admin_nodeInfo  
cast rpc debug_traceTransaction <tx_hash>
cast rpc erigon_forks