diff --git a/docs/base-chain/flashblocks/api-reference.mdx b/docs/base-chain/flashblocks/api-reference.mdx
new file mode 100644
index 000000000..2ff1577f7
--- /dev/null
+++ b/docs/base-chain/flashblocks/api-reference.mdx
@@ -0,0 +1,748 @@
+---
+title: 'Flashblocks API Reference'
+description: 'Complete reference for Flashblocks-aware RPC methods and real-time WebSocket subscription types for sub-200ms preconfirmed transaction data.'
+---
+
+Flashblocks-aware nodes extend the standard Ethereum JSON-RPC API with support for preconfirmed block state and Flashblocks-specific real-time subscriptions. All [standard JSON-RPC methods](/base-chain/reference/json-rpc-api) remain fully supported.
+
+
+See [Flashblocks](/base-chain/flashblocks/apps) for an overview of Flashblocks and how to integrate it into your app. For the standard Base node RPC reference, see the [JSON-RPC API Reference](/base-chain/reference/json-rpc-api).
+
+
+## Endpoints
+
+Connect to a Flashblocks-aware endpoint to access preconfirmed data:
+
+| Network | HTTP RPC | WebSocket (WSS) |
+| ------- | -------- | --------------- |
+| Mainnet | `https://mainnet-preconf.base.org` | `wss://mainnet-preconf.base.org` |
+| Sepolia | `https://sepolia-preconf.base.org` | `wss://sepolia-preconf.base.org` |
+
+
+The public endpoints above are rate-limited and not suitable for production traffic. For production use, connect through a Flashblocks-enabled node provider such as Alchemy, QuickNode, or dRPC.
+
+
+---
+
+## Standard Methods with Flashblocks Behavior
+
+The following standard JSON-RPC methods return preconfirmed data when called with the `"pending"` block tag against a Flashblocks-aware endpoint. This gives your application real-time state up to 200ms before the next full block is sealed.
+
+### eth_getBlockByNumber
+
+When called with `"pending"`, returns the current Flashblock — the block actively being built with preconfirmed transactions.
+
+#### Parameters
+
+
+ Use `"pending"` to retrieve the latest Flashblock. Also accepts `"latest"`, `"safe"`, `"finalized"`, or a specific block number.
+
+
+
+ If `true`, returns full transaction objects. If `false`, returns only transaction hashes.
+
+
+#### Returns
+
+
+ A block object reflecting the current preconfirmed state. See [eth_getBlockByNumber](/base-chain/reference/json-rpc-api#eth_getblockbynumber) for full field descriptions.
+
+
+
+```bash cURL
+curl https://sepolia-preconf.base.org \
+ -X POST \
+ -H "Content-Type: application/json" \
+ -d '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["pending",true],"id":1}'
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": {
+ "number": "0x1234",
+ "hash": "0x...",
+ "transactions": [...]
+ }
+}
+```
+
+
+---
+
+### eth_getTransactionReceipt
+
+Returns the receipt for a preconfirmed transaction before it is included in a finalized block.
+
+#### Parameters
+
+
+ The 32-byte transaction hash.
+
+
+#### Returns
+
+
+ A transaction receipt object for the preconfirmed transaction, or `null` if not found. See [eth_getTransactionReceipt](/base-chain/reference/json-rpc-api#eth_gettransactionreceipt) for full field descriptions.
+
+
+
+```bash cURL
+curl https://sepolia-preconf.base.org \
+ -X POST \
+ -H "Content-Type: application/json" \
+ -d '{"jsonrpc":"2.0","method":"eth_getTransactionReceipt","params":["0x..."],"id":1}'
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": {
+ "transactionHash": "0x...",
+ "blockNumber": "0x1234",
+ "status": "0x1"
+ }
+}
+```
+
+
+---
+
+### eth_getBalance
+
+Returns the ETH balance of an address in the latest preconfirmed Flashblock state.
+
+#### Parameters
+
+
+ The 20-byte address to query.
+
+
+
+ Use `"pending"` to query preconfirmed state.
+
+
+#### Returns
+
+
+ The balance in wei as a hexadecimal string.
+
+
+
+```bash cURL
+curl https://sepolia-preconf.base.org \
+ -X POST \
+ -H "Content-Type: application/json" \
+ -d '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0x...","pending"],"id":1}'
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": "0x0234c00000"
+}
+```
+
+
+---
+
+### eth_getTransactionCount
+
+Returns the account nonce in the latest preconfirmed Flashblock state. Use `"pending"` to account for transactions that are preconfirmed but not yet in a sealed block.
+
+#### Parameters
+
+
+ The 20-byte account address.
+
+
+
+ Use `"pending"` to include preconfirmed transactions in the nonce count.
+
+
+#### Returns
+
+
+ The transaction count (nonce) as a hexadecimal integer.
+
+
+
+```bash cURL
+curl https://sepolia-preconf.base.org \
+ -X POST \
+ -H "Content-Type: application/json" \
+ -d '{"jsonrpc":"2.0","method":"eth_getTransactionCount","params":["0x...","pending"],"id":1}'
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": "0x1b"
+}
+```
+
+
+---
+
+### eth_getTransactionByHash
+
+Returns a preconfirmed transaction before it is included in a finalized block.
+
+#### Parameters
+
+
+ The 32-byte transaction hash.
+
+
+#### Returns
+
+
+ A transaction object, or `null` if not found. See [eth_getTransactionByHash](/base-chain/reference/json-rpc-api#eth_gettransactionbyhash) for full field descriptions.
+
+
+
+```bash cURL
+curl https://sepolia-preconf.base.org \
+ -X POST \
+ -H "Content-Type: application/json" \
+ -d '{"jsonrpc":"2.0","method":"eth_getTransactionByHash","params":["0x..."],"id":1}'
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": {
+ "type": "0x2",
+ "chainId": "0x14a34",
+ "nonce": "0x1b",
+ "hash": "0x...",
+ "from": "0x...",
+ "to": "0x..."
+ }
+}
+```
+
+
+---
+
+### eth_call
+
+Executes a contract call against the latest preconfirmed Flashblock state.
+
+#### Parameters
+
+
+ The transaction call object. See [eth_call](/base-chain/reference/json-rpc-api#eth_call) for field details.
+
+
+
+ Use `"pending"` to execute the call against preconfirmed state.
+
+
+#### Returns
+
+
+ Hex-encoded return data from the contract call.
+
+
+
+```bash cURL
+curl https://sepolia-preconf.base.org \
+ -X POST \
+ -H "Content-Type: application/json" \
+ -d '{"jsonrpc":"2.0","method":"eth_call","params":[{"to":"0x...","data":"0x..."},"pending"],"id":1}'
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": "0x0000000000000000000000000000000000000000000000000000000000000001"
+}
+```
+
+
+---
+
+### eth_estimateGas
+
+Estimates gas for a transaction against the latest preconfirmed Flashblock state.
+
+#### Parameters
+
+
+ The transaction object. See [eth_estimateGas](/base-chain/reference/json-rpc-api#eth_estimategas) for field details.
+
+
+
+ Use `"pending"` to estimate against preconfirmed state.
+
+
+#### Returns
+
+
+ Estimated gas as a hexadecimal integer.
+
+
+
+```bash cURL
+curl https://sepolia-preconf.base.org \
+ -X POST \
+ -H "Content-Type: application/json" \
+ -d '{"jsonrpc":"2.0","method":"eth_estimateGas","params":[{"to":"0x...","data":"0x..."},"pending"],"id":1}'
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": "0x5208"
+}
+```
+
+
+---
+
+### eth_getLogs
+
+Returns logs from preconfirmed Flashblock data by setting `"toBlock"` to `"pending"`.
+
+#### Parameters
+
+
+ The log filter object.
+
+
+
+ Start of the block range. Use `"latest"` for the most recent mined block.
+
+
+ Use `"pending"` to include logs from the current Flashblock.
+
+
+ A single contract address or array of addresses to filter by. Optional.
+
+
+ Array of topic filters. Same format as in `eth_getLogs`. Optional.
+
+
+
+
+#### Returns
+
+
+ An array of log objects. See [eth_getLogs](/base-chain/reference/json-rpc-api#eth_getlogs) for full field descriptions.
+
+
+
+```bash cURL
+curl https://sepolia-preconf.base.org \
+ -X POST \
+ -H "Content-Type: application/json" \
+ -d '{"jsonrpc":"2.0","method":"eth_getLogs","params":[{"fromBlock":"latest","toBlock":"pending","address":"0x...","topics":["0x..."]}],"id":1}'
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": [
+ {
+ "address": "0x...",
+ "topics": ["0x..."],
+ "data": "0x...",
+ "blockNumber": "0x1234",
+ "transactionHash": "0x...",
+ "transactionIndex": "0x0",
+ "blockHash": "0x...",
+ "logIndex": "0x0",
+ "removed": false
+ }
+ ]
+}
+```
+
+
+---
+
+## Flashblocks-Specific Methods
+
+### eth_simulateV1
+
+Simulates one or more transaction bundles against the current preconfirmed Flashblock state. Supports state overrides, multi-block simulation, and optional transfer tracing.
+
+#### Parameters
+
+
+ The simulation configuration.
+
+
+
+ Array of block state call objects. Each object represents one simulated block.
+
+
+
+ Array of transaction call objects to simulate within this block.
+
+
+ Per-address state overrides applied before simulation (e.g., balance, nonce, code, storage). Optional.
+
+
+ Block-level overrides (e.g., `number`, `timestamp`). Optional.
+
+
+
+
+ If `true`, ETH transfer events are included as logs in the result. Optional; defaults to `false`.
+
+
+ If `true`, transaction validation (nonce, balance) is enforced. Optional; defaults to `false`.
+
+
+
+
+
+ Use `"pending"` to simulate against the current Flashblock state.
+
+
+#### Returns
+
+
+ Array of simulated block results, one per entry in `blockStateCalls`.
+
+
+
+ Array of individual call results.
+
+
+
+ `"0x1"` for success, `"0x0"` for failure.
+
+
+ Gas used by this call as a hexadecimal integer.
+
+
+ Hex-encoded return data from the call.
+
+
+ Logs emitted by this call (including ETH transfer logs if `traceTransfers` is `true`).
+
+
+ Revert reason if the call failed. Optional.
+
+
+
+
+
+
+
+```bash cURL
+curl https://sepolia-preconf.base.org \
+ -X POST \
+ -H "Content-Type: application/json" \
+ -d '{
+ "jsonrpc": "2.0",
+ "method": "eth_simulateV1",
+ "params": [
+ {
+ "blockStateCalls": [
+ {
+ "calls": [
+ { "to": "0x...", "data": "0x..." }
+ ],
+ "stateOverrides": {}
+ }
+ ],
+ "traceTransfers": true,
+ "validation": true
+ },
+ "pending"
+ ],
+ "id": 1
+ }'
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": [
+ {
+ "calls": [
+ {
+ "status": "0x1",
+ "gasUsed": "0x5208",
+ "returnData": "0x",
+ "logs": []
+ }
+ ]
+ }
+ ]
+}
+```
+
+
+---
+
+### base_transactionStatus Beta
+
+Checks whether a specific transaction is present in the node's mempool. Use this to confirm that a submitted transaction has been received before it appears in a Flashblock.
+
+
+Requires [base/base](https://github.com/base/base) minimum client version v0.3.0.
+
+
+#### Parameters
+
+
+ The 32-byte transaction hash to query.
+
+
+#### Returns
+
+
+ Transaction status object.
+
+
+
+ `"Known"` if the transaction is present in the mempool. `"Unknown"` if it has not been seen by this node.
+
+
+
+
+
+```bash cURL
+curl https://sepolia-preconf.base.org \
+ -X POST \
+ -H "Content-Type: application/json" \
+ -d '{"jsonrpc":"2.0","method":"base_transactionStatus","params":["0x..."],"id":1}'
+```
+
+```json Known
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": {
+ "status": "Known"
+ }
+}
+```
+
+```json Unknown
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": {
+ "status": "Unknown"
+ }
+}
+```
+
+
+---
+
+## WebSocket Subscription Methods
+
+Flashblocks-aware nodes expose specialized `eth_subscribe` subscription types for real-time streaming of preconfirmed data at ~200ms intervals — well before a full block is sealed.
+
+
+Each subscription emits **one item per WebSocket message**. Events arrive approximately every 200ms. If your application performs heavy processing per event, throttle or debounce your handler to avoid blocking.
+
+
+
+The Flashblocks-specific subscription types (`newFlashblockTransactions`, `pendingLogs`, `newFlashblocks`) require [base/base](https://github.com/base/base) minimum client version v0.3.1.
+
+
+### Flashblocks Subscription Types
+
+In addition to the [standard subscription types](/base-chain/reference/json-rpc-api#eth_subscribe) (`newHeads`, `logs`, `newPendingTransactions`), Flashblocks-aware nodes support:
+
+| Subscription | Description | Response format |
+| ------------ | ----------- | --------------- |
+| `newFlashblockTransactions` | Streams transactions as they are preconfirmed into Flashblocks | One transaction per message |
+| `pendingLogs` | Streams logs matching a filter as they are preconfirmed | One log per message |
+| `newFlashblocks` | Streams full block state updates for each new Flashblock | Block state object per Flashblock |
+
+---
+
+### newFlashblockTransactions
+
+Subscribe to receive each transaction as it is preconfirmed. Pass `true` as the second parameter to receive full transaction and log data in each message.
+
+#### Parameters
+
+
+ Must be `"newFlashblockTransactions"`.
+
+
+
+ Optional. If `true`, each notification includes the full transaction object and associated logs. If `false` or omitted, notifications contain minimal transaction data.
+
+
+#### Returns
+
+
+ Hex-encoded subscription ID.
+
+
+
+```json Subscribe
+{"jsonrpc": "2.0", "id": 1, "method": "eth_subscribe", "params": ["newFlashblockTransactions"]}
+```
+
+```json Subscribe (full data)
+{"jsonrpc": "2.0", "id": 1, "method": "eth_subscribe", "params": ["newFlashblockTransactions", true]}
+```
+
+```json Subscription ID Response
+{"jsonrpc": "2.0", "id": 1, "result": "0x1887ec8b9589ccad00000000000532da"}
+```
+
+
+---
+
+### pendingLogs
+
+Subscribe to receive logs from preconfirmed transactions matching an optional filter. Useful for monitoring contract events with sub-block latency.
+
+#### Parameters
+
+
+ Must be `"pendingLogs"`.
+
+
+
+ Optional log filter.
+
+
+
+ A single contract address or array of addresses to filter by. Optional.
+
+
+ Array of topic filters in the same format as `eth_getLogs`. Optional.
+
+
+
+
+#### Returns
+
+
+ Hex-encoded subscription ID.
+
+
+
+```json Subscribe (with filter)
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "method": "eth_subscribe",
+ "params": [
+ "pendingLogs",
+ {
+ "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+ "topics": [
+ "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
+ ]
+ }
+ ]
+}
+```
+
+```json Subscription ID Response
+{"jsonrpc": "2.0", "id": 1, "result": "0x2a7bc8d4e3f5a6b1c2d3e4f5a6b7c8d9"}
+```
+
+
+---
+
+### newFlashblocks
+
+Subscribe to receive full block state updates as each Flashblock is built. Each message contains the accumulated preconfirmed state for the block in progress.
+
+#### Parameters
+
+
+ Must be `"newFlashblocks"`.
+
+
+#### Returns
+
+
+ Hex-encoded subscription ID.
+
+
+
+```json Subscribe
+{"jsonrpc": "2.0", "id": 1, "method": "eth_subscribe", "params": ["newFlashblocks"]}
+```
+
+```json Subscription ID Response
+{"jsonrpc": "2.0", "id": 1, "result": "0x3b8cd9e5f4a7b2c1d0e3f4a5b6c7d8e9"}
+```
+
+
+**JavaScript example:**
+
+```javascript
+import WebSocket from 'ws';
+
+// Use a WSS RPC endpoint — not the raw Flashblock WebSocket stream
+const ws = new WebSocket('wss://your-provider.example.com/ws');
+
+ws.on('open', () => {
+ ws.send(JSON.stringify({
+ jsonrpc: '2.0',
+ method: 'eth_subscribe',
+ params: ['newFlashblockTransactions'],
+ id: 1
+ }));
+});
+
+ws.on('message', (data) => {
+ const response = JSON.parse(data.toString());
+ if (response.method === 'eth_subscription') {
+ console.log('Preconfirmed transaction:', response.params.result);
+ }
+});
+
+ws.on('error', (error) => {
+ console.error('WebSocket error:', error);
+});
+
+ws.on('close', () => {
+ console.log('WebSocket connection closed');
+});
+```
+
+---
+
+### eth_unsubscribe
+
+Cancels a Flashblocks subscription. Works identically to the [standard eth_unsubscribe](/base-chain/reference/json-rpc-api#eth_unsubscribe).
+
+#### Parameters
+
+
+ The hex-encoded subscription ID returned by `eth_subscribe`.
+
+
+#### Returns
+
+
+ `true` if successfully cancelled, `false` if the subscription ID was not found.
+
+
+
+```json Request
+{"jsonrpc": "2.0", "method": "eth_unsubscribe", "params": ["0x1887ec8b9589ccad00000000000532da"], "id": 1}
+```
+
+```json Response
+{"jsonrpc": "2.0", "id": 1, "result": true}
+```
+
diff --git a/docs/base-chain/flashblocks/apps.mdx b/docs/base-chain/flashblocks/apps.mdx
index 809655673..dd34984a8 100644
--- a/docs/base-chain/flashblocks/apps.mdx
+++ b/docs/base-chain/flashblocks/apps.mdx
@@ -6,327 +6,24 @@ description: Experience lightning-fast transaction confirmations of Base by usin
## Overview
-Flashblocks enable up to 200 millisecond transaction confirmations on Base by leveraging preconfirmations, ultra-fast signals that arrive before the next block is sealed. Built for developers who demand instant UX, it's ideal for high-frequency apps, games, and real-time interactions where waiting even a few seconds is too long. By integrating directly within Base's infrastructure, Flashblocks enables, seamless, ultrafast and snappy user experiences without compromising security.
+Flashblocks enable up to 200 millisecond transaction confirmations on Base by leveraging preconfirmations, ultra-fast signals that arrive before the next block is sealed. Built for developers who demand instant UX, it's ideal for high-frequency apps, games, and real-time interactions where waiting even a few seconds is too long. By integrating directly within Base's infrastructure, Flashblocks enables seamless, ultrafast and snappy user experiences without compromising security.
-## Integrating Flashblocks
-
-Flashblocks is enabled for developers on Base. There are two ways you can integrate with Flashblocks data. You can either use the WebSocket API to stream real-time block updates, or use the RPC API to query the Flashblocks-aware RPC endpoint.
-
-### RPC API
-
-Base offers the following public Flashblocks aware RPC endpoints. These are rate limited and may not be suitable for production use - we recommend using a node provider that runs Flashblocks integrated nodes.
-Major node providers such as Alchemy, Infura, QuickNode and dRPC have Flashblocks-aware RPCs that can be leveraged
-
- | Network | URL |
- | :----------------- | :------------------------------- |
- | Mainnet | https://mainnet-preconf.base.org |
- | Sepolia | https://sepolia-preconf.base.org |
-
-
-The following RPC methods can return Flashblocks specific data. All standard Ethereum JSON-RPC methods are still supported as usual.
-
-#### eth_getBlockByNumber
-
-Use the `pending` tag to retrieve the latest Flashblock:
-```
-curl https://sepolia-preconf.base.org -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["pending",true],"id":1}'
-```
-
-**Example Response**
-```
-{
- "jsonrpc": "2.0",
- "id": 1,
- "result": {
- "number": "0x1234",
- "hash": "0x...",
- "transactions": [...]
- }
-}
-```
-
-#### eth_getTransactionReceipt
-
-Use the existing receipt RPC to get preconfirmed receipts:
-```
-curl https://sepolia-preconf.base.org -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"eth_getTransactionReceipt","params":["0x..."],"id":1}'
-```
-
-**Example Response**
-```
-{
- "jsonrpc": "2.0",
- "id": 1,
- "result": {
- "transactionHash": "0x...",
- "blockNumber": "0x1234",
- "status": "0x1"
- }
-}
-```
-
-#### eth_getBalance
-
-Use the `pending` tag to get the address balance in the latest Flashblock:
-```
-curl https://sepolia-preconf.base.org -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0x...","pending"],"id":1}'
-```
-
-**Example Response**
-```
-{
- "jsonrpc": "2.0",
- "id": 1,
- "result": "0x0234"
-}
-```
-
-#### eth_getTransactionCount
-
-Use the `pending` tag to get the address nonce in the latest Flashblock:
-```
-curl https://sepolia-preconf.base.org -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"eth_getTransactionCount","params":["0x...","pending"],"id":1}'
-```
-
-**Example Response**
-```
-{
- "jsonrpc": "2.0",
- "id": 1,
- "result": "0x1b" // 27 transactions
-}
-```
-
-#### eth_getTransactionByHash
-
-Use the existing get transaction by hash RPC to get preconfirmed transactions:
-```
-curl https://sepolia-preconf.base.org -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"eth_getTransactionByHash","params":["0x..."],"id":1}'
-```
-
-**Example Response**
-```
-{
- "type": "0x2",
- "chainId": "...",
- "nonce": "...",
- ...
-}
-```
-
-#### eth_call
-
-Use the `pending` tag to execute a smart contract call against the latest Flashblock:
-```
-curl https://sepolia-preconf.base.org -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"eth_call","params":[{"to":"0x...","data":"0x..."},"pending"],"id":1}'
-```
-
-**Example Response**
-```
-{
- "jsonrpc": "2.0",
- "id": 1,
- "result": "0x0000000000000000000000000000000000000000000000000000000000000001"
-}
-```
-
-#### eth_simulateV1
-
-Use the `pending` tag to simulate transactions against the latest Flashblock:
-```
-curl https://sepolia-preconf.base.org -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"eth_simulateV1","params":[{"blockStateCalls":[{"calls":[{"to":"0x...","data":"0x..."}],"stateOverrides":{}}],"traceTransfers":true,"validation":true},"pending"],"id":1}'
-```
-
-**Example Response**
-```
-{
- "jsonrpc": "2.0",
- "id": 1,
- "result": [
- {
- "calls": [
- {
- "status": "0x1",
- "gasUsed": "0x5208",
- "returnData": "0x"
- }
- ]
- }
- ]
-}
-```
+See the [Flashblocks API Reference](/base-chain/flashblocks/api-reference) for the full list of supported RPC methods and WebSocket subscription types.
-#### eth_estimateGas
-
-Use the `pending` tag to estimate gas against the latest Flashblock:
-```
-curl https://sepolia-preconf.base.org -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"eth_estimateGas","params":[{"to":"0x...","data":"0x..."},"pending"],"id":1}'
-```
-
-**Example Response**
-```
-{
- "jsonrpc": "2.0",
- "id": 1,
- "result": "0x5208"
-}
-```
-
-#### eth_getLogs
-
-Use the `pending` tag for `toBlock` to retrieve logs from the latest Flashblock:
-```
-curl https://sepolia-preconf.base.org -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"eth_getLogs","params":[{"fromBlock":"latest","toBlock":"pending","address":"0x...","topics":["0x..."]}],"id":1}'
-```
-
-**Example Response**
-```
-{
- "jsonrpc": "2.0",
- "id": 1,
- "result": [
- {
- "address": "0x...",
- "topics": ["0x..."],
- "data": "0x...",
- "blockNumber": "0x1234",
- "transactionHash": "0x...",
- "transactionIndex": "0x0",
- "blockHash": "0x...",
- "logIndex": "0x0",
- "removed": false
- }
- ]
-}
-```
-
-#### eth_subscribe Beta
-
-Flashblocks-aware nodes support specialized `eth_subscribe` methods for real-time streaming of Flashblock data.
-
-Requires [base/base](https://github.com/base/base) minimum client version v0.3.1
-
-
-Each subscription returns **one item per WebSocket message** and emits events every 200ms. If your application performs heavy processing on each event, consider throttling or debouncing to avoid performance issues.
-
-
-**Subscription Types:**
-
-| Subscription | Description | Response |
-|--------------|-------------|----------|
-| `newFlashblockTransactions` | Stream transactions as they're included | One transaction per message |
-| `pendingLogs` | Stream logs matching a filter | One log per message |
-| `newFlashblocks` | Stream block state updates | Block state per Flashblock |
-
----
-
-**newFlashblockTransactions**
-
-```json
-{"jsonrpc":"2.0", "id": 1, "method": "eth_subscribe", "params": ["newFlashblockTransactions"]}
-```
-
-Optional `full` parameter for enriched transaction and log data:
-```json
-{"jsonrpc":"2.0", "id": 1, "method": "eth_subscribe", "params": ["newFlashblockTransactions", true]}
-```
-
----
-
-**pendingLogs**
-
-Filter logs by address and topics:
-```json
-{"jsonrpc":"2.0", "id": 1, "method": "eth_subscribe", "params": ["pendingLogs", {"address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]}]}
-```
-
----
-
-**newFlashblocks**
-
-```json
-{"jsonrpc":"2.0", "id": 1, "method": "eth_subscribe", "params": ["newFlashblocks"]}
-```
-
----
-
-**JavaScript Example:**
-
-```javascript
-import WebSocket from 'ws';
-import { createHash } from 'crypto';
-
-// `ws` should be a WebSocket RPC URL, not from the Flashblock WebSocket Stream
-const ws = new WebSocket('wss://my-node.node-provider.com/ws');
-
-ws.on('open', () => {
- console.log('Connected to Flashblocks WebSocket');
- // Subscribe to new Flashblocks
- ws.send(JSON.stringify({
- jsonrpc: "2.0",
- method: "eth_subscribe",
- params: ["newFlashblockTransactions"],
- id: 1
- }));
-});
-
-ws.on('message', (data: WebSocket.Data) => {
- try {
- if (Buffer.isBuffer(data)) {
- if (data.length >= 37) {
- const txHash = '0x' + data.slice(5, 37).toString('hex');
- console.log(txHash);
- }
- } else {
- const response = JSON.parse(data.toString());
- if (response.id === 1) {
- console.log('✓ Subscribed');
- }
- }
- } catch (error) {
- // Handle error
- }
-});
-
-ws.on('error', (error) => {
- console.error('WebSocket error:', error);
-});
-
-ws.on('close', () => {
- console.log('WebSocket connection closed');
-});
-```
+## Integrating Flashblocks
-#### base_transactionStatus Beta
+Flashblocks is enabled for developers on Base. You can integrate with Flashblocks data via the RPC API or the WebSocket API.
-Check whether a transaction is present in the mempool:
+### RPC Endpoints
-Requires [base/base](https://github.com/base/base) minimum client version v0.3.0
-```
-curl https://sepolia-preconf.base.org -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"base_transactionStatus","params":["0x..."],"id":1}'
-```
+Base offers the following public Flashblocks-aware RPC endpoints. These are rate-limited and may not be suitable for production use — we recommend using a node provider that runs Flashblocks-integrated nodes. Major node providers such as Alchemy, Infura, QuickNode, and dRPC have Flashblocks-aware RPCs.
-**Transaction Known**
-```
-{
- "jsonrpc": "2.0",
- "id": 1,
- "result": {
- "status": "Known"
- }
-}
-```
+| Network | URL |
+| :------ | :-- |
+| Mainnet | https://mainnet-preconf.base.org |
+| Sepolia | https://sepolia-preconf.base.org |
-**Transaction Unknown**
-```
-{
- "jsonrpc": "2.0",
- "id": 1,
- "result": {
- "status": "Unknown"
- }
-}
-```
+For a full reference of all supported RPC methods — including preconfirmed state queries, simulation, and real-time subscriptions — see the [Flashblocks API Reference](/base-chain/flashblocks/api-reference).
### Libraries
diff --git a/docs/base-chain/reference/json-rpc-api.mdx b/docs/base-chain/reference/json-rpc-api.mdx
new file mode 100644
index 000000000..99074ede9
--- /dev/null
+++ b/docs/base-chain/reference/json-rpc-api.mdx
@@ -0,0 +1,2005 @@
+---
+title: 'JSON-RPC API Reference'
+description: 'Complete reference for all JSON-RPC methods available on Base chain nodes, with parameters, return values, and examples for every method.'
+---
+
+Base nodes implement the Ethereum JSON-RPC 2.0 specification. All HTTP methods accept POST requests to your RPC endpoint. WebSocket endpoints support the same methods plus real-time subscription methods.
+
+
+For production use, connect through a [node provider](/base-chain/tools/node-providers) or [run your own Base node](/base-chain/node-operators/run-a-base-node). The public endpoints `https://mainnet.base.org` and `https://sepolia.base.org` are rate-limited and not suitable for production traffic.
+
+
+## Request & Response Format
+
+All requests are HTTP POST with `Content-Type: application/json`. The body must be a JSON-RPC 2.0 request object:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `jsonrpc` | string | Always `"2.0"` |
+| `method` | string | The RPC method name |
+| `params` | array | Method parameters in order |
+| `id` | number \| string | Identifier echoed back in the response |
+
+**Success response:**
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": "0x4b7"
+}
+```
+
+**Error response:**
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "error": {
+ "code": -32602,
+ "message": "Invalid params"
+ }
+}
+```
+
+## Error Codes
+
+| Code | Name | Description |
+| --- | --- | --- |
+| `-32700` | Parse error | Invalid JSON received by the server |
+| `-32600` | Invalid request | The JSON sent is not a valid request object |
+| `-32601` | Method not found | The method does not exist or is not available |
+| `-32602` | Invalid params | Invalid method parameter(s) |
+| `-32603` | Internal error | Internal JSON-RPC error |
+| `-32000` | Server error | Node-specific error (see message for details) |
+
+## Block Parameters
+
+Methods that accept a block parameter support the following values:
+
+| Value | Description |
+| --- | --- |
+| `"latest"` | Most recently mined block (default when not specified) |
+| `"earliest"` | Genesis block (block 0) |
+| `"pending"` | Pending/preconfirmed state — use with Flashblocks endpoints |
+| `"safe"` | Latest block considered safe by the consensus layer |
+| `"finalized"` | Latest block considered finalized |
+| `"0x"` | Specific block number in hexadecimal |
+
+## Account & State Methods
+
+### eth_blockNumber
+
+Returns the number of the most recently mined block.
+
+**Parameters**
+
+This method takes no parameters.
+
+**Returns**
+
+
+ The current block number as a hexadecimal string.
+
+
+
+```json Request
+{
+ "jsonrpc": "2.0",
+ "method": "eth_blockNumber",
+ "params": [],
+ "id": 1
+}
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": "0x12ced28"
+}
+```
+
+
+### eth_getBalance
+
+Returns the ETH balance of a given address at a specified block.
+
+**Parameters**
+
+
+ The 20-byte address to check the balance for.
+
+
+
+ Block number in hexadecimal, or a block tag: `latest`, `earliest`, `pending`, `safe`, or `finalized`.
+
+
+**Returns**
+
+
+ The account balance in wei as a hexadecimal string.
+
+
+
+```json Request
+{
+ "jsonrpc": "2.0",
+ "method": "eth_getBalance",
+ "params": [
+ "0x4200000000000000000000000000000000000006",
+ "latest"
+ ],
+ "id": 1
+}
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": "0x2c68af0bb14000"
+}
+```
+
+
+### eth_getTransactionCount
+
+Returns the number of transactions sent from an address — also known as the account nonce. Use the `pending` block parameter to include transactions that are in the mempool but not yet mined.
+
+**Parameters**
+
+
+ The 20-byte account address.
+
+
+
+ Block number in hexadecimal, or a block tag: `latest`, `earliest`, `pending`, `safe`, or `finalized`.
+
+
+**Returns**
+
+
+ The number of transactions sent from the address as a hexadecimal integer.
+
+
+
+```json Request
+{
+ "jsonrpc": "2.0",
+ "method": "eth_getTransactionCount",
+ "params": [
+ "0xd3CdA913deB6f4967b2Ef66ae97DE114a83bcc01",
+ "latest"
+ ],
+ "id": 1
+}
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": "0x1b"
+}
+```
+
+
+### eth_getCode
+
+Returns the compiled bytecode stored at a given contract address. Returns `"0x"` for externally owned accounts (EOAs).
+
+**Parameters**
+
+
+ The 20-byte address (typically a smart contract).
+
+
+
+ Block number in hexadecimal, or a block tag: `latest`, `earliest`, `pending`, `safe`, or `finalized`.
+
+
+**Returns**
+
+
+ The bytecode at the address as a hex string. Returns `"0x"` if there is no code (EOA or self-destructed contract).
+
+
+
+```json Request
+{
+ "jsonrpc": "2.0",
+ "method": "eth_getCode",
+ "params": [
+ "0x4200000000000000000000000000000000000006",
+ "latest"
+ ],
+ "id": 1
+}
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": "0x6080604052348015600f57600080fd5b506004361060285760003560e01c8063..."
+}
+```
+
+
+### eth_getStorageAt
+
+Returns the raw value stored at a specific storage slot of a contract address.
+
+**Parameters**
+
+
+ The 20-byte contract address.
+
+
+
+ The hex-encoded integer position of the storage slot (e.g., `"0x0"` for slot 0).
+
+
+
+ Block number in hexadecimal, or a block tag: `latest`, `earliest`, `pending`, `safe`, or `finalized`.
+
+
+**Returns**
+
+
+ The 32-byte value stored at the given storage position as a hex string.
+
+
+
+```json Request
+{
+ "jsonrpc": "2.0",
+ "method": "eth_getStorageAt",
+ "params": [
+ "0x4200000000000000000000000000000000000006",
+ "0x0",
+ "latest"
+ ],
+ "id": 1
+}
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": "0x0000000000000000000000000000000000000000000000000000000000000000"
+}
+```
+
+
+### eth_call
+
+Executes a message call against the current chain state without broadcasting a transaction. No gas is consumed on-chain. Used to read contract state or simulate calls.
+
+**Parameters**
+
+
+ The transaction call object.
+
+
+
+ The 20-byte address the call is sent from. Optional; defaults to the zero address.
+
+
+ The 20-byte address of the contract to call.
+
+
+ Hex-encoded integer of gas to provide for the call. Defaults to a high limit if omitted.
+
+
+ Hex-encoded gas price in wei. For legacy transactions. Optional.
+
+
+ EIP-1559 maximum total fee per gas. Optional.
+
+
+ EIP-1559 maximum priority fee per gas. Optional.
+
+
+ Hex-encoded ETH value to send with the call in wei. Optional.
+
+
+ ABI-encoded call data: the 4-byte function selector followed by encoded arguments. Optional.
+
+
+
+
+
+ Block number in hexadecimal, or a block tag: `latest`, `earliest`, `pending`, `safe`, or `finalized`.
+
+
+**Returns**
+
+
+ The return value of the executed contract call as a hex-encoded byte array.
+
+
+
+```json Request
+{
+ "jsonrpc": "2.0",
+ "method": "eth_call",
+ "params": [
+ {
+ "to": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+ "data": "0x70a082310000000000000000000000004200000000000000000000000000000000000006"
+ },
+ "latest"
+ ],
+ "id": 1
+}
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": "0x0000000000000000000000000000000000000000000000000000000005f5e100"
+}
+```
+
+
+| Code | Message | Description |
+| --- | --- | --- |
+| `-32000` | execution reverted | The call reverted. The `data` field in the error object contains the ABI-encoded revert reason when available. |
+
+## Block Methods
+
+### eth_getBlockByNumber
+
+Returns information about a block by its block number.
+
+**Parameters**
+
+
+ Block number in hexadecimal, or a block tag: `latest`, `earliest`, `pending`, `safe`, or `finalized`.
+
+
+
+ If `true`, returns full transaction objects in the `transactions` array. If `false`, returns only transaction hashes.
+
+
+**Returns**
+
+
+ A block object, or `null` if no block was found.
+
+
+
+ Block number as a hex string. `null` when the block is pending.
+
+
+ 32-byte hash of the block. `null` when the block is pending.
+
+
+ 32-byte hash of the parent block.
+
+
+ 8-byte proof-of-work nonce. Always `"0x0000000000000000"` on Base (proof-of-stake).
+
+
+ 32-byte SHA3 hash of the uncles data in the block. Always the empty-uncle-list hash on Base.
+
+
+ 256-byte bloom filter for the logs of the block.
+
+
+ 32-byte root of the transaction trie.
+
+
+ 32-byte root of the final state trie.
+
+
+ 32-byte root of the receipts trie.
+
+
+ 20-byte address of the fee recipient (block proposer on Base).
+
+
+ Block difficulty. Always `"0x0"` on Base (proof-of-stake).
+
+
+ Total chain difficulty. Always `"0x0"` on Base (proof-of-stake).
+
+
+ Hex-encoded extra data field of the block.
+
+
+ Integer size of the block in bytes as a hexadecimal.
+
+
+ Maximum gas allowed in this block.
+
+
+ Total gas used by all transactions in this block.
+
+
+ Unix timestamp of when the block was collated.
+
+
+ Array of transaction hashes (when `fullTransactions` is `false`) or full transaction objects (when `true`).
+
+
+ Array of uncle block hashes. Always `[]` on Base.
+
+
+ Base fee per gas in this block (EIP-1559).
+
+
+ Array of validator withdrawals included in the block (EIP-4895).
+
+
+ 32-byte root of the withdrawals trie (EIP-4895).
+
+
+
+
+
+```json Request
+{
+ "jsonrpc": "2.0",
+ "method": "eth_getBlockByNumber",
+ "params": ["latest", false],
+ "id": 1
+}
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": {
+ "number": "0x12ced28",
+ "hash": "0x3a4e8c5d7f2b1a6e9d0c4f8b3e7a2d5c8f1b4e7a0d3c6f9b2e5a8d1c4f7b0e3",
+ "parentHash": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
+ "nonce": "0x0000000000000000",
+ "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
+ "logsBloom": "0x00000000000000000000000000000000...",
+ "transactionsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
+ "stateRoot": "0x3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b",
+ "receiptsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
+ "miner": "0x4200000000000000000000000000000000000011",
+ "difficulty": "0x0",
+ "totalDifficulty": "0x0",
+ "extraData": "0x",
+ "size": "0x220",
+ "gasLimit": "0x1c9c380",
+ "gasUsed": "0x5208",
+ "timestamp": "0x6783a5d0",
+ "transactions": [
+ "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"
+ ],
+ "uncles": [],
+ "baseFeePerGas": "0x3b9aca00",
+ "withdrawals": [],
+ "withdrawalsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421"
+ }
+}
+```
+
+```json Not Found
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": null
+}
+```
+
+
+### eth_getBlockByHash
+
+Returns information about a block by its hash.
+
+**Parameters**
+
+
+ The 32-byte hash of the block.
+
+
+
+ If `true`, returns full transaction objects. If `false`, returns only transaction hashes.
+
+
+**Returns**
+
+
+ A block object with the same fields as [`eth_getBlockByNumber`](#eth_getblockbynumber), or `null` if no block was found.
+
+
+
+```json Request
+{
+ "jsonrpc": "2.0",
+ "method": "eth_getBlockByHash",
+ "params": [
+ "0x3a4e8c5d7f2b1a6e9d0c4f8b3e7a2d5c8f1b4e7a0d3c6f9b2e5a8d1c4f7b0e3",
+ false
+ ],
+ "id": 1
+}
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": {
+ "number": "0x12ced28",
+ "hash": "0x3a4e8c5d7f2b1a6e9d0c4f8b3e7a2d5c8f1b4e7a0d3c6f9b2e5a8d1c4f7b0e3",
+ "parentHash": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
+ "gasLimit": "0x1c9c380",
+ "gasUsed": "0x5208",
+ "timestamp": "0x6783a5d0",
+ "baseFeePerGas": "0x3b9aca00",
+ "transactions": [
+ "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"
+ ]
+ }
+}
+```
+
+```json Not Found
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": null
+}
+```
+
+
+### eth_getBlockReceipts
+
+Returns all transaction receipts for a given block. More efficient than calling `eth_getTransactionReceipt` individually for each transaction.
+
+**Parameters**
+
+
+ Block number in hexadecimal, or a block tag: `latest`, `earliest`, `pending`, `safe`, or `finalized`.
+
+
+**Returns**
+
+
+ An array of transaction receipt objects for every transaction in the block, or `null` if the block was not found. Each receipt has the same structure as [`eth_getTransactionReceipt`](#eth_gettransactionreceipt).
+
+
+
+```json Request
+{
+ "jsonrpc": "2.0",
+ "method": "eth_getBlockReceipts",
+ "params": ["latest"],
+ "id": 1
+}
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": [
+ {
+ "transactionHash": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
+ "transactionIndex": "0x0",
+ "blockHash": "0x3a4e8c5d7f2b1a6e9d0c4f8b3e7a2d5c8f1b4e7a0d3c6f9b2e5a8d1c4f7b0e3",
+ "blockNumber": "0x12ced28",
+ "from": "0xd3CdA913deB6f4967b2Ef66ae97DE114a83bcc01",
+ "to": "0x4200000000000000000000000000000000000006",
+ "cumulativeGasUsed": "0x5208",
+ "effectiveGasPrice": "0x3b9aca00",
+ "gasUsed": "0x5208",
+ "contractAddress": null,
+ "logs": [],
+ "logsBloom": "0x000...",
+ "status": "0x1",
+ "type": "0x2"
+ }
+ ]
+}
+```
+
+
+### eth_getBlockTransactionCountByNumber
+
+Returns the number of transactions in a block identified by block number.
+
+**Parameters**
+
+
+ Block number in hexadecimal, or a block tag: `latest`, `earliest`, `pending`, `safe`, or `finalized`.
+
+
+**Returns**
+
+
+ The number of transactions in the block as a hexadecimal integer, or `null` if no block was found.
+
+
+
+```json Request
+{
+ "jsonrpc": "2.0",
+ "method": "eth_getBlockTransactionCountByNumber",
+ "params": ["latest"],
+ "id": 1
+}
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": "0x12"
+}
+```
+
+
+### eth_getBlockTransactionCountByHash
+
+Returns the number of transactions in a block identified by block hash.
+
+**Parameters**
+
+
+ The 32-byte hash of the block.
+
+
+**Returns**
+
+
+ The number of transactions in the block as a hexadecimal integer, or `null` if no block was found.
+
+
+
+```json Request
+{
+ "jsonrpc": "2.0",
+ "method": "eth_getBlockTransactionCountByHash",
+ "params": [
+ "0x3a4e8c5d7f2b1a6e9d0c4f8b3e7a2d5c8f1b4e7a0d3c6f9b2e5a8d1c4f7b0e3"
+ ],
+ "id": 1
+}
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": "0x12"
+}
+```
+
+
+## Transaction Methods
+
+### eth_getTransactionByHash
+
+Returns transaction information for a given transaction hash.
+
+**Parameters**
+
+
+ The 32-byte transaction hash.
+
+
+**Returns**
+
+
+ A transaction object, or `null` if no transaction was found.
+
+
+
+ 32-byte hash of the transaction.
+
+
+ Number of transactions sent by the sender prior to this one.
+
+
+ 32-byte hash of the block this transaction is in. `null` if pending.
+
+
+ Block number this transaction is in. `null` if pending.
+
+
+ Transaction's index position in the block. `null` if pending.
+
+
+ 20-byte address of the sender.
+
+
+ 20-byte address of the receiver. `null` for contract creation transactions.
+
+
+ Value transferred in wei as a hexadecimal.
+
+
+ Gas provided by the sender.
+
+
+ Gas price in wei. For EIP-1559 transactions, this is the effective gas price paid.
+
+
+ Maximum total fee per gas the sender is willing to pay (EIP-1559). Only present for type `0x2` transactions.
+
+
+ Maximum priority fee per gas (EIP-1559). Only present for type `0x2` transactions.
+
+
+ ABI-encoded call data sent with the transaction. `"0x"` for plain ETH transfers.
+
+
+ Transaction type: `"0x0"` (legacy), `"0x1"` (EIP-2930 access list), `"0x2"` (EIP-1559), `"0x7e"` (deposit transaction on Base).
+
+
+ Chain ID the transaction is valid for. `"0x2105"` for Base Mainnet, `"0x14a34"` for Base Sepolia.
+
+
+ List of addresses and storage keys the transaction accesses (EIP-2930). Only present for type `0x1` and `0x2` transactions.
+
+
+ ECDSA recovery ID.
+
+
+ 32-byte ECDSA signature component r.
+
+
+ 32-byte ECDSA signature component s.
+
+
+
+
+
+```json Request
+{
+ "jsonrpc": "2.0",
+ "method": "eth_getTransactionByHash",
+ "params": [
+ "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"
+ ],
+ "id": 1
+}
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": {
+ "hash": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
+ "nonce": "0x1b",
+ "blockHash": "0x3a4e8c5d7f2b1a6e9d0c4f8b3e7a2d5c8f1b4e7a0d3c6f9b2e5a8d1c4f7b0e3",
+ "blockNumber": "0x12ced28",
+ "transactionIndex": "0x0",
+ "from": "0xd3CdA913deB6f4967b2Ef66ae97DE114a83bcc01",
+ "to": "0x4200000000000000000000000000000000000006",
+ "value": "0x2c68af0bb14000",
+ "gas": "0x5208",
+ "gasPrice": "0x3b9aca00",
+ "maxFeePerGas": "0x77359400",
+ "maxPriorityFeePerGas": "0x3b9aca00",
+ "input": "0x",
+ "type": "0x2",
+ "chainId": "0x2105",
+ "accessList": [],
+ "v": "0x1",
+ "r": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
+ "s": "0x2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c"
+ }
+}
+```
+
+```json Not Found
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": null
+}
+```
+
+
+### eth_getTransactionByBlockHashAndIndex
+
+Returns transaction information for a given block hash and transaction index position.
+
+**Parameters**
+
+
+ The 32-byte hash of the block.
+
+
+
+ The transaction's index position in the block as a hexadecimal integer (e.g., `"0x0"` for the first transaction).
+
+
+**Returns**
+
+
+ A transaction object with the same fields as [`eth_getTransactionByHash`](#eth_gettransactionbyhash), or `null` if no transaction was found at that position.
+
+
+
+```json Request
+{
+ "jsonrpc": "2.0",
+ "method": "eth_getTransactionByBlockHashAndIndex",
+ "params": [
+ "0x3a4e8c5d7f2b1a6e9d0c4f8b3e7a2d5c8f1b4e7a0d3c6f9b2e5a8d1c4f7b0e3",
+ "0x0"
+ ],
+ "id": 1
+}
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": {
+ "hash": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
+ "blockNumber": "0x12ced28",
+ "transactionIndex": "0x0",
+ "from": "0xd3CdA913deB6f4967b2Ef66ae97DE114a83bcc01",
+ "to": "0x4200000000000000000000000000000000000006",
+ "value": "0x2c68af0bb14000",
+ "type": "0x2"
+ }
+}
+```
+
+
+### eth_getTransactionByBlockNumberAndIndex
+
+Returns transaction information for a given block number and transaction index position.
+
+**Parameters**
+
+
+ Block number in hexadecimal, or a block tag: `latest`, `earliest`, `pending`, `safe`, or `finalized`.
+
+
+
+ The transaction's index position in the block as a hexadecimal integer.
+
+
+**Returns**
+
+
+ A transaction object with the same fields as [`eth_getTransactionByHash`](#eth_gettransactionbyhash), or `null` if no transaction was found at that position.
+
+
+
+```json Request
+{
+ "jsonrpc": "2.0",
+ "method": "eth_getTransactionByBlockNumberAndIndex",
+ "params": ["latest", "0x0"],
+ "id": 1
+}
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": {
+ "hash": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
+ "blockNumber": "0x12ced28",
+ "transactionIndex": "0x0",
+ "from": "0xd3CdA913deB6f4967b2Ef66ae97DE114a83bcc01",
+ "to": "0x4200000000000000000000000000000000000006",
+ "value": "0x2c68af0bb14000",
+ "type": "0x2"
+ }
+}
+```
+
+
+### eth_getTransactionReceipt
+
+Returns the receipt for a mined transaction. Receipts are only available after the transaction has been included in a block.
+
+
+For preconfirmed transaction receipts before a block is sealed, use a [Flashblocks-aware endpoint](/base-chain/flashblocks/api-reference#eth_gettransactionreceipt).
+
+
+**Parameters**
+
+
+ The 32-byte hash of the transaction.
+
+
+**Returns**
+
+
+ A transaction receipt object, or `null` if the transaction is not found or is still pending.
+
+
+
+ 32-byte hash of the transaction.
+
+
+ Transaction's index position in the block.
+
+
+ 32-byte hash of the block this transaction is in.
+
+
+ Block number this transaction is in.
+
+
+ 20-byte address of the sender.
+
+
+ 20-byte address of the receiver. `null` for contract creation transactions.
+
+
+ Total gas used in the block at the point this transaction was executed.
+
+
+ Actual gas price paid per unit of gas for this transaction.
+
+
+ Gas used by this specific transaction.
+
+
+ The address of the contract created by this transaction, if it was a contract creation. Otherwise `null`.
+
+
+ Array of log objects generated by this transaction.
+
+
+ 256-byte bloom filter for the logs of this transaction.
+
+
+ `"0x1"` for a successful transaction, `"0x0"` for a failed (reverted) transaction.
+
+
+ Transaction type: `"0x0"` (legacy), `"0x1"` (EIP-2930), `"0x2"` (EIP-1559).
+
+
+
+
+
+```json Request
+{
+ "jsonrpc": "2.0",
+ "method": "eth_getTransactionReceipt",
+ "params": [
+ "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"
+ ],
+ "id": 1
+}
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": {
+ "transactionHash": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
+ "transactionIndex": "0x0",
+ "blockHash": "0x3a4e8c5d7f2b1a6e9d0c4f8b3e7a2d5c8f1b4e7a0d3c6f9b2e5a8d1c4f7b0e3",
+ "blockNumber": "0x12ced28",
+ "from": "0xd3CdA913deB6f4967b2Ef66ae97DE114a83bcc01",
+ "to": "0x4200000000000000000000000000000000000006",
+ "cumulativeGasUsed": "0x5208",
+ "effectiveGasPrice": "0x3b9aca00",
+ "gasUsed": "0x5208",
+ "contractAddress": null,
+ "logs": [],
+ "logsBloom": "0x00000000000000000000000000000000...",
+ "status": "0x1",
+ "type": "0x2"
+ }
+}
+```
+
+```json Not Found
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": null
+}
+```
+
+
+| Code | Message | Description |
+| --- | --- | --- |
+| `-32000` | transaction indexing is in progress | The node is still indexing transactions. Retry after the node has finished syncing. |
+
+### eth_sendRawTransaction
+
+Submits a signed, RLP-encoded transaction to the network for broadcast. The transaction must be signed offline using the sender's private key before calling this method.
+
+**Parameters**
+
+
+ The signed transaction data as a hex-encoded RLP-encoded string. Typically generated by a wallet library such as ethers.js, viem, or web3.js.
+
+
+**Returns**
+
+
+ The 32-byte transaction hash if the transaction was accepted into the mempool.
+
+
+
+```json Request
+{
+ "jsonrpc": "2.0",
+ "method": "eth_sendRawTransaction",
+ "params": [
+ "0x02f86b82210501843b9aca008477359400825208944200000000000000000000000000000000000006872c68af0bb1400080c001a01a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2ba02b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c"
+ ],
+ "id": 1
+}
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"
+}
+```
+
+
+| Code | Message | Description |
+| --- | --- | --- |
+| `-32000` | nonce too low | The transaction nonce is lower than the current account nonce |
+| `-32000` | insufficient funds for gas * price + value | The sender's balance cannot cover gas cost and value |
+| `-32000` | already known | An identical transaction is already in the mempool |
+| `-32000` | replacement transaction underpriced | A replacement transaction must pay a higher gas price |
+
+## Gas & Fee Methods
+
+### eth_gasPrice
+
+Returns the current gas price suggested for legacy (type `0x0`) transactions.
+
+**Parameters**
+
+This method takes no parameters.
+
+**Returns**
+
+
+ Current gas price in wei as a hexadecimal string.
+
+
+
+```json Request
+{
+ "jsonrpc": "2.0",
+ "method": "eth_gasPrice",
+ "params": [],
+ "id": 1
+}
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": "0x3b9aca00"
+}
+```
+
+
+### eth_maxPriorityFeePerGas
+
+Returns the suggested `maxPriorityFeePerGas` (tip) for EIP-1559 transactions. Add this to the current `baseFeePerGas` to derive a `maxFeePerGas`.
+
+**Parameters**
+
+This method takes no parameters.
+
+**Returns**
+
+
+ Suggested priority fee per gas in wei as a hexadecimal string.
+
+
+
+```json Request
+{
+ "jsonrpc": "2.0",
+ "method": "eth_maxPriorityFeePerGas",
+ "params": [],
+ "id": 1
+}
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": "0x3b9aca00"
+}
+```
+
+
+### eth_feeHistory
+
+Returns historical base fees, gas usage ratios, and priority fee percentiles for a range of blocks. Useful for building accurate EIP-1559 fee estimates.
+
+**Parameters**
+
+
+ Number of blocks to include in the history. Must be between 1 and 1024. Can be a decimal integer or a hex string (e.g., `4` or `"0x4"`).
+
+
+
+ The newest block in the requested range. Block number in hexadecimal, or a block tag: `latest`, `safe`, or `finalized`.
+
+
+
+ Optional. An array of percentile values between 0 and 100. For each block, the node returns the effective priority fee at each percentile from the transactions in that block. For example, `[25, 50, 75]` returns 25th, 50th, and 75th percentile values.
+
+
+**Returns**
+
+
+ Fee history data for the requested range.
+
+
+
+ Block number of the oldest block in the returned range.
+
+
+ Array of base fees per gas for each block in the range, plus one extra entry for the next block after the range. Length is `blockCount + 1`.
+
+
+ Array of gas used ratios (values between 0 and 1) for each block in the range.
+
+
+ Array of arrays containing the priority fees at each requested percentile for each block. Only present when `rewardPercentiles` is provided.
+
+
+
+
+
+```json Request
+{
+ "jsonrpc": "2.0",
+ "method": "eth_feeHistory",
+ "params": [4, "latest", [25, 75]],
+ "id": 1
+}
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": {
+ "oldestBlock": "0x12ced25",
+ "baseFeePerGas": [
+ "0x3b9aca00",
+ "0x3b9aca00",
+ "0x3b9aca00",
+ "0x3b9aca00",
+ "0x3b9aca00"
+ ],
+ "gasUsedRatio": [0.21, 0.45, 0.12, 0.67],
+ "reward": [
+ ["0x3b9aca00", "0x77359400"],
+ ["0x3b9aca00", "0x77359400"],
+ ["0x3b9aca00", "0x77359400"],
+ ["0x3b9aca00", "0x77359400"]
+ ]
+ }
+}
+```
+
+
+### eth_estimateGas
+
+Estimates the amount of gas required to execute a transaction. The estimate may be higher than the gas actually used at execution time.
+
+**Parameters**
+
+
+ The transaction object to estimate gas for.
+
+
+
+ The 20-byte address the transaction is sent from. Optional.
+
+
+ The 20-byte destination address. Required for contract calls; omit for contract deployments.
+
+
+ Gas limit for the estimate. Optional.
+
+
+ Gas price in wei for legacy transactions. Optional.
+
+
+ EIP-1559 maximum total fee per gas. Optional.
+
+
+ EIP-1559 maximum priority fee per gas. Optional.
+
+
+ ETH value to send with the transaction in wei. Optional.
+
+
+ ABI-encoded call data. Optional.
+
+
+
+
+
+ Optional block to estimate against. Defaults to `latest`.
+
+
+**Returns**
+
+
+ The estimated gas amount as a hexadecimal integer.
+
+
+
+```json Request
+{
+ "jsonrpc": "2.0",
+ "method": "eth_estimateGas",
+ "params": [
+ {
+ "from": "0xd3CdA913deB6f4967b2Ef66ae97DE114a83bcc01",
+ "to": "0x4200000000000000000000000000000000000006",
+ "value": "0x2c68af0bb14000"
+ }
+ ],
+ "id": 1
+}
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": "0x5208"
+}
+```
+
+
+| Code | Message | Description |
+| --- | --- | --- |
+| `-32000` | execution reverted | The transaction would revert. The error data may contain a revert reason. |
+
+## Log Methods
+
+### eth_getLogs
+
+Returns an array of logs matching the given filter criteria. Particularly useful for indexing on-chain events.
+
+
+Queries spanning large block ranges or high-activity contracts can time out or be rejected. Keep `fromBlock`-to-`toBlock` ranges under 2,000 blocks for reliable results. Node providers may enforce their own limits.
+
+
+**Parameters**
+
+
+ The log filter object. At least one filter criterion should be provided.
+
+
+
+ Start of the block range. Block number in hexadecimal or a block tag. Defaults to `"latest"`.
+
+
+ End of the block range. Block number in hexadecimal or a block tag. Defaults to `"latest"`.
+
+
+ A single contract address or array of addresses to filter logs by. Optional.
+
+
+ Array of 32-byte topic filters. Each position can be `null` (match any), a single topic hex string, or an array of topic hex strings (match any in the array). Position 0 is typically the `keccak256` hash of the event signature. Optional.
+
+
+ A specific block hash to restrict results to that single block only. If provided, `fromBlock` and `toBlock` are ignored. Optional.
+
+
+
+
+**Returns**
+
+
+ An array of log objects matching the filter.
+
+
+
+ 20-byte address of the contract that emitted the log.
+
+
+ Array of 0–4 indexed 32-byte topics. Topic 0 is the event signature hash for named events.
+
+
+ ABI-encoded non-indexed event parameters.
+
+
+ Block number in which this log was emitted.
+
+
+ 32-byte hash of the transaction that emitted this log.
+
+
+ Index of the transaction in the block.
+
+
+ 32-byte hash of the block.
+
+
+ Log's index position within the block.
+
+
+ `true` if the log was removed due to a chain reorganization. `false` for valid logs.
+
+
+
+
+
+```json Request
+{
+ "jsonrpc": "2.0",
+ "method": "eth_getLogs",
+ "params": [
+ {
+ "fromBlock": "0x12ced00",
+ "toBlock": "0x12ced28",
+ "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+ "topics": [
+ "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
+ ]
+ }
+ ],
+ "id": 1
+}
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": [
+ {
+ "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+ "topics": [
+ "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
+ "0x000000000000000000000000d3cda913deb6f4967b2ef66ae97de114a83bcc01",
+ "0x0000000000000000000000004200000000000000000000000000000000000006"
+ ],
+ "data": "0x0000000000000000000000000000000000000000000000000000000005f5e100",
+ "blockNumber": "0x12ced28",
+ "transactionHash": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
+ "transactionIndex": "0x0",
+ "blockHash": "0x3a4e8c5d7f2b1a6e9d0c4f8b3e7a2d5c8f1b4e7a0d3c6f9b2e5a8d1c4f7b0e3",
+ "logIndex": "0x0",
+ "removed": false
+ }
+ ]
+}
+```
+
+
+## Chain & Network Methods
+
+### eth_chainId
+
+Returns the chain ID of the current network per [EIP-695](https://eips.ethereum.org/EIPS/eip-695).
+
+**Parameters**
+
+This method takes no parameters.
+
+**Returns**
+
+
+ The chain ID as a hexadecimal string. `"0x2105"` (8453) for Base Mainnet, `"0x14a34"` (84532) for Base Sepolia.
+
+
+
+```json Request
+{
+ "jsonrpc": "2.0",
+ "method": "eth_chainId",
+ "params": [],
+ "id": 1
+}
+```
+
+```json Response (Base Mainnet)
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": "0x2105"
+}
+```
+
+```json Response (Base Sepolia)
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": "0x14a34"
+}
+```
+
+
+### eth_syncing
+
+Returns the synchronization status of the node.
+
+**Parameters**
+
+This method takes no parameters.
+
+**Returns**
+
+
+ Returns `false` if the node is fully synced with the network. Returns a sync status object if the node is still catching up.
+
+
+
+ Block number where the current sync started.
+
+
+ Current block the node has processed.
+
+
+ Estimated highest block number on the network.
+
+
+
+
+
+```json Request
+{
+ "jsonrpc": "2.0",
+ "method": "eth_syncing",
+ "params": [],
+ "id": 1
+}
+```
+
+```json Response (synced)
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": false
+}
+```
+
+```json Response (syncing)
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": {
+ "startingBlock": "0x0",
+ "currentBlock": "0x12ce000",
+ "highestBlock": "0x12ced28"
+ }
+}
+```
+
+
+### net_version
+
+Returns the network ID as a decimal string. For Base, this is the same value as the chain ID.
+
+**Parameters**
+
+This method takes no parameters.
+
+**Returns**
+
+
+ The network ID as a decimal string (not hex). `"8453"` for Base Mainnet, `"84532"` for Base Sepolia.
+
+
+
+```json Request
+{
+ "jsonrpc": "2.0",
+ "method": "net_version",
+ "params": [],
+ "id": 1
+}
+```
+
+```json Response (Base Mainnet)
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": "8453"
+}
+```
+
+
+### web3_clientVersion
+
+Returns a string identifying the node client software and version.
+
+**Parameters**
+
+This method takes no parameters.
+
+**Returns**
+
+
+ A string in the format `///`.
+
+
+
+```json Request
+{
+ "jsonrpc": "2.0",
+ "method": "web3_clientVersion",
+ "params": [],
+ "id": 1
+}
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": "op-geth/v1.101411.0/linux-amd64/go1.21.0"
+}
+```
+
+
+## Debug Methods
+
+
+Debug methods require a node with debug APIs enabled. Availability and rate limits vary by [node provider](/base-chain/tools/node-providers). These methods replay transactions and are computationally expensive — avoid calling them in hot paths.
+
+
+### debug_traceTransaction
+
+Replays a transaction and returns its complete EVM execution trace, including every opcode executed, gas consumed at each step, stack contents, and storage changes.
+
+**Parameters**
+
+
+ The 32-byte hash of the transaction to trace.
+
+
+
+ Optional tracing configuration.
+
+
+
+ If `true`, omits storage capture from struct logs. Reduces response size. Defaults to `false`.
+
+
+ If `true`, omits memory capture from struct logs. Reduces response size. Defaults to `false`.
+
+
+ If `true`, omits stack capture from struct logs. Defaults to `false`.
+
+
+ Name of a built-in tracer. Options: `"callTracer"` (returns a call tree), `"prestateTracer"` (returns the pre-execution state). Omit to use the default struct log tracer.
+
+
+ Configuration for the selected tracer. For `callTracer`: `{ "onlyTopCall": true }` skips internal calls.
+
+
+ Execution timeout as a Go duration string (e.g., `"10s"`, `"30s"`). Defaults to `"5s"`.
+
+
+
+
+**Returns**
+
+
+ The execution trace. Format depends on the `tracer` option selected.
+
+
+
+ Total gas provided for the transaction.
+
+
+ Whether the transaction failed (reverted).
+
+
+ Hex-encoded return value from the transaction execution.
+
+
+ Array of struct log entries, one per EVM opcode executed.
+
+
+ Program counter position.
+ EVM opcode name (e.g., `"PUSH1"`, `"SLOAD"`).
+ Remaining gas at this step.
+ Gas cost of this opcode.
+ Call depth (1 = top-level call).
+ EVM stack values at this step.
+ EVM memory contents as 32-byte chunks.
+ Contract storage changes at this step (slot → value).
+
+
+
+
+
+
+ Call type: `"CALL"`, `"STATICCALL"`, `"DELEGATECALL"`, or `"CREATE"`.
+
+ Sender address.
+ Recipient address.
+ ETH value sent with the call.
+ Gas provided for the call.
+ Gas actually consumed.
+ Call data sent.
+ Return data from the call.
+ Error message if the call reverted. Optional.
+ Array of nested call objects for internal calls.
+
+
+
+
+```json Request (default trace)
+{
+ "jsonrpc": "2.0",
+ "method": "debug_traceTransaction",
+ "params": [
+ "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
+ {}
+ ],
+ "id": 1
+}
+```
+
+```json Request (callTracer)
+{
+ "jsonrpc": "2.0",
+ "method": "debug_traceTransaction",
+ "params": [
+ "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
+ { "tracer": "callTracer" }
+ ],
+ "id": 1
+}
+```
+
+```json Response (default trace)
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": {
+ "gas": 21000,
+ "failed": false,
+ "returnValue": "",
+ "structLogs": [
+ {
+ "pc": 0,
+ "op": "PUSH1",
+ "gas": 21000,
+ "gasCost": 3,
+ "depth": 1,
+ "stack": [],
+ "memory": [],
+ "storage": {}
+ }
+ ]
+ }
+}
+```
+
+```json Response (callTracer)
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": {
+ "type": "CALL",
+ "from": "0xd3cda913deb6f4967b2ef66ae97de114a83bcc01",
+ "to": "0x4200000000000000000000000000000000000006",
+ "value": "0x2c68af0bb14000",
+ "gas": "0x5208",
+ "gasUsed": "0x5208",
+ "input": "0x",
+ "output": "0x",
+ "calls": []
+ }
+}
+```
+
+
+### debug_traceBlockByHash
+
+Replays all transactions in a block identified by its hash and returns an execution trace for each transaction.
+
+**Parameters**
+
+
+ The 32-byte hash of the block to trace.
+
+
+
+ Optional trace configuration. Accepts the same fields as [`debug_traceTransaction`](#debug_tracetransaction).
+
+
+**Returns**
+
+
+ An array of trace result objects, one per transaction in the block.
+
+
+
+ The transaction hash.
+
+
+ The execution trace for this transaction. Same format as the result of `debug_traceTransaction`.
+
+
+
+
+
+```json Request
+{
+ "jsonrpc": "2.0",
+ "method": "debug_traceBlockByHash",
+ "params": [
+ "0x3a4e8c5d7f2b1a6e9d0c4f8b3e7a2d5c8f1b4e7a0d3c6f9b2e5a8d1c4f7b0e3",
+ { "tracer": "callTracer" }
+ ],
+ "id": 1
+}
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": [
+ {
+ "txHash": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
+ "result": {
+ "type": "CALL",
+ "from": "0xd3cda913deb6f4967b2ef66ae97de114a83bcc01",
+ "to": "0x4200000000000000000000000000000000000006",
+ "value": "0x2c68af0bb14000",
+ "gas": "0x5208",
+ "gasUsed": "0x5208",
+ "input": "0x",
+ "output": "0x",
+ "calls": []
+ }
+ }
+ ]
+}
+```
+
+
+### debug_traceBlockByNumber
+
+Replays all transactions in a block identified by its number and returns an execution trace for each transaction.
+
+**Parameters**
+
+
+ Block number in hexadecimal, or a block tag: `latest`, `earliest`, `safe`, or `finalized`.
+
+
+
+ Optional trace configuration. Accepts the same fields as [`debug_traceTransaction`](#debug_tracetransaction).
+
+
+**Returns**
+
+
+ An array of trace result objects, one per transaction in the block. Same format as [`debug_traceBlockByHash`](#debug_traceblockbyhash).
+
+
+
+```json Request
+{
+ "jsonrpc": "2.0",
+ "method": "debug_traceBlockByNumber",
+ "params": ["latest", { "tracer": "callTracer" }],
+ "id": 1
+}
+```
+
+```json Response
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": [
+ {
+ "txHash": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
+ "result": {
+ "type": "CALL",
+ "from": "0xd3cda913deb6f4967b2ef66ae97de114a83bcc01",
+ "to": "0x4200000000000000000000000000000000000006",
+ "value": "0x2c68af0bb14000",
+ "gas": "0x5208",
+ "gasUsed": "0x5208",
+ "input": "0x",
+ "output": "0x",
+ "calls": []
+ }
+ }
+ ]
+}
+```
+
+
+## WebSocket Methods
+
+WebSocket methods are only available over WebSocket (WSS) connections. All HTTP methods are also available over WebSocket. Connect using your provider's WSS endpoint and send JSON-RPC messages as UTF-8 text frames.
+
+### eth_subscribe
+
+Creates a real-time subscription to on-chain events. The node pushes event notifications to the client as JSON-RPC messages whenever a matching event occurs, without the client needing to poll.
+
+**Parameters**
+
+
+ The event type to subscribe to. See subscription types below.
+
+
+
+ Optional filter options. Only applicable for the `logs` subscription type.
+
+
+
+ A single contract address or array of addresses to filter logs by. Optional.
+
+
+ Array of topic filters in the same format as `eth_getLogs`. Optional.
+
+
+
+
+**Subscription Types**
+
+| Type | Description | Notification payload |
+| ---- | ----------- | -------------------- |
+| `newHeads` | Fires for each new block header appended to the chain | Block header object |
+| `logs` | Fires for each new log matching the filter criteria | Log object |
+| `newPendingTransactions` | Fires for each new pending transaction hash added to the mempool | Transaction hash string |
+
+**Returns**
+
+
+ A hex-encoded subscription ID. All subsequent event notifications from this subscription include this ID in `params.subscription`.
+
+
+Event notifications arrive as unsolicited JSON-RPC messages with `method: "eth_subscription"`:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "method": "eth_subscription",
+ "params": {
+ "subscription": "0x1887ec8b9589ccad00000000000532da",
+ "result": { ... }
+ }
+}
+```
+
+**Subscribe to new block headers:**
+
+
+```json Request
+{"jsonrpc": "2.0", "method": "eth_subscribe", "params": ["newHeads"], "id": 1}
+```
+
+```json Response
+{"jsonrpc": "2.0", "id": 1, "result": "0x1887ec8b9589ccad00000000000532da"}
+```
+
+```json Event Notification
+{
+ "jsonrpc": "2.0",
+ "method": "eth_subscription",
+ "params": {
+ "subscription": "0x1887ec8b9589ccad00000000000532da",
+ "result": {
+ "number": "0x12ced29",
+ "hash": "0x4b5e8c5d7f2b1a6e9d0c4f8b3e7a2d5c8f1b4e7a0d3c6f9b2e5a8d1c4f7b0e4",
+ "parentHash": "0x3a4e8c5d7f2b1a6e9d0c4f8b3e7a2d5c8f1b4e7a0d3c6f9b2e5a8d1c4f7b0e3",
+ "gasLimit": "0x1c9c380",
+ "gasUsed": "0xa410",
+ "timestamp": "0x6783a5d2",
+ "baseFeePerGas": "0x3b9aca00"
+ }
+ }
+}
+```
+
+
+**Subscribe to contract logs:**
+
+
+```json Request
+{
+ "jsonrpc": "2.0",
+ "method": "eth_subscribe",
+ "params": [
+ "logs",
+ {
+ "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+ "topics": [
+ "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
+ ]
+ }
+ ],
+ "id": 1
+}
+```
+
+```json Response
+{"jsonrpc": "2.0", "id": 1, "result": "0x2a7bc8d4e3f5a6b1c2d3e4f5a6b7c8d9"}
+```
+
+```json Event Notification
+{
+ "jsonrpc": "2.0",
+ "method": "eth_subscription",
+ "params": {
+ "subscription": "0x2a7bc8d4e3f5a6b1c2d3e4f5a6b7c8d9",
+ "result": {
+ "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+ "topics": [
+ "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
+ "0x000000000000000000000000d3cda913deb6f4967b2ef66ae97de114a83bcc01",
+ "0x0000000000000000000000004200000000000000000000000000000000000006"
+ ],
+ "data": "0x0000000000000000000000000000000000000000000000000000000005f5e100",
+ "blockNumber": "0x12ced29",
+ "transactionHash": "0xc903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568239",
+ "transactionIndex": "0x0",
+ "blockHash": "0x4b5e8c5d7f2b1a6e9d0c4f8b3e7a2d5c8f1b4e7a0d3c6f9b2e5a8d1c4f7b0e4",
+ "logIndex": "0x0",
+ "removed": false
+ }
+ }
+}
+```
+
+
+### eth_unsubscribe
+
+Cancels a subscription created by `eth_subscribe`. After cancellation, no further notifications are sent for that subscription ID.
+
+**Parameters**
+
+
+ The hex-encoded subscription ID returned by `eth_subscribe`.
+
+
+**Returns**
+
+
+ `true` if the subscription was successfully cancelled. `false` if the subscription ID was not found (e.g., already cancelled or never existed).
+
+
+
+```json Request
+{
+ "jsonrpc": "2.0",
+ "method": "eth_unsubscribe",
+ "params": ["0x1887ec8b9589ccad00000000000532da"],
+ "id": 1
+}
+```
+
+```json Response (success)
+{"jsonrpc": "2.0", "id": 1, "result": true}
+```
+
+```json Response (not found)
+{"jsonrpc": "2.0", "id": 1, "result": false}
+```
+
diff --git a/docs/docs.json b/docs/docs.json
index 1e9c9816f..9a3afe002 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -101,6 +101,12 @@
"base-chain/quickstart/base-solana-bridge"
]
},
+ {
+ "group": "Reference",
+ "pages": [
+ "base-chain/reference/json-rpc-api"
+ ]
+ },
{
"group": "Network Information",
"pages": [
@@ -118,6 +124,7 @@
"group": "Flashblocks",
"pages": [
"base-chain/flashblocks/apps",
+ "base-chain/flashblocks/api-reference",
"base-chain/flashblocks/node-providers",
"base-chain/flashblocks/docs"
]