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

**Use case guide:** [Investigate a Block](/use-cases/investigate-mev-block) shows how to filter, paginate, and audit the relay bid ladder.

**Data provenance:** The bid ladder is collected from offchain relay APIs and streams. Relay-reported timestamps, identities, and bids are not independently verifiable from onchain data, and coverage gaps or inconsistent reporting can make the recorded ladder incomplete. Verify included block fields separately.

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.


        **Use case guide:** [Investigate a
        Block](/use-cases/investigate-mev-block) shows how to filter, paginate,
        and audit the relay bid ladder.


        **Data provenance:** The bid ladder is collected from offchain relay
        APIs and streams. Relay-reported timestamps, identities, and bids are
        not independently verifiable from onchain data, and coverage gaps or
        inconsistent reporting can make the recorded ladder incomplete. Verify
        included block fields separately.


        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 from an offchain relay
        API or stream. Relay-provided fields are observational data and are not
        independently verifiable from onchain data.
      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: >-
            Relay-reported Unix timestamp in milliseconds at which the bid was
            received. This offchain timestamp cannot be independently verified
            from onchain data.
        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. The offset is derived from
        an offchain relay-reported timestamp and is not independently verifiable
        from onchain data.
    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.

````