Flashblocks API Reference

This page covers what is unique to Flashblocks: the preconf endpoints, Flashblocks-only methods, real-time WebSocket subscriptions, and the infrastructure stream schema.

All standard JSON-RPC methods work as-is against a Flashblocks endpoint — use the "pending" block tag to read preconfirmed state.

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.

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}

Infrastructure Stream

The raw Flashblocks infrastructure stream is the upstream source that Flashblocks-aware RPC nodes consume.

Applications should not connect directly to the infrastructure stream. These endpoints are for node infrastructure only. App developers should use the WebSocket subscription methods above via a Flashblocks-aware RPC provider.

Network	URL
Mainnet	`wss://mainnet.flashblocks.base.org/ws`
Sepolia	`wss://sepolia.flashblocks.base.org/ws`

Flashblock Object

The root structure of each infrastructure stream message.

payload_id

string

Unique identifier for the block being built. Remains consistent across all 10 Flashblocks within a single full block.

index

number

Flashblock index within the current block (0–10). Index 0 contains system transactions only; indexes 1–10 contain user transactions.

base

Base

Block header properties. Only present when index is 0. See Base Object.

diff

Diff

Block differences/updates for this Flashblock. See Diff Object.

metadata

Metadata

Additional data including balance updates and transaction receipts. Not stable — may change without notice. See Metadata Object.

Base Object

Contains full block header properties. Only present in Index 0 (the first Flashblock of each full block).

parent_hash

string

Hash of the parent block.

fee_recipient

string

Address receiving transaction fees (coinbase).

block_number

string

Block number in hex format.

gas_limit

string

Maximum gas allowed in this block (hex).

timestamp

string

Unix timestamp of block creation (hex).

base_fee_per_gas

string

Base fee per gas unit (hex, EIP-1559).

prev_randao

string

Previous RANDAO value for randomness.

extra_data

string

Arbitrary data included by the block builder.

Diff Object

Contains the block state changes for this specific Flashblock. Present in every message.

state_root

string

Merkle root of the state trie after applying this Flashblock’s transactions.

block_hash

string

Hash of the block at this Flashblock index. Changes with each Flashblock as more transactions are added.

gas_used

string

Cumulative gas used up to and including this Flashblock (hex).

blob_gas_used

string

Cumulative blob gas used (hex, EIP-4844).

transactions

string[]

Array of RLP-encoded transaction data included in this Flashblock.

withdrawals

array

Validator withdrawals included in this Flashblock (typically empty on L2).

receipts_root

string

Merkle root of transaction receipts.

logs_bloom

string

Bloom filter for quick log searching.

withdrawals_root

string

Merkle root of withdrawals.

Metadata Object

The metadata object is not stable.Fields may be added, modified, or removed without prior notice. Do not build production dependencies on it — use the diff object or query finalized block data via RPC instead.

block_number

number

Block number as a decimal integer.

new_account_balances

object

Map of addresses to their updated ETH balances (hex). Only includes accounts whose balances changed in this Flashblock.

receipts

object

Map of transaction hashes to their Receipt objects.

Receipt Object

Transaction execution result. Check which type is present to determine the transaction type: Legacy, Access List, EIP-1559, Custom/Experimental (Deposit)

type

string

Transaction type: 0x0 Legacy, 0x1 Access List, 0x2 EIP-1559, 0x7e Deposit (L1→L2).

status

string

Transaction status: 0x1 for success, 0x0 for failure.

cumulativeGasUsed

string

Total gas used in the block up to and including this transaction (hex).

logs

Log[]

Array of event logs emitted by the transaction. See Log Object.

logsBloom

string

Bloom filter for the logs in this receipt.

transactionIndex

string

Index of the transaction within the block (hex).

Log Object

address

string

Contract address that emitted the event.

topics

string[]

Array of indexed event parameters. The first topic is typically the event signature hash.

data

string

ABI-encoded non-indexed event parameters.

Complete Examples

Index 0 (initial) — includes the base object:

{
  "payload_id": "0x03997352d799c31a",
  "index": 0,
  "base": {
    "parent_hash": "0x9edc29b8b0a1e31d28616e40c16132ad0d58faa8bb952595b557526bdb9a960a",
    "fee_recipient": "0x4200000000000000000000000000000000000011",
    "block_number": "0x158a0e9",
    "gas_limit": "0x3938700",
    "timestamp": "0x67bf8332",
    "base_fee_per_gas": "0xfa"
  },
  "diff": {
    "state_root": "0x208fd63edc0681161105f27d03daf9f8c726d8c94e584a3c0696c98291c24333",
    "block_hash": "0x5c330e55a190f82ea486b61e5b12e27dfb4fb3cecfc5746886ef38ca1281bce8",
    "gas_used": "0xab3f",
    "transactions": ["0x7ef8f8a0b4afc0b7ce10e150801bbaf08ac33fecb0f38311793abccb022120d321c6d276..."],
    "withdrawals": []
  },
  "metadata": {
    "block_number": 22585577,
    "new_account_balances": {
      "0x000f3df6d732807ef1319fb7b8bb8522d0beac02": "0x0"
    },
    "receipts": {
      "0x07d7f06b06fea714c1d1d446efa2790c6970aa74ee006186a32b5b7dd8ca2d82": {
        "type": "0x7e",
        "status": "0x1",
        "cumulativeGasUsed": "0xab3f",
        "logs": [],
        "logsBloom": "0x00000000...",
        "transactionIndex": "0x0"
      }
    }
  }
}

Index 1–10 (diff only) — no base object:

{
  "payload_id": "0x03997352d799c31a",
  "index": 4,
  "diff": {
    "state_root": "0x7a8f45038665072f382730e689f4a1561835c9987fca8942fa95872fb9367eaa",
    "block_hash": "0x9b32f7a14cbd1efc8c2c5cad5eb718ec9e0c5da92c3ba7080f8d4c49d660c332",
    "gas_used": "0x1234f",
    "transactions": ["0x02f90133...", "0x02f90196..."],
    "withdrawals": []
  },
  "metadata": {
    "block_number": 22585577,
    "new_account_balances": {
      "0x4200000000000000000000000000000000000015": "0x1234"
    },
    "receipts": {
      "0x7c69632dc315f13a...": {
        "type": "0x2",
        "status": "0x1",
        "cumulativeGasUsed": "0x1234f",
        "logs": [],
        "logsBloom": "0x00000000...",
        "transactionIndex": "0x1"
      }
    }
  }
}

Quickstart

Reference

Network Information

Flashblocks

Node Operators

Builder Codes

Security

Endpoints

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

Infrastructure Stream

Flashblock Object

Base Object

Diff Object

Metadata Object

Receipt Object

Log Object

Complete Examples

Quickstart

Reference

Network Information

Flashblocks

Node Operators

Builder Codes

Security

​Endpoints

​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

​Infrastructure Stream

​Flashblock Object

​Base Object

​Diff Object

​Metadata Object

​Receipt Object

​Log Object

​Complete Examples

Endpoints

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

Infrastructure Stream

Flashblock Object

Base Object

Diff Object

Metadata Object

Receipt Object

Log Object

Complete Examples