Skip to main content
This page documents the Flashblocks WebSocket API used for infrastructure-to-node data syncing.
Applications should not connect directly to wss://mainnet.flashblocks.base.org/ws. This endpoint is reserved for node infrastructure. Apps should query their RPC node or node provider (e.g., QuickNode, Alchemy) for Flashblocks data instead. See the App Integration guide for implementation details.
For background on how Flashblocks work and the base component, see the Flashblocks Architecture.

​
WebSocket Endpoints

NetworkURL
Mainnetwss://mainnet.flashblocks.base.org/ws
Sepoliawss://sepolia.flashblocks.base.org/ws
These endpoints are rate-limited (max 10 connections per IP).
Applications should avoid hard dependencies on the WebSocket stream. RPCs provide stable behavior and automatic failover to regular blocks if Flashblocks are unavailable.

​
Message Format

Messages are delivered as Brotli-compressed binary data. Decompress before parsing as JSON. To minimize bandwidth, each Flashblock only includes diff data from the previous Flashblock:
  • Index 0 (initial): Contains the base object with full block properties, plus the first diff
  • Index 1-10 (subsequent): Contains only diff data (new transactions, updated state root, gas used)

​
Schema

​
Flashblock Object

The root structure of each WebSocket 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. This object is not stable and may change without notice. See Metadata Object.
Example:
flashblock.json
{
  "payload_id": "0x03997352d799c31a",
  "index": 0,
  "base": { ... },
  "diff": { ... },
  "metadata": { ... }
}

​
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.
Example:
base.json
{
  "parent_hash": "0x9edc29b8b0a1e31d28616e40c16132ad0d58faa8bb952595b557526bdb9a960a",
  "fee_recipient": "0x4200000000000000000000000000000000000011",
  "block_number": "0x158a0e9",
  "gas_limit": "0x3938700",
  "timestamp": "0x67bf8332",
  "base_fee_per_gas": "0xfa",
  "prev_randao": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "extra_data": "0x"
}

​
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.
Example:
diff.json
{
  "state_root": "0x208fd63edc0681161105f27d03daf9f8c726d8c94e584a3c0696c98291c24333",
  "block_hash": "0x5c330e55a190f82ea486b61e5b12e27dfb4fb3cecfc5746886ef38ca1281bce8",
  "gas_used": "0xab3f",
  "blob_gas_used": "0x0",
  "transactions": [
    "0x02f90133..."
  ],
  "withdrawals": [],
  "receipts_root": "0xa83fdcff1e433d49",
  "logs_bloom": "0x00000000...",
  "withdrawals_root": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421"
}

​
Metadata Object

The metadata object is not stable. Fields may be added, modified, or removed without prior notice. Do not build production dependencies on the structure or presence of any metadata fields. If you require stable data, use the diff object or query finalized block data via RPC.
Contains additional block metadata, including balance updates and transaction receipts.

​
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. Contains execution results for transactions in this Flashblock.
Example:
metadata.json
{
  "block_number": 22585577,
  "new_account_balances": {
    "0x000f3df6d732807ef1319fb7b8bb8522d0beac02": "0x0",
    "0x4200000000000000000000000000000000000015": "0x1234"
  },
  "receipts": {
    "0x07d7f06b06fea714c1d1d446efa2790c6970aa74ee006186a32b5b7dd8ca2d82": { ... }
  }
}

​
Receipt Object

Transaction execution result. Receipts come in two formats: EIP-1559 (modern) or Legacy. Check which field is present to determine the type.

​
Eip1559
ReceiptData
Receipt data for EIP-1559 transactions. See ReceiptData.
​
Legacy
ReceiptData
Receipt data for legacy transactions. See ReceiptData.
​
Deposit
ReceiptData
Receipt data for L1→L2 deposit transactions. See ReceiptData.
Example:
receipt.json
{
  "Eip1559": {
    "status": "0x1",
    "cumulativeGasUsed": "0x1234f",
    "logs": []
  }
}

​
ReceiptData Object

The actual receipt information, regardless of transaction type.

​
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.
​
depositNonce
string
Nonce for deposit transactions (L1→L2 only).
Example:
receiptdata.json
{
  "status": "0x1",
  "cumulativeGasUsed": "0x1234f",
  "logs": [
    {
      "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"],
      "data": "0x0000000000000000000000000000000000000000000000000000000000001234"
    }
  ]
}

​
Log Object

Event log emitted by a smart contract. Crucial for detecting swaps, transfers, and other contract events.

​
address
string
Contract address that emitted the event.
​
topics
string[]
Array of indexed event parameters. The first topic is typically the event signature hash (e.g., Transfer(address,address,uint256)).
​
data
string
ABI-encoded non-indexed event parameters.
Example:
log.json
{
  "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "topics": [
    "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
    "0x000000000000000000000000abc123...",
    "0x000000000000000000000000def456..."
  ],
  "data": "0x0000000000000000000000000000000000000000000000000000000000001234"
}

​
Complete Example

​
Index 0 Response (Initial)

The first Flashblock of each full block includes the base object: Example: 
{
  "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": {
        "Deposit": {
          "status": "0x1",
          "cumulativeGasUsed": "0xab3f",
          "logs": [],
          "depositNonce": "0x158a0ea"
        }
      }
    }
  }
}

​
Index 1-10 Response (Diff Only)

Subsequent Flashblocks only include the diff (no base object): Example: 
{
  "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": {
      "0x000f3df6d732807ef1319fb7b8bb8522d0beac02": "0x0",
      "0x4200000000000000000000000000000000000015": "0x1234"
    },
    "receipts": {
      "0x7c69632dc315f13a...": {
        "Eip1559": {
          "status": "0x1",
          "cumulativeGasUsed": "0x1234f",
          "logs": []
        }
      }
    }
  }
}

​
Further Resources