> ## Documentation Index
> Fetch the complete documentation index at: https://docs.optimism.io/llms.txt
> Use this file to discover all available pages before exploring further.

# op-geth JSON-RPC API

> Complete reference for op-geth execution client RPC methods with OP Stack enhancements.

`op-geth` is the execution client for the OP Stack, based on Go Ethereum (Geth). It provides the execution layer with Ethereum-equivalent functionality plus OP Stack-specific enhancements for L2 gas accounting and receipts.

## Overview

The `op-geth` execution client implements the standard Ethereum JSON-RPC API with minimal modifications. This means you can use familiar Ethereum tools and libraries with OP Stack chains.

<Info>
  The execution engine's RPC interface is identical to [the upstream Geth RPC interface](https://geth.ethereum.org/docs/interacting-with-geth/rpc). The key difference is that transaction receipts include additional L1 gas usage and pricing information specific to L2 operations.
</Info>

## Key Differences from Ethereum

While `op-geth` maintains compatibility with Ethereum's JSON-RPC API, there are important differences:

### Transaction Receipts

Transaction receipts in `op-geth` include additional L1 data fee information:

* **`l1GasUsed`**: Amount of L1 gas used for L1 data availability
* **`l1GasPrice`**: L1 gas price at the time of transaction execution
* **`l1Fee`**: Total L1 data fee charged (in wei)
* **`l1FeeScalar`**: Scalar value used in L1 fee calculation

This additional information helps you understand the full cost of L2 transactions, which include both L2 execution costs and L1 data availability costs.

### Gas Price Calculation

For L2 gas prices, use the standard [`eth_gasPrice`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_gasprice) method.

For L1 gas prices and fee estimation, use the [`GasPriceOracle`](https://explorer.optimism.io/address/0x420000000000000000000000000000000000000F) predeployed contract or [the Optimism SDK](/app-developers/tutorials/transactions/sdk-estimate-costs).

## Standard JSON-RPC Methods

`op-geth` supports all standard Ethereum JSON-RPC methods. Below are commonly used methods with examples.

### eth\_blockNumber

Returns the number of the most recent block.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
      '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
      http://localhost:8545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast block-number --rpc-url http://localhost:8545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x4b7"
}
```

### eth\_getBalance

Returns the balance of the account at the given address.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
      '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb","latest"],"id":1}' \
      http://localhost:8545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast balance 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb --rpc-url http://localhost:8545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x0234c8a3397aab58"
}
```

### eth\_getTransactionByHash

Returns information about a transaction by transaction hash.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
      '{"jsonrpc":"2.0","method":"eth_getTransactionByHash","params":["0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b"],"id":1}' \
      http://localhost:8545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast tx 0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b --rpc-url http://localhost:8545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "blockHash": "0x1d59ff54b1eb26b013ce3cb5fc9dab3705b415a67127a003c3e61eb445bb8df2",
    "blockNumber": "0x5daf3b",
    "from": "0xa7d9ddbe1f17865597fbd27ec712455208b6b76d",
    "gas": "0xc350",
    "gasPrice": "0x4a817c800",
    "hash": "0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b",
    "input": "0x68656c6c6f21",
    "nonce": "0x15",
    "to": "0xf02c1c8e6114b1dbe8937a39260b5b0a374432bb",
    "transactionIndex": "0x41",
    "value": "0xf3dbb76162000",
    "type": "0x0",
    "chainId": "0xa4b1",
    "v": "0x1546d71",
    "r": "0x8a8eafb3cf4c5c4c5c5e5c5e5c5e5c5e5c5e5c5e5c5e5c5e5c5e5c5e5c5e5c5e",
    "s": "0x8a8eafb3cf4c5c4c5c5e5c5e5c5e5c5e5c5e5c5e5c5e5c5e5c5e5c5e5c5e5c5e"
  }
}
```

### eth\_getTransactionReceipt

Returns the receipt of a transaction by transaction hash. This method includes OP Stack-specific L1 fee fields.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
      '{"jsonrpc":"2.0","method":"eth_getTransactionReceipt","params":["0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b"],"id":1}' \
      http://localhost:8545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast receipt 0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b --rpc-url http://localhost:8545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "blockHash": "0x1d59ff54b1eb26b013ce3cb5fc9dab3705b415a67127a003c3e61eb445bb8df2",
    "blockNumber": "0x5daf3b",
    "contractAddress": null,
    "cumulativeGasUsed": "0x33bc",
    "effectiveGasPrice": "0x4a817c800",
    "from": "0xa7d9ddbe1f17865597fbd27ec712455208b6b76d",
    "gasUsed": "0x4dc",
    "logs": [],
    "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
    "status": "0x1",
    "to": "0xf02c1c8e6114b1dbe8937a39260b5b0a374432bb",
    "transactionHash": "0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b",
    "transactionIndex": "0x41",
    "type": "0x0",
    "l1GasUsed": "0x5e0",
    "l1GasPrice": "0x3b9aca00",
    "l1Fee": "0x16a3f5b9c0",
    "l1FeeScalar": "1.0"
  }
}
```

<Info>
  Notice the additional fields at the end of the receipt: `l1GasUsed`, `l1GasPrice`, `l1Fee`, and `l1FeeScalar`. These fields are specific to OP Stack chains and provide information about L1 data availability costs.
</Info>

### eth\_call

Executes a new message call immediately without creating a transaction on the blockchain.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
      '{"jsonrpc":"2.0","method":"eth_call","params":[{"to":"0x420000000000000000000000000000000000000F","data":"0x519b4bd3"},"latest"],"id":1}' \
      http://localhost:8545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast call 0x420000000000000000000000000000000000000F "l1BaseFee()" --rpc-url http://localhost:8545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x00000000000000000000000000000000000000000000000000000003b9aca00"
}
```

### eth\_estimateGas

Generates and returns an estimate of gas needed for a transaction to complete.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
      '{"jsonrpc":"2.0","method":"eth_estimateGas","params":[{"from":"0x8D97689C9818892B700e27F316cc3E41e17fBeb9","to":"0xd3CdA913deB6f67967B99D67aCDFa1712C293601","value":"0xde0b6b3a7640000"}],"id":1}' \
      http://localhost:8545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast estimate 0xd3CdA913deB6f67967B99D67aCDFa1712C293601 --value 1ether --from 0x8D97689C9818892B700e27F316cc3E41e17fBeb9 --rpc-url http://localhost:8545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x5208"
}
```

<Warning>
  `eth_estimateGas` only estimates L2 execution gas. To calculate the total transaction cost including L1 data fees, use the [Optimism SDK](/app-developers/tutorials/transactions/sdk-estimate-costs) or query the [`GasPriceOracle` predeployed contract](https://explorer.optimism.io/address/0x420000000000000000000000000000000000000F).
</Warning>

### eth\_sendRawTransaction

Submits a signed transaction to the network.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
      '{"jsonrpc":"2.0","method":"eth_sendRawTransaction","params":["0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675"],"id":1}' \
      http://localhost:8545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast publish 0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675 --rpc-url http://localhost:8545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331"
}
```

### eth\_getBlockByNumber

Returns information about a block by block number.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
      '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["0x1b4",true],"id":1}' \
      http://localhost:8545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast block 0x1b4 --rpc-url http://localhost:8545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "difficulty": "0x0",
    "extraData": "0x",
    "gasLimit": "0x1c9c380",
    "gasUsed": "0x5208",
    "hash": "0x1d59ff54b1eb26b013ce3cb5fc9dab3705b415a67127a003c3e61eb445bb8df2",
    "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
    "miner": "0x4200000000000000000000000000000000000011",
    "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "nonce": "0x0000000000000000",
    "number": "0x1b4",
    "parentHash": "0x9b83c12c69edb74f6c8dd5d052765c1adf940e320bd1291696e6fa07829eee71",
    "receiptsRoot": "0x056b23fbba480696b65fe5a59b8f2148a1299103c4f57df839233af2cf4ca2d2",
    "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
    "size": "0x27f",
    "stateRoot": "0xd5855eb08b3387c0af375e9cdb6acfc05eb8f519e419b874b6ff2ffda7ed1dff",
    "timestamp": "0x54e34e8e",
    "totalDifficulty": "0x0",
    "transactions": [],
    "transactionsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
    "uncles": []
  }
}
```

### eth\_getLogs

Returns an array of all logs matching a given filter object.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
      '{"jsonrpc":"2.0","method":"eth_getLogs","params":[{"fromBlock":"0x1","toBlock":"0x2","address":"0x8320fe7702b96808f7bbc0d4a888ed1468216cfd"}],"id":1}' \
      http://localhost:8545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast logs --from-block 1 --to-block 2 --address 0x8320fe7702b96808f7bbc0d4a888ed1468216cfd --rpc-url http://localhost:8545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [{
    "address": "0x8320fe7702b96808f7bbc0d4a888ed1468216cfd",
    "topics": [
      "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
      "0x00000000000000000000000000000000000000000000000000000000000000fe",
      "0x000000000000000000000000a94f5374fce5edbc8e2a8697c15331677e6ebf0b"
    ],
    "data": "0x0000000000000000000000000000000000000000000000000000000000000001",
    "blockNumber": "0x1",
    "transactionHash": "0xab059a62e22e230fe0f56d8555340a29b2e9532360368f810595453f6fdd213b",
    "transactionIndex": "0x0",
    "blockHash": "0x8243343df08b9751f5ca0c5f8c9c0460d8a9b6351066fae0acbd4d3e776de8bb",
    "logIndex": "0x0",
    "removed": false
  }]
}
```

### eth\_chainId

Returns the currently configured chain ID, used for signing replay-protected transactions.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
      '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}' \
      http://localhost:8545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast chain-id --rpc-url http://localhost:8545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0xa"
}
```

## Gas Price Methods

### eth\_gasPrice

Returns the current gas price in wei for L2 execution.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
      '{"jsonrpc":"2.0","method":"eth_gasPrice","params":[],"id":1}' \
      http://localhost:8545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast gas-price --rpc-url http://localhost:8545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x4a817c800"
}
```

<Info>
  This only returns the L2 gas price. For comprehensive transaction cost estimation including L1 data fees, use the [`GasPriceOracle` predeployed contract](https://explorer.optimism.io/address/0x420000000000000000000000000000000000000F) or [the Optimism SDK](/app-developers/tutorials/transactions/sdk-estimate-costs).
</Info>

### eth\_maxPriorityFeePerGas

Returns the current maximum priority fee per gas (EIP-1559).

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
      '{"jsonrpc":"2.0","method":"eth_maxPriorityFeePerGas","params":[],"id":1}' \
      http://localhost:8545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast --priority-gas-price --rpc-url http://localhost:8545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x3b9aca00"
}
```

## Account and State Methods

### eth\_getCode

Returns code at a given address.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
      '{"jsonrpc":"2.0","method":"eth_getCode","params":["0x420000000000000000000000000000000000000F","latest"],"id":1}' \
      http://localhost:8545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast code 0x420000000000000000000000000000000000000F --rpc-url http://localhost:8545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x608060405234801561001057600080fd5b50600436106100365760003560e01c806354fd4d501461003b578063..."
}
```

### eth\_getStorageAt

Returns the value from a storage position at a given address.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
      '{"jsonrpc":"2.0","method":"eth_getStorageAt","params":["0x420000000000000000000000000000000000000F","0x0","latest"],"id":1}' \
      http://localhost:8545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast storage 0x420000000000000000000000000000000000000F 0x0 --rpc-url http://localhost:8545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x0000000000000000000000000000000000000000000000000000000000000001"
}
```

### eth\_getTransactionCount

Returns the number of transactions sent from an address (the nonce).

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
      '{"jsonrpc":"2.0","method":"eth_getTransactionCount","params":["0x8D97689C9818892B700e27F316cc3E41e17fBeb9","latest"],"id":1}' \
      http://localhost:8545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast nonce 0x8D97689C9818892B700e27F316cc3E41e17fBeb9 --rpc-url http://localhost:8545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x1a"
}
```

## Debug and Trace Methods

`op-geth` supports the same debug and trace methods as upstream Geth, allowing detailed transaction analysis and debugging.

<Warning>
  Debug and trace methods can be resource-intensive. Most public RPC providers disable these methods. You'll need to run your own node with `--http.api debug,trace` to access them.
</Warning>

### debug\_traceTransaction

Returns the trace of a transaction, showing all internal calls and state changes.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
      '{"jsonrpc":"2.0","method":"debug_traceTransaction","params":["0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b"],"id":1}' \
      http://localhost:8545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast run 0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b --rpc-url http://localhost:8545 --trace
    ```
  </Tab>
</Tabs>

### debug\_traceCall

Traces a call without executing it on-chain.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
      '{"jsonrpc":"2.0","method":"debug_traceCall","params":[{"to":"0x420000000000000000000000000000000000000F","data":"0x519b4bd3"},"latest"],"id":1}' \
      http://localhost:8545
    ```
  </Tab>
</Tabs>

## WebSocket Support

`op-geth` supports WebSocket connections for real-time event subscriptions using the `eth_subscribe` method.

### eth\_subscribe

Creates a subscription for specific events.

```javascript theme={null}
// Connect to WebSocket
const ws = new WebSocket('ws://localhost:8546');

// Subscribe to new block headers
ws.send(JSON.stringify({
  "jsonrpc": "2.0",
  "method": "eth_subscribe",
  "params": ["newHeads"],
  "id": 1
}));

// Subscribe to logs
ws.send(JSON.stringify({
  "jsonrpc": "2.0",
  "method": "eth_subscribe",
  "params": [
    "logs",
    {
      "address": "0x8320fe7702b96808f7bbc0d4a888ed1468216cfd",
      "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
    }
  ],
  "id": 2
}));
```

### eth\_unsubscribe

Cancels an active subscription.

```javascript theme={null}
ws.send(JSON.stringify({
  "jsonrpc": "2.0",
  "method": "eth_unsubscribe",
  "params": ["0x9cef478923ff08bf67fde6c64013158d"],
  "id": 1
}));
```

## Additional Resources

For a complete list of all supported JSON-RPC methods, refer to:

* [Geth JSON-RPC Documentation](https://geth.ethereum.org/docs/interacting-with-geth/rpc)
* [Ethereum JSON-RPC Specification](https://ethereum.org/en/developers/docs/apis/json-rpc/)
* [OP Stack Transaction Cost Estimation](/app-developers/tutorials/transactions/sdk-estimate-costs)

## Running a Node with RPC Access

To run your own `op-geth` node with full RPC access:

```sh theme={null}
op-geth \
  --http \
  --http.addr 0.0.0.0 \
  --http.port 8545 \
  --http.api eth,net,web3,debug,trace \
  --ws \
  --ws.addr 0.0.0.0 \
  --ws.port 8546 \
  --ws.api eth,net,web3 \
  ... # additional flags
```

<Warning>
  Be cautious when exposing RPC endpoints publicly. Use authentication, rate limiting, and firewall rules to prevent abuse. Debug and trace APIs should only be enabled for trusted clients.
</Warning>