> ## 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 Bids

> Returns the full per-relay bid ladder for a single block's slot — every recorded relay bid with its value, arrival time, relay, builder, and source. Intended for research and auditing.

Results are ordered by arrival time and paginated. An optional `slot_offset_ms_range` filters bids by their slot offset.

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

**History:** Relay bid collection began on 2024-06-03 (UTC). No bids are recorded for slots before that date — including all pre-Merge blocks — so the bid ladder is empty for them.

Data freshness: per-slot relay statistics lag the chain head by roughly 4 hours.

**Premium Endpoint:** This endpoint requires a Scale or Enterprise plan.




## OpenAPI

````yaml /v3/bundled.yaml post /api/v2/ethereum/block/mev-bids
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-bids:
    post:
      tags:
        - Block
      summary: 💎 MEV Bids
      description: >
        Returns the full per-relay bid ladder for a single block's slot — every
        recorded relay bid with its value, arrival time, relay, builder, and
        source. Intended for research and auditing.


        Results are ordered by arrival time and paginated. An optional
        `slot_offset_ms_range` filters bids by their slot offset.


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


        **History:** Relay bid collection began on 2024-06-03 (UTC). No bids are
        recorded for slots before that date — including all pre-Merge blocks —
        so the bid ladder is empty for them.


        Data freshness: per-slot relay statistics lag the chain head by roughly
        4 hours.


        **Premium Endpoint:** This endpoint requires a Scale or Enterprise plan.
      operationId: GetBlockMevBids
      requestBody:
        $ref: '#/components/requestBodies/blockMevBids'
      responses:
        '200':
          $ref: '#/components/responses/BlockMevBids'
        '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:
    blockMevBids:
      x-go-name: BlockMevBidsRequestBody
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BlockMevBidsRequest'
          example:
            block:
              view: latest
            chain: mainnet
            page_size: 25
  responses:
    BlockMevBids:
      description: Successful response.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BlockMevBid.ContainerList'
              - $ref: '#/components/schemas/PagingTemplate'
              - $ref: '#/components/schemas/DataReadinessTemplate'
            description: >-
              Paginated response containing the relay bid ladder for the block's
              slot.
    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:
    BlockMevBidsRequest:
      allOf:
        - $ref: '#/components/schemas/NamedChain'
        - $ref: '#/components/schemas/NamedBlockSelector'
        - type: object
          properties:
            slot_offset_ms_range:
              $ref: '#/components/schemas/SlotOffsetMsRange'
            cursor:
              $ref: '#/components/schemas/Cursor'
            page_size:
              $ref: '#/components/schemas/MevBidsPageSize'
      required:
        - block
    BlockMevBid.ContainerList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BlockMevBid.Data'
      required:
        - data
    PagingTemplate:
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/Paging'
    DataReadinessTemplate:
      type: object
      properties:
        ready:
          type: boolean
          description: >
            `true` when the underlying data pipeline has fully processed this
            slot and the result is definitive.

            `false` when the slot falls within the pipeline lag window (roughly
            4 hours behind the chain head) — the empty response reflects current
            pipeline state and may change when the exporter catches up.
      required:
        - ready
    Error:
      type: object
      properties:
        error:
          type: string
    NamedChain:
      type: object
      properties:
        chain:
          $ref: '#/components/schemas/Chain'
    NamedBlockSelector:
      type: object
      properties:
        block:
          $ref: '#/components/schemas/BlockSelector'
      required:
        - block
    SlotOffsetMsRange:
      type: object
      description: >-
        Inclusive bounds (in milliseconds relative to slot start) used to filter
        bids by their slot offset. Either bound may be omitted or `null` to
        leave that side unbounded.
      properties:
        min:
          allOf:
            - $ref: '#/components/schemas/SlotOffsetMs'
          nullable: true
          description: Inclusive lower bound. `null` = unbounded below.
        max:
          allOf:
            - $ref: '#/components/schemas/SlotOffsetMs'
          nullable: true
          description: Inclusive upper bound. `null` = unbounded above.
    Cursor:
      type: string
      description: >-
        Cursor value for pagination. See our [pagination guide](/api/pagination)
        for more details.
      default: ''
    MevBidsPageSize:
      type: integer
      description: The number of bids to return per page.
      minimum: 1
      maximum: 200
      default: 25
    BlockMevBid.Data:
      type: object
      description: A single relay bid recorded for the block's slot.
      properties:
        relay:
          type: string
          description: Identifier of the relay that submitted the bid.
        builder_pubkey:
          type: string
          pattern: ^0x[a-fA-F0-9]{96}$
          nullable: true
          description: BLS public key of the block builder, or `null` if unknown.
        value:
          allOf:
            - $ref: '#/components/schemas/wei'
          description: Bid value in wei.
        slot_offset_ms:
          allOf:
            - $ref: '#/components/schemas/SlotOffsetMs'
          nullable: true
          description: >-
            Slot offset of this bid, or `null` when the relay submission carried
            no usable timestamp and the offset could not be computed.
        relay_received_at:
          type: integer
          format: int64
          description: >-
            Unix timestamp in milliseconds at which the bid was received by the
            relay.
        won:
          type: boolean
          description: >-
            `true` if this was the winning bid for the slot (the bid the
            proposer selected).
        block_number:
          $ref: '#/components/schemas/Block'
        block_hash:
          type: string
          pattern: ^0x[a-fA-F0-9]{64}$
          description: Execution layer block hash of the bid, as a 0x-prefixed hex string.
        parent_hash:
          type: string
          pattern: ^0x[a-fA-F0-9]{64}$
          description: >-
            Execution layer parent block hash of the bid, as a 0x-prefixed hex
            string.
        source:
          $ref: '#/components/schemas/MevSource'
        optimistic_submission:
          type: boolean
          description: >-
            `true` if the bid was submitted optimistically (accepted by the
            relay before full validation).
      required:
        - relay
        - builder_pubkey
        - value
        - slot_offset_ms
        - relay_received_at
        - won
        - block_number
        - block_hash
        - parent_hash
        - source
        - optimistic_submission
    Paging:
      type: object
      properties:
        next_cursor:
          description: >-
            Cursor to the next page of results. See our [pagination
            guide](/api/pagination) for more details. If empty, there are no
            more pages to fetch.
          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
    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.
    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.
    MevSource:
      type: string
      enum:
        - get_header
        - data_api
        - ultrasound
      example: get_header
      description: |
        How the bid was observed.

        - `get_header`: seen via the relay's `getHeader` proposer API.
        - `data_api`: seen via the relay's data API.
        - `ultrasound`: seen via the ultrasound relay top-bid stream.
    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
    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.
  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.

````