Optimism RPC Guide: How to Connect and Build on Optimism (2026)
Optimism (OP Mainnet) is a Layer 2 network built on the OP Stack, Ethereum’s most widely adopted optimistic rollup framework. It executes transactions off-chain, batches them, posts transaction data to Ethereum L1 as calldata. The result: lower gas costs with security anchored directly to Ethereum.
To interact with OP Mainnet programmatically (reading contract state, submitting transactions, subscribing to events, monitoring L1/L2 bridge messages), your application connects through a JSON-RPC endpoint. This guide covers the full picture: OP Stack-specific RPC methods, how to connect with ethers.js, Web3.py, curl, Optimism’s finality model, common production issues, how to choose a provider.
For MetaMask setup and BoltRPC endpoint details, see the Optimism chain page.
What is an Optimism RPC Endpoint
An Optimism RPC endpoint is an HTTP or WebSocket URL that exposes the Optimism JSON-RPC API. Your application sends method calls and receives on-chain data in return.
HTTP endpoints handle request-response interactions: reading balances, calling contracts, submitting transactions, querying logs.
WebSocket endpoints maintain a persistent connection for event subscriptions. Use WSS for real-time block tracking, bridge message monitoring, or contract event streaming.
OP Mainnet uses chain ID 10. Optimism Sepolia (testnet) uses chain ID 11155420. Both networks expose the same JSON-RPC method set but hold entirely separate state. Never submit a mainnet transaction to a testnet endpoint.
Example Optimism RPC Methods
Optimism is fully EVM-compatible. Every standard Ethereum JSON-RPC method works identically on OP Mainnet. Beyond the standard set, the OP Stack adds its own prefixed methods for rollup-specific operations.
Standard Ethereum Methods (work identically on OP Mainnet)
| Method | What It Does |
|---|---|
eth_blockNumber | Latest sequenced block number |
eth_call | Execute read-only contract call |
eth_getLogs | Query contract event logs by block range or address |
eth_getTransactionReceipt | Check transaction confirmation status |
eth_estimateGas | Estimate gas before submitting a transaction |
eth_subscribe | Subscribe to new blocks or log events (WSS only) |
eth_sendRawTransaction | Submit a signed transaction to the sequencer |
OP Stack-Specific Methods
These methods are unique to OP Stack chains and are not available on Ethereum mainnet:
| Method | What It Does |
|---|---|
optimism_syncStatus | Returns the current sync state of the node: L1 head, safe head, finalized head, sequencer status |
optimism_outputAtBlock | Returns the output root for a specific block, used in fault proof verification |
optimism_rollupConfig | Returns the full rollup configuration: chain ID, L1 genesis, batch inbox address, sequencer address |
optimism_safeHeadAtL1Block | Returns the L2 safe head at a given L1 block height, useful for cross-chain sequencing checks |
op_getL1BlockInfo | Returns the L1 block attributes deposited into the current L2 block |
optimism_syncStatus is particularly useful in production. It exposes three distinct block heads: the unsafe head (latest sequencer output), the safe head (sequenced blocks backed by L1 data), the finalized head (blocks past the 7-day challenge window). Monitoring these three values tells you exactly where your RPC node stands relative to L1 finality.
Public Optimism RPC Endpoints
For development and testing, these public endpoints are available:
| Provider | HTTP Endpoint | Notes |
|---|---|---|
| Optimism Foundation | https://mainnet.optimism.io | Official, rate limited |
| Alchemy | https://opt-mainnet.g.alchemy.com/v2/demo | Rate limited demo key |
| Ankr | https://rpc.ankr.com/optimism | Public, shared throughput |
| dRPC | https://optimism.drpc.org | Public tier available |
Public endpoints are suitable for initial testing. For production workloads, a dedicated provider endpoint with an auth key is required. Public endpoints enforce strict rate limits and share capacity across all users.
Connecting Step by Step
ethers.js (HTTP)
import { ethers } from "ethers";
const provider = new ethers.JsonRpcProvider(
"https://eu.endpoints.matrixed.link/rpc/optimism?auth=YOUR_KEY"
);
// Get latest block
const block = await provider.getBlock("latest");
console.log("Block number:", block.number);
// Read contract state (ERC-20 balance)
const erc20Abi = ["function balanceOf(address) view returns (uint256)"];
const contract = new ethers.Contract("0xTokenAddress", erc20Abi, provider);
const balance = await contract.balanceOf("0xYourAddress");
console.log("Token balance:", ethers.formatUnits(balance, 18));ethers.js (WebSocket subscription)
import { ethers } from "ethers";
const provider = new ethers.WebSocketProvider(
"wss://eu.endpoints.matrixed.link/ws/optimism?auth=YOUR_KEY"
);
// Subscribe to new blocks
provider.on("block", (blockNumber) => {
console.log("New block:", blockNumber);
});
// Subscribe to contract events
const filter = {
address: "0xTokenAddress",
topics: [ethers.id("Transfer(address,address,uint256)")]
};
provider.on(filter, (log) => {
console.log("Transfer event:", log);
});Web3.py
from web3 import Web3
w3 = Web3(Web3.HTTPProvider(
"https://eu.endpoints.matrixed.link/rpc/optimism?auth=YOUR_KEY"
))
# Verify connection
print("Connected:", w3.is_connected())
print("Chain ID:", w3.eth.chain_id) # Should be 10
# Get latest block
block = w3.eth.get_block("latest")
print("Block number:", block.number)
print("Block timestamp:", block.timestamp)curl
# Get latest block number
curl https://eu.endpoints.matrixed.link/rpc/optimism?auth=YOUR_KEY \
-X POST \
-H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
# Check OP Stack sync status
curl https://eu.endpoints.matrixed.link/rpc/optimism?auth=YOUR_KEY \
-X POST \
-H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"optimism_syncStatus","params":[],"id":1}'Optimism-Specific Considerations
The Sequencer and Soft Finality
OP Mainnet uses a centralized sequencer operated by the Optimism Foundation. When your application submits a transaction, it goes to the sequencer, which orders and executes it immediately. Soft finality is near-instant: the sequencer confirms your transaction within seconds.
Hard finality (L1 finality) follows a different timeline. The sequencer posts transaction batches to Ethereum L1 periodically. Once a batch is posted, the transactions are “safe.” After the 7-day challenge window passes with no fraud proofs submitted, they are “finalized.”
For most dApp interactions, soft finality is sufficient. For bridge withdrawals, cross-chain settlements, anything involving L1 state, you need to wait for safe or finalized status.
Bedrock Architecture
The Bedrock upgrade (launched June 2023) redesigned OP Mainnet’s architecture to bring it fully in line with the OP Stack specification. Key changes relevant to RPC usage:
- Block times dropped from ~1 block per transaction to a consistent 2-second block time, matching the OP Stack standard
- Transaction data is posted to Ethereum as calldata (pre-EIP-4844) or blobs (post-EIP-4844), reducing L1 data costs significantly
- The derivation pipeline is now deterministic: any OP Stack node can reconstruct L2 state from L1 data alone
eth_getBlockByNumbernow returns blocks with consistent 2-second intervals rather than variable timing
Applications built before Bedrock that relied on variable block timing need to account for the new consistent cadence.
L1/L2 Messaging
The OP Stack bridge enables assets and messages to move between OP Mainnet and Ethereum. L1-to-L2 messages (deposits) are processed via a “deposit transaction” type that appears in the first block after the L1 transaction is finalized. L2-to-L1 messages (withdrawals) require a 7-day challenge period before they can be finalized on L1.
Monitoring bridge activity requires subscribing to events on both the Optimism and Ethereum sides. The key contracts are:
L1CrossDomainMessenger(on Ethereum): emitsSentMessagefor depositsL2CrossDomainMessenger(on OP Mainnet): emitsRelayedMessagewhen a deposit is processedOptimismPortal(on Ethereum): handles withdrawal finalization
Use eth_getLogs against these contract addresses to track bridge state from either side.
Superchain Context
OP Mainnet is the first chain in the Superchain: a network of interoperable L2 chains all built on the OP Stack. Base, Mode, Zora share the same underlying architecture. If you are building a multi-chain OP Stack application, the optimism_rollupConfig method returns per-chain configuration, allowing your application to verify it is connected to the correct OP Stack deployment.
Common Issues and Fixes
eth_getLogs block range too wide
OP Mainnet nodes enforce a maximum log query range, typically 10,000 blocks per request on most providers. Querying from block 0 to latest in a single call returns an error. Fix: paginate your log queries in chunks of 2,000 to 5,000 blocks.
async function getLogsInRange(provider, filter, fromBlock, toBlock, chunkSize = 2000) {
const logs = [];
for (let start = fromBlock; start <= toBlock; start += chunkSize) {
const end = Math.min(start + chunkSize - 1, toBlock);
const chunk = await provider.getLogs({ ...filter, fromBlock: start, toBlock: end });
logs.push(...chunk);
}
return logs;
}Transaction shows as pending but sequencer accepted it
After submitting a transaction, eth_getTransactionByHash may return null briefly if the RPC node has not yet synced the sequencer’s latest output. Retry with exponential backoff before treating the transaction as lost.
optimism_syncStatus shows unsafe head ahead of safe head
This is normal behavior. The unsafe head is the sequencer’s latest output. The safe head is the latest block backed by L1 data. A gap between them is expected during normal operation and closes within minutes as the sequencer posts new batches to L1.
nonce too low on rapid transaction submission
The sequencer processes transactions in the order received. If you submit multiple transactions quickly, manage nonces explicitly rather than relying on eth_getTransactionCount for each call, since count may not reflect pending sequencer state.
WebSocket disconnection during high-traffic periods
Implement reconnect logic with backoff. Log events generated during a disconnection are not replayed automatically. Track the last received block number and re-query eth_getLogs for the gap when reconnecting.
Choosing a Provider
The key dimensions when evaluating an Optimism RPC provider:
Pricing model. Per-call or compute-unit pricing penalizes eth_getLogs-heavy workloads. Governance tooling, event indexers, bridge monitors all generate high log query volume. Flat-rate pricing eliminates cost unpredictability for these patterns.
OP Stack method support. Verify that optimism_syncStatus, optimism_rollupConfig, op_getL1BlockInfo are supported. Some providers return errors on these methods. They are essential for bridge monitoring and sequencer health checks.
WebSocket support. Required for real-time event subscriptions. Confirm the provider exposes WSS alongside HTTP.
Network coverage. If you are building across multiple OP Stack chains (Optimism, Base, others), a single provider supporting all of them simplifies key management and endpoint configuration.
BoltRPC supports OP Mainnet over HTTP and WebSocket with full OP Stack method support. Flat-rate pricing from $49/month. Start your free 2-week trial. See the full Optimism chain page for endpoint details.
FAQ
What is the Optimism RPC endpoint URL?
The BoltRPC endpoint for OP Mainnet is https://eu.endpoints.matrixed.link/rpc/optimism?auth=YOUR_KEY. The chain ID is 10. For MetaMask setup instructions, see the Optimism chain page.
What is the difference between the unsafe head, safe head, finalized head on Optimism?
The unsafe head is the latest block confirmed by the sequencer but not yet backed by L1 data. The safe head is backed by L1 transaction data posted to Ethereum. The finalized head has passed the 7-day fraud proof window. Call optimism_syncStatus to retrieve all three values from your RPC node.
How long does an Optimism withdrawal take? Withdrawals from OP Mainnet to Ethereum require a 7-day challenge period after the L2 transaction is included in a finalized L1 batch. This is the fraud proof window. Once the period passes, the withdrawal can be finalized on Ethereum L1. Deposits from Ethereum to Optimism are processed much faster: typically within a few minutes.
What OP Stack-specific RPC methods should developers know about?
The most important are optimism_syncStatus (node sync state), optimism_rollupConfig (chain configuration), optimism_outputAtBlock (output root for fault proofs), op_getL1BlockInfo (L1 attributes in the current L2 block). These are not available on Ethereum mainnet and are specific to OP Stack chains.
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "FAQPage",
"mainEntity": [
{
"@type": "Question",
"name": "What is the Optimism RPC endpoint URL?",
"acceptedAnswer": {
"@type": "Answer",
"text": "The BoltRPC endpoint for OP Mainnet is https://eu.endpoints.matrixed.link/rpc/optimism?auth=YOUR_KEY. The chain ID is 10. See the Optimism chain page at boltrpc.io/networks/optimism for MetaMask setup instructions."
}
},
{
"@type": "Question",
"name": "What is the difference between the unsafe head, safe head, finalized head on Optimism?",
"acceptedAnswer": {
"@type": "Answer",
"text": "The unsafe head is the latest block confirmed by the sequencer but not yet posted to L1. The safe head is backed by L1 data posted to Ethereum. The finalized head has passed the 7-day fraud proof window. Call optimism_syncStatus to retrieve all three values."
}
},
{
"@type": "Question",
"name": "How long does an Optimism withdrawal take?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Withdrawals from OP Mainnet to Ethereum require a 7-day challenge period after the L2 transaction is included in a finalized L1 batch. Once the period passes, the withdrawal can be finalized on Ethereum L1. Deposits from Ethereum to Optimism are processed within a few minutes."
}
},
{
"@type": "Question",
"name": "What OP Stack-specific RPC methods should developers know about?",
"acceptedAnswer": {
"@type": "Answer",
"text": "The most important are optimism_syncStatus (node sync state), optimism_rollupConfig (chain configuration), optimism_outputAtBlock (output root for fault proofs), op_getL1BlockInfo (L1 attributes in the current L2 block). These are specific to OP Stack chains and are not available on Ethereum mainnet."
}
}
]
}
</script>