Investigate a Block

Overview

Block-level MEV analysis answers two different questions:

What was the outcome? The block timing endpoint summarizes the selected bid and the best alternatives that arrived later.
What did the proposer have available? The bid endpoint returns every recorded relay bid in arrival order for research and auditing.

API Endpoints: This guide uses /api/v2/ethereum/block/mev-timing and /api/v2/ethereum/block/mev-bids.

The timing summary is available to all API plans. The full bid ladder requires a Scale or Enterprise plan.

The bid ladder is collected from offchain relay APIs and streams. Relay-reported arrival times, identities, and bids cannot be independently verified from onchain data, and missing or inconsistent relay observations can make the recorded ladder incomplete. Verify onchain fields such as the included block hash separately.

Step 1: Fetch the Timing Outcome

Resolve a block by execution-layer block number, or use the latest or finalized view. A recent latest block will usually return pending because per-slot MEV aggregates lag the chain head by about 4 hours.

curl --request POST \
  --url https://beaconcha.in/api/v2/ethereum/block/mev-timing \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "chain": "mainnet",
  "block": {
    "number": 25378998
  }
}
'

An identified relay winner produces a response like this:

{
  "data": {
    "status": "timing_games",
    "winning_bid": {
      "value": "118000000000000000",
      "slot_offset_ms": 2460,
      "relays": ["example-relay"],
      "builder_pubkey": null
    },
    "first_better_bid": {
      "value": "121000000000000000",
      "slot_offset_ms": 2518,
      "status": "timing_games"
    },
    "best_later_bid": {
      "value": "139000000000000000",
      "slot_offset_ms": 2784,
      "status": "aggressive_tg"
    },
    "missed_value": "21000000000000000",
    "relay_count": 8,
    "bid_count": 436
  }
}

This is an illustrative response. Bid values, relay names, counts, and builder keys depend on the selected block.

Interpret the Outcome

See the block timing API reference. In this workflow, compare the included winner with the earliest better bid and the best later bid to distinguish the minimum additional wait from the maximum later opportunity observed.

missed_value is hindsight, not guaranteed revenue. The proposer could not know which future bid would be best, and waiting for it would have increased propagation and orphan risk.

For non-classified outcomes, follow the status-specific behavior in the API reference. Retry provisional results, and do not reinterpret unknown coverage as a non-MEV outcome.

Step 2: Fetch the Bid Ladder

The full bid ladder is ordered by arrival time and can contain many thousands of rows. Filter to the timing window you need, request up to 200 bids per page, and follow paging.next_cursor until it is empty.

curl --request POST \
  --url https://beaconcha.in/api/v2/ethereum/block/mev-bids \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "chain": "mainnet",
  "block": {
    "number": 25378998
  },
  "slot_offset_ms_range": {
    "min": 2400,
    "max": 4000
  },
  "page_size": 200
}
'

See the block MEV bids API reference.

Audit the Alternatives with Python

This script fetches the summary, retrieves every later bid, and independently checks the earliest better and best later values. It keeps wei as integers until formatting the final ETH amounts.

import os
from decimal import Decimal

import requests

BASE_URL = "https://beaconcha.in/api/v2/ethereum"
BLOCK_NUMBER = 25378998
HEADERS = {
    "Authorization": f"Bearer {os.environ['BEACONCHAIN_API_KEY']}",
    "Content-Type": "application/json",
}


def post(path, payload):
    response = requests.post(
        f"{BASE_URL}/{path}", headers=HEADERS, json=payload, timeout=30
    )
    response.raise_for_status()
    return response.json()


selector = {"chain": "mainnet", "block": {"number": BLOCK_NUMBER}}
summary = post("block/mev-timing", selector)["data"]
winner = summary["winning_bid"]

if winner is None:
    raise SystemExit(f"No identified winner: {summary['status']}")

cursor = ""
bids = []

while True:
    payload = {
        **selector,
        "slot_offset_ms_range": {
            "min": winner["slot_offset_ms"],
            "max": 4000,
        },
        "page_size": 200,
    }
    if cursor:
        payload["cursor"] = cursor

    page = post("block/mev-bids", payload)
    if not page["ready"]:
        raise SystemExit("Bid data is still processing; retry later")

    bids.extend(page["data"])
    cursor = page.get("paging", {}).get("next_cursor", "")
    if not cursor:
        break

later_bids = [
    bid
    for bid in bids
    if bid["slot_offset_ms"] is not None
    and bid["slot_offset_ms"] > winner["slot_offset_ms"]
]
winning_value = int(winner["value"])
better_bids = [bid for bid in later_bids if int(bid["value"]) > winning_value]

first_better = min(better_bids, key=lambda bid: bid["slot_offset_ms"], default=None)
best_later = max(later_bids, key=lambda bid: int(bid["value"]), default=None)


def eth(wei):
    return Decimal(wei) / Decimal(10**18)


print("status:", summary["status"])
print("winner:", eth(winner["value"]), "ETH at", winner["slot_offset_ms"], "ms")
print("first better:", first_better)
print("best later:", best_later)
print("missed value:", eth(summary["missed_value"]), "ETH")

Audit the Alternatives with JavaScript

This Node.js 18+ example uses BigInt so bid values remain exact.

const baseUrl = 'https://beaconcha.in/api/v2/ethereum'
const blockNumber = 25378998
const headers = {
  Authorization: `Bearer ${process.env.BEACONCHAIN_API_KEY}`,
  'Content-Type': 'application/json',
}

async function post(path, payload) {
  const response = await fetch(`${baseUrl}/${path}`, {
    method: 'POST',
    headers,
    body: JSON.stringify(payload),
  })

  if (!response.ok) {
    throw new Error(`${response.status} ${await response.text()}`)
  }

  return response.json()
}

const selector = { chain: 'mainnet', block: { number: blockNumber } }
const { data: summary } = await post('block/mev-timing', selector)
const winner = summary.winning_bid

if (!winner) {
  throw new Error(`No identified winner: ${summary.status}`)
}

let cursor = ''
const bids = []

do {
  const payload = {
    ...selector,
    slot_offset_ms_range: {
      min: winner.slot_offset_ms,
      max: 4000,
    },
    page_size: 200,
    ...(cursor && { cursor }),
  }
  const page = await post('block/mev-bids', payload)

  if (!page.ready) {
    throw new Error('Bid data is still processing; retry later')
  }

  bids.push(...page.data)
  cursor = page.paging?.next_cursor ?? ''
} while (cursor)

const laterBids = bids.filter(bid =>
  bid.slot_offset_ms !== null
  && bid.slot_offset_ms > winner.slot_offset_ms,
)
const winningValue = BigInt(winner.value)
const betterBids = laterBids.filter(bid => BigInt(bid.value) > winningValue)
const firstBetter = betterBids.reduce((first, bid) =>
  !first || bid.slot_offset_ms < first.slot_offset_ms ? bid : first,
null)
const bestLater = laterBids.reduce((best, bid) =>
  !best || BigInt(bid.value) > BigInt(best.value) ? bid : best,
null)

console.log({
  status: summary.status,
  winner,
  first_better: firstBetter,
  best_later: bestLater,
  missed_value_wei: summary.missed_value,
})

Relay observations can contain duplicate economic bids from different sources or relays. The timing summary uses beaconcha.in’s canonical aggregation. Treat the raw ladder as offchain observational audit data, not as a complete or independently verifiable record and not as a drop-in replacement for the summary fields.

Best Practices

Start with the Summary

Use block/mev-timing first. Fetch the full ladder only when the outcome needs deeper investigation.

Filter Before Paging

Restrict slot_offset_ms_range to the relevant interval to avoid downloading an unnecessarily large ladder.

Preserve Wei Exactly

Parse values with Python integers, Decimal, JavaScript BigInt, or another arbitrary-precision type.

Respect Readiness

Retry pending summaries and ready: false ladders after the roughly four-hour processing lag.

MEV Analysis Introduction — Endpoint selection, timing bands, and freshness
Compare MEV Timing — Find aggregate outliers before drilling into blocks
MEV Timing Games — Winning, first better, and best later bids explained
API Pagination — Cursor handling for long bid ladders

Introduction

V2 API Docs

V1 API Docs

Overview

Step 1: Fetch the Timing Outcome

Interpret the Outcome

Step 2: Fetch the Bid Ladder

Audit the Alternatives with Python

Audit the Alternatives with JavaScript

Best Practices

Start with the Summary

Filter Before Paging

Preserve Wei Exactly

Respect Readiness

​Overview

​Step 1: Fetch the Timing Outcome

​Interpret the Outcome

​Step 2: Fetch the Bid Ladder

​Audit the Alternatives with Python

​Audit the Alternatives with JavaScript

​Best Practices

Start with the Summary

Filter Before Paging

Preserve Wei Exactly

Respect Readiness

​Related Resources

Overview

Step 1: Fetch the Timing Outcome

Interpret the Outcome

Step 2: Fetch the Bid Ladder

Audit the Alternatives with Python

Audit the Alternatives with JavaScript

Best Practices

Related Resources