Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ethereum/go-ethereum/llms.txt

Use this file to discover all available pages before exploring further.

Geth implements the Ethereum JSON-RPC specification and exposes additional management APIs. Clients communicate with the node by sending JSON-encoded requests and receiving JSON-encoded responses.

​
Transports

Geth supports three transport mechanisms. Each must be explicitly enabled (except IPC, which is on by default).
HTTP is a stateless, request-response transport. It is the most common choice for dapps and tooling.
geth --http --http.port 8545 --http.api eth,net,web3
Additional flags:
FlagDescription
--http.addrInterface to listen on (default 127.0.0.1)
--http.portPort to listen on (default 8545)
--http.apiComma-separated list of API namespaces to expose
--http.corsdomainComma-separated list of allowed CORS origins
--http.vhostsComma-separated list of allowed virtual hostnames
Never expose the HTTP server on a public interface without restricting --http.api. The admin, debug, and miner namespaces grant significant control over the node.

​
API namespaces

Geth groups its methods into namespaces. Each namespace must be listed in the --http.api, --ws.api, or --authrpc.api flags to be accessible over the corresponding transport. All namespaces are always available over IPC.
NamespaceDescription
ethCore Ethereum API: blocks, transactions, accounts, state, filters
netNetwork information: peer count, listening status, network ID
web3Utility methods: unit conversion, hashing
txpoolTransaction pool inspection: pending and queued transactions
debugLow-level debugging: tracing, state dumps, profiling
adminNode management: peer management, chain export, server control
minerMining control: start/stop, gas price, coinbase (PoW networks only)

​
Example requests

The examples below use curl to send requests to an HTTP endpoint. All requests follow the JSON-RPC 2.0 format. 
curl -X POST http://localhost:8545 \
  -H 'Content-Type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_blockNumber",
    "params": [],
    "id": 1
  }'
Example response for eth_blockNumber: 
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x1388"
}
Block numbers and other integer values are returned as 0x-prefixed hex strings.

​
Engine API and JWT authentication

The Engine API is a separate authenticated endpoint used by the consensus layer client (e.g. Prysm, Lighthouse) to drive block production after the Merge. Enable it with a JWT secret file: 
geth --authrpc.jwtsecret /path/to/jwt.hex \
     --authrpc.addr localhost \
     --authrpc.port 8551 \
     --authrpc.vhosts localhost
Generate a JWT secret if you do not have one: 
openssl rand -hex 32 > /path/to/jwt.hex
All requests to the Engine API must include a Authorization: Bearer <token> header. The token is a signed JWT that uses the HS256 algorithm with the shared secret and must contain an iat (issued-at) claim within 60 seconds of the current time.
Both Geth and your consensus client must be configured with the same JWT secret file. Mismatched secrets are the most common cause of Geth failing to follow the chain head after the Merge.

​
WebSocket subscriptions

WebSocket connections support eth_subscribe, which pushes events to the client as they occur rather than requiring polling. 
// Subscribe to new block headers
{"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["newHeads"]}

// Subscribe to logs matching a filter
{"jsonrpc":"2.0","id":2,"method":"eth_subscribe","params":["logs",{"address":"0xContractAddress","topics":[]}]}

// Subscribe to new pending transactions (hash only)
{"jsonrpc":"2.0","id":3,"method":"eth_subscribe","params":["newPendingTransactions"]}
The server responds with a subscription ID: 
{"jsonrpc":"2.0","id":1,"result":"0x9cef478923ff08bf67fde6c64013158d"}
Subsequent events arrive as notifications: 
{
  "jsonrpc": "2.0",
  "method": "eth_subscription",
  "params": {
    "subscription": "0x9cef478923ff08bf67fde6c64013158d",
    "result": {
      "number": "0x1b4",
      "hash": "0x..."
    }
  }
}
Cancel a subscription with eth_unsubscribe: 
{"jsonrpc":"2.0","id":4,"method":"eth_unsubscribe","params":["0x9cef478923ff08bf67fde6c64013158d"]}
Subscription typeDescription
newHeadsNew block headers as they are added to the chain
logsLog entries matching an optional address and topics filter
newPendingTransactionsTransaction hashes as they enter the transaction pool
syncingNode sync status changes
Subscriptions are only supported over WebSocket and IPC connections. HTTP connections receive an error if eth_subscribe is called.

Build docs developers (and LLMs) love

Get started for freeTalk to us