Flashblocks API Reference - Base Documentation

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 remain fully supported.

See Flashblocks 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.

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

blockParameter

string

required

Use "pending" to retrieve the latest Flashblock. Also accepts "latest", "safe", "finalized", or a specific block number.

fullTransactions

boolean

required

If true, returns full transaction objects. If false, returns only transaction hashes.

Returns

result

object | null

A block object reflecting the current preconfirmed state. See eth_getBlockByNumber for full field descriptions.

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}'

eth_getTransactionReceipt

Returns the receipt for a preconfirmed transaction before it is included in a finalized block.

Parameters

transactionHash

string

required

The 32-byte transaction hash.

Returns

result

object | null

A transaction receipt object for the preconfirmed transaction, or null if not found. See eth_getTransactionReceipt for full field descriptions.

curl https://sepolia-preconf.base.org \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getTransactionReceipt","params":["0x..."],"id":1}'

eth_getBalance

Returns the ETH balance of an address in the latest preconfirmed Flashblock state.

Parameters

address

string

required

The 20-byte address to query.

blockParameter

string

required

Use "pending" to query preconfirmed state.

Returns

result

string

The balance in wei as a hexadecimal string.

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}'

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

address

string

required

The 20-byte account address.

blockParameter

string

required

Use "pending" to include preconfirmed transactions in the nonce count.

Returns

result

string

The transaction count (nonce) as a hexadecimal integer.

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}'

eth_getTransactionByHash

Returns a preconfirmed transaction before it is included in a finalized block.

Parameters

transactionHash

string

required

The 32-byte transaction hash.

Returns

result

object | null

A transaction object, or null if not found. See eth_getTransactionByHash for full field descriptions.

curl https://sepolia-preconf.base.org \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getTransactionByHash","params":["0x..."],"id":1}'

eth_call

Executes a contract call against the latest preconfirmed Flashblock state.

Parameters

transactionObject

object

required

The transaction call object. See eth_call for field details.

blockParameter

string

required

Use "pending" to execute the call against preconfirmed state.

Returns

result

string

Hex-encoded return data from the contract call.

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}'

eth_estimateGas

Estimates gas for a transaction against the latest preconfirmed Flashblock state.

Parameters

transactionObject

object

required

The transaction object. See eth_estimateGas for field details.

blockParameter

string

required

Use "pending" to estimate against preconfirmed state.

Returns

result

string

Estimated gas as a hexadecimal integer.

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}'

eth_getLogs

Returns logs from preconfirmed Flashblock data by setting "toBlock" to "pending".

Parameters

filterObject

object

required

The log filter object.

Show Filter object fields

fromBlock

string

Start of the block range. Use "latest" for the most recent mined block.

toBlock

string

Use "pending" to include logs from the current Flashblock.

address

string | array

A single contract address or array of addresses to filter by. Optional.

topics

array

Array of topic filters. Same format as in eth_getLogs. Optional.

Returns

result

array

An array of log objects. See eth_getLogs for full field descriptions.

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}'

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

simulationPayload

object

required

The simulation configuration.

Show Simulation payload fields

blockStateCalls

array

required

Array of block state call objects. Each object represents one simulated block.

Show Block state call fields

calls

array

Array of transaction call objects to simulate within this block.

stateOverrides

object

Per-address state overrides applied before simulation (e.g., balance, nonce, code, storage). Optional.

blockOverrides

object

Block-level overrides (e.g., number, timestamp). Optional.

traceTransfers

boolean

If true, ETH transfer events are included as logs in the result. Optional; defaults to false.

validation

boolean

If true, transaction validation (nonce, balance) is enforced. Optional; defaults to false.

blockParameter

string

required

Use "pending" to simulate against the current Flashblock state.

Returns

result

array

Array of simulated block results, one per entry in blockStateCalls.

Show Block result fields

calls

array

Array of individual call results.

Show Call result fields

status

string

"0x1" for success, "0x0" for failure.

gasUsed

string

Gas used by this call as a hexadecimal integer.

returnData

string

Hex-encoded return data from the call.

logs

array

Logs emitted by this call (including ETH transfer logs if traceTransfers is true).

error

string

Revert reason if the call failed. Optional.

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
  }'

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 minimum client version v0.3.0.

Parameters

transactionHash

string

required

The 32-byte transaction hash to query.

Returns

result

object

Transaction status object.

Show Status fields

status

string

"Known" if the transaction is present in the mempool. "Unknown" if it has not been seen by this node.

curl https://sepolia-preconf.base.org \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"base_transactionStatus","params":["0x..."],"id":1}'

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 minimum client version v0.3.1.

Flashblocks Subscription Types

In addition to the standard subscription types (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

subscriptionType

string

required

Must be "newFlashblockTransactions".

full

boolean

Optional. If true, each notification includes the full transaction object and associated logs. If false or omitted, notifications contain minimal transaction data.

Returns

result

string

Hex-encoded subscription ID.

{"jsonrpc": "2.0", "id": 1, "method": "eth_subscribe", "params": ["newFlashblockTransactions"]}

pendingLogs

Subscribe to receive logs from preconfirmed transactions matching an optional filter. Useful for monitoring contract events with sub-block latency.

Parameters

subscriptionType

string

required

Must be "pendingLogs".

Optional log filter.

Show Filter options

address

string | array

A single contract address or array of addresses to filter by. Optional.

topics

array

Array of topic filters in the same format as eth_getLogs. Optional.

Returns

result

string

Hex-encoded subscription ID.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_subscribe",
  "params": [
    "pendingLogs",
    {
      "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "topics": [
        "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
      ]
    }
  ]
}

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

subscriptionType

string

required

Must be "newFlashblocks".

Returns

result

string

Hex-encoded subscription ID.

{"jsonrpc": "2.0", "id": 1, "method": "eth_subscribe", "params": ["newFlashblocks"]}

JavaScript example:

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.

Parameters

subscriptionId

string

required

The hex-encoded subscription ID returned by eth_subscribe.

Returns

result

boolean

true if successfully cancelled, false if the subscription ID was not found.

{"jsonrpc": "2.0", "method": "eth_unsubscribe", "params": ["0x1887ec8b9589ccad00000000000532da"], "id": 1}

Quickstart

Reference

Network Information

Flashblocks

Node Operators

Builder Codes

Tools

Security

​Endpoints

​Standard Methods with Flashblocks Behavior

​eth_getBlockByNumber

​Parameters

​Returns

​eth_getTransactionReceipt

​Parameters

​Returns

​eth_getBalance

​Parameters

​Returns

​eth_getTransactionCount

​Parameters

​Returns

​eth_getTransactionByHash

​Parameters

​Returns

​eth_call

​Parameters

​Returns

​eth_estimateGas

​Parameters

​Returns

​eth_getLogs

​Parameters

​Returns

​Flashblocks-Specific Methods

​eth_simulateV1

​Parameters

​Returns

​base_transactionStatus Beta

​Parameters

​Returns

​WebSocket Subscription Methods

​Flashblocks Subscription Types

​newFlashblockTransactions

​Parameters

​Returns

​pendingLogs

​Parameters

​Returns

​newFlashblocks

​Parameters

​Returns

​eth_unsubscribe

​Parameters

​Returns

Endpoints

Standard Methods with Flashblocks Behavior

eth_getBlockByNumber

Parameters

Returns

eth_getTransactionReceipt

Parameters

Returns

eth_getBalance

Parameters

Returns

eth_getTransactionCount

Parameters

Returns

eth_getTransactionByHash

Parameters

Returns

eth_call

Parameters

Returns

eth_estimateGas

Parameters

Returns

eth_getLogs

Parameters

Returns

Flashblocks-Specific Methods

eth_simulateV1

Parameters

Returns

base_transactionStatus Beta

Parameters

Returns

WebSocket Subscription Methods

Flashblocks Subscription Types

newFlashblockTransactions

Parameters

Returns

pendingLogs

Parameters

Returns

newFlashblocks

Parameters

Returns

eth_unsubscribe

Parameters

Returns