🎉 We are deprecating the Optimism SDK and migrating all tutorials to use viem/op-stack. Read more →
Builders
Node operators
JSON-RPC API

JSON-RPC API

There are several OP Mainnet components with an RPC API, which are reviewed in this guide.

⚠️

Use eth_gasPrice (opens in a new tab) instead of rollup_gasPrices for the L2 gas price. For the L1 gas price, you can call the GasPriceOracle's l1BaseFee function (opens in a new tab). If you want to estimate the cost of a transaction, you can use the SDK.

op-node

op-node implements most rollup-specific functionality as Consensus-Layer, similar to a L1 beacon-node. The following RPC methods are broken down by namespace.

The following examples show you how to make requests with curl (opens in a new tab) and cast (opens in a new tab).

Protip: piping these commands in to jq (opens in a new tab) will give you nicely formatted JSON responses.

$ cast rpc optimism_syncStatus --rpc-url http://localhost:9545 | jq

optimism

Optimism specific rollup methods.

optimism_outputAtBlock

Get the output root at a specific block. This method is documented in the specifications (opens in a new tab).

curl -X POST -H "Content-Type: application/json" --data  \
  '{"jsonrpc":"2.0","method":"optimism_outputAtBlock","params":["<hex_block_number>"],"id":1}' \
  http://localhost:9545

Sample success output:

{
   "jsonrpc":"2.0",
   "id":1,
   "result":[
      "0x0000000000000000000000000000000000000000000000000000000000000000",
      "0xabe711e34c1387c8c56d0def8ce77e454d6a0bfd26cef2396626202238442421"
   ]
}

optimism_syncStatus

Get the synchronization status.

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

Sample success output:

{
  "current_l1": {
    "hash": "0xff3b3253058411b727ac662f4c9ae1698918179e02ecebd304beb1a1ae8fc4fd",
    "number": 4427350,
    "parentHash": "0xb26586390c3f04678706dde13abfb5c6e6bb545e59c22774e651db224b16cd48",
    "timestamp": 1696478784
  },
  "current_l1_finalized": {
    "hash": "0x7157f91b8ae21ef869c604e5b268e392de5aa69a9f44466b9b0f838d56426541",
    "number": 4706784,
    "parentHash": "0x1ac2612a500b9facd650950b8755d97cf2470818da2d88552dea7cd563e86a17",
    "timestamp": 1700160084
  },
  "head_l1": {
    "hash": "0x6110a8e6ed4c4aaab20477a3eac81bf99e505bf6370cd4d2e3c6d34aa5f4059a",
    "number": 4706863,
    "parentHash": "0xee8a9cba5d93481f11145c24890fd8f536384f3c3c043f40006650538fbdcb56",
    "timestamp": 1700161272
  },
  "safe_l1": {
    "hash": "0x8407c9968ce278ab435eeaced18ba8f2f94670ad9d3bdd170560932cf46e2804",
    "number": 4706811,
    "parentHash": "0x6593cccab3e772776418ff691f6e4e75597af18505373522480fdd97219c06ef",
    "timestamp": 1700160480
  },
  "finalized_l1": {
    "hash": "0x7157f91b8ae21ef869c604e5b268e392de5aa69a9f44466b9b0f838d56426541",
    "number": 4706784,
    "parentHash": "0x1ac2612a500b9facd650950b8755d97cf2470818da2d88552dea7cd563e86a17",
    "timestamp": 1700160084
  },
  "unsafe_l2": {
    "hash": "0x9a3b2edab72150de252d45cabe2f1ac57d48ddd52bb891831ffed00e89408fe4",
    "number": 2338094,
    "parentHash": "0x935b94ec0bac0e63c67a870b1a97d79e3fa84dda86d31996516cb2f940753f53",
    "timestamp": 1696478728,
    "l1origin": {
      "hash": "0x38731e0a6eeb40091f0c4a00650e911c57d054aaeb5b158f55cd5705fa6a3ebf",
      "number": 4427339
    },
    "sequenceNumber": 3
  },
  "safe_l2": {
    "hash": "0x9a3b2edab72150de252d45cabe2f1ac57d48ddd52bb891831ffed00e89408fe4",
    "number": 2338094,
    "parentHash": "0x935b94ec0bac0e63c67a870b1a97d79e3fa84dda86d31996516cb2f940753f53",
    "timestamp": 1696478728,
    "l1origin": {
      "hash": "0x38731e0a6eeb40091f0c4a00650e911c57d054aaeb5b158f55cd5705fa6a3ebf",
      "number": 4427339
    },
    "sequenceNumber": 3
  },
  "finalized_l2": {
    "hash": "0x285b03afb46faad747be1ca7ab6ef50ef0ff1fe04e4eeabafc54f129d180fad2",
    "number": 2337942,
    "parentHash": "0x7e7f36cba1fd1ccdcdaa81577a1732776a01c0108ab5f98986cf997724eb48ac",
    "timestamp": 1696478424,
    "l1origin": {
      "hash": "0x983309dadf7e0ab8447f3050f2a85b179e9acde1cd884f883fb331908c356412",
      "number": 4427314
    },
    "sequenceNumber": 7
  },
  "pending_safe_l2": {
    "hash": "0x9a3b2edab72150de252d45cabe2f1ac57d48ddd52bb891831ffed00e89408fe4",
    "number": 2338094,
    "parentHash": "0x935b94ec0bac0e63c67a870b1a97d79e3fa84dda86d31996516cb2f940753f53",
    "timestamp": 1696478728,
    "l1origin": {
      "hash": "0x38731e0a6eeb40091f0c4a00650e911c57d054aaeb5b158f55cd5705fa6a3ebf",
      "number": 4427339
    },
    "sequenceNumber": 3
  },
  "queued_unsafe_l2": {
    "hash": "0x3af253f5b993f58fffdd5e594b3f53f5b7b254cdc18f4bdb13ea7331149942db",
    "number": 4054795,
    "parentHash": "0x284b7dc92bac97be8ec3b2cf548e75208eb288704de381f2557938ecdf86539d",
    "timestamp": 1699912130,
    "l1origin": {
      "hash": "0x1490a63c372090a0331e05e63ec6a7a6e84835f91776306531f28b4217394d76",
      "number": 4688196
    },
    "sequenceNumber": 2
  },
  "engine_sync_target": {
    "hash": "0x9a3b2edab72150de252d45cabe2f1ac57d48ddd52bb891831ffed00e89408fe4",
    "number": 2338094,
    "parentHash": "0x935b94ec0bac0e63c67a870b1a97d79e3fa84dda86d31996516cb2f940753f53",
    "timestamp": 1696478728,
    "l1origin": {
      "hash": "0x38731e0a6eeb40091f0c4a00650e911c57d054aaeb5b158f55cd5705fa6a3ebf",
      "number": 4427339
    },
    "sequenceNumber": 3
  }
}

optimism_rollupConfig

Get the rollup configuration parameters.

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

Sample success output:

{
  "genesis": {
    "l1": {
      "hash": "0x48f520cf4ddaf34c8336e6e490632ea3cf1e5e93b0b2bc6e917557e31845371b",
      "number": 4071408
    },
    "l2": {
      "hash": "0x102de6ffb001480cc9b8b548fd05c34cd4f46ae4aa91759393db90ea0409887d",
      "number": 0
    },
    "l2_time": 1691802540,
    "system_config": {
      "batcherAddr": "0x8f23bb38f531600e5d8fddaaec41f13fab46e98c",
      "overhead": "0x00000000000000000000000000000000000000000000000000000000000000bc",
      "scalar": "0x00000000000000000000000000000000000000000000000000000000000a6fe0",
      "gasLimit": 30000000
    }
  },
  "block_time": 2,
  "max_sequencer_drift": 600,
  "seq_window_size": 3600,
  "channel_timeout": 300,
  "l1_chain_id": 11155111,
  "l2_chain_id": 11155420,
  "regolith_time": 0,
  "canyon_time": 1699981200,
  "batch_inbox_address": "0xff00000000000000000000000000000011155420",
  "deposit_contract_address": "0x16fc5058f25648194471939df75cf27a2fdc48bc",
  "l1_system_config_address": "0x034edd2a225f7f429a63e0f1d2084b9e0a93b538",
  "protocol_versions_address": "0x79add5713b383daa0a138d3c4780c7a1804a8090"
}

optimism_version

Get the software version.

At the moment, building from source will not give you the correct version, but our docker images will.

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

Sample success output:

{
   "jsonrpc":"2.0",
   "id":1,
   "result":"v0.0.0-"
}

opp2p

The opp2p namespace handles peer interactions.

opp2p_self

Returns your node's information.

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

Sample success output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "peerID": "16Uiu2HAm2y6DXp6THWHCyquczNUh8gVAm4spo6hjP3Ns1dGRiAdE",
    "nodeID": "75a52a90fe5f972171fefce2399ca5a73191c654e7c7ddfdd71edf4fca6697f0",
    "userAgent": "",
    "protocolVersion": "",
    "ENR": "enr:-J-4QFOtI_hDBa_kilrQcg4iTJt9VMAuDLCbgAAKMa--WfxoPml1xDYxypUG7IsWga83FOlvr78LG3oH8CfzRzUmsDyGAYvKqIZ2gmlkgnY0gmlwhGxAaceHb3BzdGFja4Xc76gFAIlzZWNwMjU2azGhAnAON-FvpiWY2iG_LXJDYosknGyikaajPDd1cQARsVnBg3RjcIIkBoN1ZHCC0Vs",
    "addresses": [
      "/ip4/127.0.0.1/tcp/9222/p2p/16Uiu2HAm2y6DXp6THWHCyquczNUh8gVAm4spo6hjP3Ns1dGRiAdE",
      "/ip4/192.168.1.71/tcp/9222/p2p/16Uiu2HAm2y6DXp6THWHCyquczNUh8gVAm4spo6hjP3Ns1dGRiAdE",
      "/ip4/108.64.105.199/tcp/9222/p2p/16Uiu2HAm2y6DXp6THWHCyquczNUh8gVAm4spo6hjP3Ns1dGRiAdE"
    ],
    "protocols": null,
    "connectedness": 0,
    "direction": 0,
    "protected": false,
    "chainID": 0,
    "latency": 0,
    "gossipBlocks": true,
    "scores": {
      "gossip": {
        "total": 0,
        "blocks": {
          "timeInMesh": 0,
          "firstMessageDeliveries": 0,
          "meshMessageDeliveries": 0,
          "invalidMessageDeliveries": 0
        },
        "IPColocationFactor": 0,
        "behavioralPenalty": 0
      },
      "reqResp": {
        "validResponses": 0,
        "errorResponses": 0,
        "rejectedPayloads": 0
      }
    }
  }
}

opp2p_peers

Returns a list of your node's peers.

curl -X POST -H "Content-Type: application/json" --data \
    '{"jsonrpc":"2.0","method":"opp2p_peers","params":[true],"id":1}'  \
    http://localhost:9545

Sample success output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "totalConnected": 20,
    "peers": {
      "16Uiu2HAkvNYscHu4V1uj6fVWkwrAMCRsqXDSq4mUbhpGq4LttYsC": {
        "peerID": "16Uiu2HAkvNYscHu4V1uj6fVWkwrAMCRsqXDSq4mUbhpGq4LttYsC",
        "nodeID": "d693c5b58424016c0c38ec5539c272c754cb6b8007b322e0ecf16a4ee13f96fb",
        "userAgent": "optimism",
        "protocolVersion": "",
        "ENR": "",
        "addresses": [
          "/ip4/20.249.62.215/tcp/9222/p2p/16Uiu2HAkvNYscHu4V1uj6fVWkwrAMCRsqXDSq4mUbhpGq4LttYsC"
        ],
        "protocols": [
          "/ipfs/ping/1.0.0",
          "/meshsub/1.0.0",
          "/meshsub/1.1.0",
          "/opstack/req/payload_by_number/11155420/0",
          "/floodsub/1.0.0",
          "/ipfs/id/1.0.0",
          "/ipfs/id/push/1.0.0"
        ],
        "connectedness": 1,
        "direction": 1,
        "protected": false,
        "chainID": 0,
        "latency": 0,
        "gossipBlocks": true,
        "scores": {
          "gossip": {
            "total": -5.04,
            "blocks": {
              "timeInMesh": 0,
              "firstMessageDeliveries": 0,
              "meshMessageDeliveries": 0,
              "invalidMessageDeliveries": 0
            },
            "IPColocationFactor": 0,
            "behavioralPenalty": 0
          },
          "reqResp": {
            "validResponses": 0,
            "errorResponses": 0,
            "rejectedPayloads": 0
          }
        }
      },
    ...
    "bannedPeers": [],
    "bannedIPS": [],
    "bannedSubnets": []
  }
}

opp2p_peerStats

Returns your peer stats.

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

Sample success output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "connected": 20,
    "table": 94,
    "blocksTopic": 20,
    "blocksTopicV2": 18,
    "banned": 0,
    "known": 71
  }
}

opp2p_discoveryTable

Returns your peer discovery table.

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

Sample success output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
  "enr:-J24QGC_SzoGG4EqyvO_082paQOwhvECeWGT-kaenrHdE2_iLTLeGmH-IOVpqEjC0L-yWmkI-c7598VaCjHQRNWn1CyGAYsqDgrFgmlkgnY0gmlwhNgp3WeHb3BzdGFja4OFQgCJc2VjcDI1NmsxoQPiq20PNZYzyvpEifcGVrOXHfM94JeWSgDL07I2hSl0d4N0Y3CCJAaDdWRwgiQG",
  "enr:-J24QKvt2ThBM8-FPeHfAmpoaVLdfVD2cw1cRpNuwmvH_bQtQ1dqrrZw9FqiMbXbFRQf9IvjrlKSFLodbsRALIFATICGAYuQClJigmlkgnY0gmlwhKI3ZuaHb3BzdGFja4O6BACJc2VjcDI1NmsxoQLQRz2CH95qQd6vmF5saV-WOoTZobNfSt-FUdVa7R35nYN0Y3CCIyuDdWRwgiMr",
  "enr:-J24QEMvLGmRBbDw48cHq9GzHSDiPlJ3eUpZiOMMXwvxN0JLQMZsS3-J6DKP2Uu--65BC5lAQF3zv7ukQDbEjuZpr5iGAYs0a4segmlkgnY0gmlwhEEVRWmHb3BzdGFja4OFQgCJc2VjcDI1NmsxoQJI0VT2eysk6v3t63pOZlGgJReDnNqh30roStkURIpGCoN0Y3CCJAaDdWRwgiQG",
  ...
  "enr:-J24QOdxnjbP7MkCFBuEjWe50NGdtAECj8tyrDBmXm8Y-JydVeoNF_IXNqodIUqeAfuAe3gcLceju96NVf8as78Eaq-GAYlu7qN_gmlkgnY0gmlwhAUJaBCHb3BzdGFja4OFQgCJc2VjcDI1NmsxoQKTb2oTlnUf5v-jP7YXZXI1wcfeSuPvsVd2niNV3BXHBYN0Y3CCJAaDdWRwgiQG"
  ]
}

opp2p_blockPeer

Blocks a peer.

curl -X POST -H "Content-Type: application/json" --data \
    '{"jsonrpc":"2.0","method":"opp2p_blockPeer","params":[<peerID>],"id":1}'  \
    http://localhost:9545

Sample success output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}

opp2p_unblockPeer

Unblocks a peer.

curl -X POST -H "Content-Type: application/json" --data \
    '{"jsonrpc":"2.0","method":"opp2p_unblockPeer","params":[<peerID>],"id":1}'  \
    http://localhost:9545

Sample success output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}

opp2p_listBlockedPeers

Returns a list of your blocked peers.

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

Sample success output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    "16Uiu2HAmV3PueiaHj7Rg2bs3mrRUo2RVhjXRMpH67k9iZquDGQ8v"
  ]
}

opp2p_blockAddr

Blocks ip address.

curl -X POST -H "Content-Type: application/json" --data \
    '{"jsonrpc":"2.0","method":"opp2p_blockAddr","params":["<ip-address>"],"id":1}'  \
    http://localhost:9545

Sample success output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}

opp2p_unblockAddr

Unblocks ip address.

curl -X POST -H "Content-Type: application/json" --data \
    '{"jsonrpc":"2.0","method":"opp2p_unblockAddr","params":["<ip-address>"],"id":1}'  \
    http://localhost:9545

Sample success output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}

opp2p_listBlockedAddrs

Returns a list of blocked ip addresses.

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

Sample success output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    "2607:f8b0:4002:c0c::65"
  ]
}

opp2p_blockSubnet

Blocks subnet.

curl -X POST -H "Content-Type: application/json" --data \
    '{"jsonrpc":"2.0","method":"opp2p_blockSubnet","params":["<subnet>"],"id":1}'  \
    http://localhost:9545

Sample success output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}

opp2p_unblockSubnet

Unblocks subnet.

curl -X POST -H "Content-Type: application/json" --data \
    '{"jsonrpc":"2.0","method":"opp2p_unblockSubnet","params":["<subnet>"],"id":1}'  \
    http://localhost:9545

Sample success output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}

opp2p_listBlockedSubnets

Returns list of blocked subnets.

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

Sample success output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": []
}

opp2p_protectPeer

Protect peer.

curl -X POST -H "Content-Type: application/json" --data \
    '{"jsonrpc":"2.0","method":"opp2p_protectPeer","params":["<peerID>"],"id":1}'  \
    http://localhost:9545

Sample success output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}

opp2p_unprotectPeer

Unprotect peer.

curl -X POST -H "Content-Type: application/json" --data \
    '{"jsonrpc":"2.0","method":"opp2p_unprotectPeer","params":["<peerID>"],"id":1}'  \
    http://localhost:9545

Sample success output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}

opp2p_connectPeer

Connect peer.

curl -X POST -H "Content-Type: application/json" --data \
    '{"jsonrpc":"2.0","method":"opp2p_connectPeer","params":[<peer multiaddr>],"id":1}'  \
    http://localhost:9545

Sample success output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}

opp2p_disconnectPeer

Disconnect peer.

curl -X POST -H "Content-Type: application/json" --data \
    '{"jsonrpc":"2.0","method":"opp2p_disconnectPeer","params":["<peerID>"],"id":1}'  \
    http://localhost:9545

Sample success output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}

admin

todo: add admin namespace description

admin_resetDerivationPipeline

Resets the derivation pipeline.

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

Sample success output:

todo: add Sample success output

admin_startSequencer

Starts the sequencer.

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

Sample success output:

todo: add Sample success output

admin_stopSequencer

Stops sequencer.

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

Sample success output:

todo: add Sample success output

admin_sequencerActive

TODO: add description

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

Sample success output:

todo: add Sample success output

op-geth

op-geth implements the Execution-Layer, with minimal changes for a secure Ethereum-equivalent application environment.

The execution engine's RPC interface is identical to the upstream Geth RPC interface (opens in a new tab). The responses are nearly identical too, except we also include the L1 gas usage and price information.