> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beaconcha.in/llms.txt
> Use this file to discover all available pages before exploring further.

# MEV Timing

> Returns the MEV timing-game outcome for a single block: the winning relay bid, the earliest later bid that would have beaten it (`first_better_bid`), the highest-value later bid (`best_later_bid`), the value left on the table, and the winning relay and builder.

Resolve a block by number or the keywords "latest" / "finalized". Pair this with [/api/v2/ethereum/validators/proposal-slots](/api-reference/ethereum/validators/proposal-slots) to drill into a specific proposal.

**Note:** MEV relay and timing data is only available on mainnet at this time.

**History:** Relay bid collection began on 2024-06-03 (UTC). Blocks before that date — including all pre-Merge blocks — return status `unknown`, since the absence of relay data means the timing outcome is not known rather than that no MEV occurred.

Data freshness: per-slot relay statistics lag the chain head by roughly 4 hours. A block newer than the latest aggregated slot returns status `pending` until the data catches up.




## OpenAPI

````yaml /v3/bundled.yaml post /api/v2/ethereum/block/mev-timing
openapi: 3.0.4
info:
  title: External Service API
  version: 1.0.3
servers:
  - url: https://beaconcha.in
    description: Production API
security:
  - ApiKeyAuth: []
paths:
  /api/v2/ethereum/block/mev-timing:
    post:
      tags:
        - Block
      summary: MEV Timing
      description: >
        Returns the MEV timing-game outcome for a single block: the winning
        relay bid, the earliest later bid that would have beaten it
        (`first_better_bid`), the highest-value later bid (`best_later_bid`),
        the value left on the table, and the winning relay and builder.


        Resolve a block by number or the keywords "latest" / "finalized". Pair
        this with
        [/api/v2/ethereum/validators/proposal-slots](/api-reference/ethereum/validators/proposal-slots)
        to drill into a specific proposal.


        **Note:** MEV relay and timing data is only available on mainnet at this
        time.


        **History:** Relay bid collection began on 2024-06-03 (UTC). Blocks
        before that date — including all pre-Merge blocks — return status
        `unknown`, since the absence of relay data means the timing outcome is
        not known rather than that no MEV occurred.


        Data freshness: per-slot relay statistics lag the chain head by roughly
        4 hours. A block newer than the latest aggregated slot returns status
        `pending` until the data catches up.
      operationId: GetBlockMevTiming
      requestBody:
        $ref: '#/components/requestBodies/BlockAndChain'
      responses:
        '200':
          $ref: '#/components/responses/BlockMevTiming'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultError'
components:
  requestBodies:
    BlockAndChain:
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/NamedChain'
              - $ref: '#/components/schemas/NamedBlockSelector'
            required:
              - block
          example:
            block:
              view: latest
            chain: mainnet
  responses:
    BlockMevTiming:
      description: Successful response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BlockMevTiming.Container'
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Bad request. Please check your input and try again.
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Unauthorized. Please provide a valid API key.
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: >-
              endpoint not allowed for your subscription tier. upgrade your
              subscription at https://beaconcha.in/pricing.
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: The requested resource was not found.
    MethodNotAllowed:
      description: Method Not Allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'method not allowed: GET. all public API endpoints use POST.'
    RateLimitExceeded:
      description: Rate Limit Exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Rate limit exceeded. Please try again later.
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: internal server error. please try again later.
    DefaultError:
      description: An unexpected error response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: An unexpected error occurred.
  schemas:
    NamedChain:
      type: object
      properties:
        chain:
          $ref: '#/components/schemas/Chain'
    NamedBlockSelector:
      type: object
      properties:
        block:
          $ref: '#/components/schemas/BlockSelector'
      required:
        - block
    BlockMevTiming.Container:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/BlockMevTiming.Data'
      description: Response containing the MEV timing-game outcome for a single block.
      required:
        - data
    Error:
      type: object
      properties:
        error:
          type: string
    Chain:
      type: string
      enum:
        - mainnet
        - hoodi
      default: mainnet
      description: The Ethereum chain to query.
    BlockSelector:
      description: |
        Specify a block using one of the following methods.
        - Block number
        - View: "latest" or "finalized" 
      oneOf:
        - $ref: '#/components/schemas/BlockByNumber'
        - $ref: '#/components/schemas/BlockByChainView'
      default: latest
    BlockMevTiming.Data:
      type: object
      description: Timing-game outcome for a single block.
      properties:
        status:
          $ref: '#/components/schemas/MevTimingStatus'
        winning_bid:
          allOf:
            - $ref: '#/components/schemas/MevWinningBid'
          nullable: true
          description: >-
            The winning relay bid for the slot, or `null` when `status` is
            `no_mev`, `unknown`, or `pending`.
        first_better_bid:
          allOf:
            - $ref: '#/components/schemas/MevBid'
          nullable: true
          description: >-
            The earliest bid that arrived after the winning bid and exceeded its
            value — the smallest delay that would have captured more MEV. `null`
            if no later bid beat the winning one.
        best_later_bid:
          allOf:
            - $ref: '#/components/schemas/MevBid'
          nullable: true
          description: >-
            The highest-value bid that arrived after the winning bid — the
            maximum additional MEV obtainable by delaying the proposal. `null`
            when no bid arrived after the winning one. Because "winning" is
            determined by which bid's block was actually included on-chain (not
            by being the highest bid ever seen for the slot), this value is
            occasionally lower than `winning_bid.value` when no later bid
            matched or exceeded it.
        missed_value:
          allOf:
            - $ref: '#/components/schemas/wei'
          nullable: true
          description: >-
            Additional MEV (in wei) the proposer could have captured by waiting
            for `best_later_bid`, computed as `max(0, best_later_bid.value −
            winning_bid.value)`. `null` when there is no winning bid.
        relay_count:
          type: integer
          minimum: 0
          nullable: true
          description: >-
            Number of distinct relays that submitted a bid for the slot. `null`
            when there is no winning bid.
        bid_count:
          type: integer
          minimum: 0
          nullable: true
          description: >-
            Total number of bids recorded for the slot. `null` when there is no
            winning bid.
      required:
        - status
        - winning_bid
        - first_better_bid
        - best_later_bid
        - missed_value
        - relay_count
        - bid_count
    BlockByNumber:
      title: Number
      type: object
      properties:
        number:
          $ref: '#/components/schemas/Block'
      required:
        - number
    BlockByChainView:
      title: View
      type: object
      properties:
        view:
          $ref: '#/components/schemas/ChainView'
      required:
        - view
    MevTimingStatus:
      type: string
      enum:
        - on_time_mev
        - timing_games
        - aggressive_tg
        - no_mev
        - unknown
        - pending
      x-enum-varnames:
        - MevTimingStatusOnTimeMev
        - MevTimingStatusTimingGames
        - MevTimingStatusAggressiveTg
        - MevTimingStatusNoMev
        - MevTimingStatusUnknown
        - MevTimingStatusPending
      example: timing_games
      description: >
        Classification of a block's MEV timing behaviour, derived from how long
        after the slot start the winning relay bid arrived.


        - `on_time_mev`: winning bid arrived ≤ 1200 ms after slot start — MEV
        was captured without delaying the proposal.

        - `timing_games`: winning bid arrived 1201–2600 ms after slot start —
        the proposer delayed to capture more MEV.

        - `aggressive_tg`: winning bid arrived > 2600 ms after slot start —
        aggressive timing games with higher orphan risk.

        - `no_mev`: no relay bids were observed for this slot at all — the block
        was built locally (or by a proposer not registered with any tracked
        relay).

        - `unknown`: relay bids were observed for this slot, but the winning
        payload could not be identified — either our periodic relay polling
        missed it, or the slot predates relay bid collection. The underlying
        block may still be an MEV block; `unknown` is not evidence either way.

        - `pending`: the slot is newer than the latest aggregated slot, so its
        timing outcome has not been computed yet. Retry once relay data catches
        up (per-slot statistics lag the chain head by roughly 4 hours).
    MevWinningBid:
      type: object
      description: >-
        The winning relay bid for a slot, including the relay that delivered it
        and the block builder.
      properties:
        value:
          allOf:
            - $ref: '#/components/schemas/wei'
          description: Winning bid value in wei.
        slot_offset_ms:
          $ref: '#/components/schemas/SlotOffsetMs'
        relays:
          type: array
          items:
            type: string
          description: >-
            The relay(s) that delivered the winning block. Currently only the
            first relay observed to deliver the block is recorded, so this array
            contains at most one entry today — it is empty if the underlying
            relay-bid record for this slot is no longer available. It may
            include additional relays in the future without being a breaking
            change.
        builder_pubkey:
          type: string
          pattern: ^0x[a-fA-F0-9]{96}$
          nullable: true
          description: >-
            BLS public key of the block builder that produced the winning block,
            or `null` if unknown. Taken from the relay data API, excluding
            `getHeader` observations.
      required:
        - value
        - slot_offset_ms
        - relays
        - builder_pubkey
    MevBid:
      type: object
      description: >-
        A relay bid summarised by its value and arrival time relative to slot
        start.
      properties:
        value:
          allOf:
            - $ref: '#/components/schemas/wei'
          description: Bid value in wei.
        slot_offset_ms:
          $ref: '#/components/schemas/SlotOffsetMs'
        status:
          allOf:
            - $ref: '#/components/schemas/MevTimingStatus'
          description: >-
            Timing classification of this bid's `slot_offset_ms`. For an
            observed bid this is always one of `on_time_mev`, `timing_games`, or
            `aggressive_tg`.
      required:
        - value
        - slot_offset_ms
        - status
    wei:
      type: string
      description: Amount in wei (1 ETH = 10^18 wei)
      pattern: ^(0|-?[1-9][0-9]*)$
    Block:
      type: integer
      minimum: 0
      description: Block by number.
    ChainView:
      type: string
      enum:
        - latest
        - finalized
      description: >
        - "latest": Refers to the most recent block, which may be subject to
        reorganization.

        - "finalized": Refers to the latest block that has been finalized and is
        not subject to change.
    SlotOffsetMs:
      type: integer
      description: >-
        Time of the bid relative to the slot's scheduled start, in milliseconds
        (`0` = on time). Negative values indicate the bid arrived before the
        slot start; positive values indicate it arrived after. Larger positive
        values reflect more aggressive timing games.
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: >-
        Authorization header with value: Bearer YOUR_TOKEN. Refer to the [API
        Keys](/api/overview#api-keys) section to create your API key.

````