canonical: https://jentic.com/apis/ethereum.org/ethereum

# Ethereum JSON-RPC API

Jentic publishes the only available OpenAPI specification for Ethereum JSON-RPC API, keeping it validated and agent-ready. The Ethereum JSON-RPC API is the standard interface for talking to an Ethereum execution client - Geth, Erigon, Nethermind, Reth, or a hosted node provider such as Infura or Alchemy. All node functionality (querying blocks, transactions, balances, calling contracts, broadcasting signed transactions) is invoked by POSTing a JSON-RPC 2.0 envelope to the node endpoint with a method name like eth_blockNumber, eth_getBalance, eth_call, or eth_sendRawTransaction.

## For AI agents

Talk to any Ethereum execution client over JSON-RPC 2.0 to read chain state, query transactions, call smart contracts, and broadcast signed transactions.

## Scope

Does not handle key custody, transaction signing, or off-chain indexing - use for JSON-RPC reads, eth_call, and eth_sendRawTransaction only.

## Capabilities

- Query the current block number, block contents, and chain ID from any Ethereum node
- Read account balances, transaction counts (nonce), and contract storage at a specific block
- Call read-only smart contract methods via eth_call without spending gas
- Estimate gas for a pending transaction with eth_estimateGas
- Broadcast a pre-signed transaction to the mempool via eth_sendRawTransaction
- Fetch transaction receipts and logs for indexing or webhook-style triggers
- Subscribe to new heads or pending transactions on JSON-RPC nodes that support filters

## Use cases

### Wallet balance and transaction history dashboard

A wallet UI assembles balances and recent activity by sending eth_blockNumber, eth_getBalance, and eth_getTransactionByHash JSON-RPC calls to the node URL. ERC-20 balances are read by encoding a balanceOf(address) call and POSTing it via eth_call. Because the JSON-RPC envelope is uniform, the same client speaks to any execution client.

Example prompt: POST {jsonrpc:2.0, method: eth_getBalance, params:[wallet_address, 'latest'], id:1} to / to fetch the wallet's ETH balance, then post an eth_call with the encoded balanceOf(address) data for each ERC-20 holding.

### Smart contract event indexer

Indexers replay a smart contract's history by calling eth_getLogs over chunked block ranges with the contract address and topic filter. Each batch returns the logs that match, which the indexer parses into a database to power dashboards or trigger downstream workflows. New blocks are caught up by polling eth_blockNumber or subscribing to newHeads on a WebSocket node.

Example prompt: POST eth_getLogs with fromBlock/toBlock chunks of 5000 and the Transfer topic filter for the target ERC-20 contract, then upsert each log into the indexer's transfers table.

### Programmatic transaction submission for a custodial wallet

A custodial wallet signs an Ethereum transaction off-chain and broadcasts it by POSTing eth_sendRawTransaction with the hex-encoded signed payload. The wallet then polls eth_getTransactionReceipt to confirm inclusion and bumps the nonce returned by eth_getTransactionCount before signing the next transaction. Gas is sized via eth_estimateGas to avoid underpricing.

Example prompt: POST eth_sendRawTransaction with the hex-encoded signed transaction, capture the returned hash, then POST eth_getTransactionReceipt(hash) until a non-null receipt is returned.

### AI agent answering on-chain questions over JSON-RPC

A research agent answers questions like 'what's the latest balance of vitalik.eth?' by resolving the ENS name off-chain, then posting eth_getBalance and eth_blockNumber JSON-RPC calls through Jentic. The node URL is held in your Jentic One instance, so the agent can be pointed at a private RPC provider without exposing the URL or any associated key.

Example prompt: Search Jentic for 'Ethereum JSON-RPC call', execute the operation with method eth_getBalance and the resolved address, then summarise the wei value as ETH.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | / | Make a JSON-RPC 2.0 call (eth_blockNumber, eth_getBalance, eth_call, eth_sendRawTransaction, eth_getLogs, etc.) |

## Key resources

- **JSON-RPC Endpoint** — Single POST endpoint accepting any JSON-RPC 2.0 method (eth_*, net_*, web3_*) supported by the connected execution client

## Why Jentic

- **Setup:** Wiring the Ethereum JSON-RPC API by hand means supplying your own node URL (often with an embedded provider key), packing method and params into the JSON-RPC envelope, and handling retries yourself. Through Jentic you install once, import the Ethereum JSON-RPC API from the API Directory, store the node URL once, and your agent calls it.
- **Permission scoping:** The Ethereum JSON-RPC API takes a single POST endpoint with the method carried in the request body, so scope the agent to that one operation. You control which JSON-RPC calls it issues, so a state-changing method like eth_sendRawTransaction is not used unless you add it.
- **Credential handling:** Your Ethereum node URL, including any embedded provider key, is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'get an ETH balance' or 'broadcast a signed transaction', and Jentic returns the JSON-RPC POST operation with its method and params schema so the agent calls the right endpoint without reading the execution-API spec by hand.

## Related APIs

- **Alchemy API** — Alchemy hosts Ethereum JSON-RPC nodes plus enhanced data APIs on top of the same protocol.
- **EtherDelta / ForkDelta API** — EtherDelta was a legacy DEX layered on top of Ethereum JSON-RPC; archived and not recommended for new builds.
- **Binance API** — Binance can settle off-chain trades whose results are mirrored on Ethereum via JSON-RPC.

## FAQ

### Why is there no official OpenAPI spec for Ethereum JSON-RPC API?

The Ethereum project does not publish an OpenAPI specification - the JSON-RPC interface is defined in the Ethereum execution-API standards rather than as an OpenAPI document. Jentic generates and maintains this spec so that AI agents and developers can call Ethereum JSON-RPC API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Ethereum JSON-RPC API use?

The Ethereum JSON-RPC standard itself does not define authentication; whether you need a key depends entirely on the node host. A self-run Geth/Erigon/Nethermind/Reth node is unauthenticated, while hosted providers such as Infura, Alchemy, or QuickNode require a project ID embedded in the node URL. Through Jentic, the node URL (and any embedded key) is held in the vault.

### Can I broadcast a signed transaction with this API?

Yes - POST a JSON-RPC envelope with method eth_sendRawTransaction and the hex-encoded signed transaction as the single param. The response contains the transaction hash, which you can then feed into eth_getTransactionReceipt to wait for confirmation.

### What are the rate limits for the Ethereum JSON-RPC API?

Limits depend on the node provider, not on Ethereum itself: a self-run node has no limits beyond hardware, while Infura, Alchemy, and similar set per-second compute-unit ceilings on free and paid tiers. Always check the chosen provider's pricing page and back off on HTTP 429 responses.

### How do I read an ERC-20 balance through Jentic?

Search Jentic for 'Ethereum JSON-RPC call'. Jentic returns POST /. Execute it with method 'eth_call', a 'to' field set to the ERC-20 contract address, and a 'data' field containing the ABI-encoded balanceOf(address) call. The response is the hex-encoded uint256 balance, which you decode client-side.

### Does this API support WebSocket subscriptions?

This OpenAPI document covers the HTTP JSON-RPC surface only. WebSocket subscriptions (eth_subscribe with newHeads or logs) are supported on most node providers but are out of scope for an HTTP OpenAPI spec; for those, connect directly to the provider's wss:// endpoint.

### Can I limit what my agent is allowed to do with the Ethereum JSON-RPC API?

Yes. Because you run Jentic One yourself, your own rules decide which JSON-RPC methods the agent may issue against the single POST endpoint that carries the method in the request body. You can keep the agent scoped to read-only calls such as eth_getBalance, eth_call, and eth_getLogs, so a state-changing method like eth_sendRawTransaction is never invoked unless you explicitly allow it. Your node URL and any embedded provider key stay in your own instance and are injected at execution time rather than exposed to the agent.