# Seneschal Builder Bids & Proposer Payment Export

> Seneschal Builder Bids & Proposer Payment Export is a paid API for AI agents from api.seneschal.space, paid per call via x402, $0.05/call, status unknown (last checked 2026-09-14).

Returns per-slot Ethereum block builder bids and realised proposer payments (priority + coinbase fees) as CSV or JSON lines over a specified block range or rolling time window

## Facts

- Endpoint: GET https://api.seneschal.space/v1/premium/builder-bids.csv
- Price: $0.05/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-14
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/seneschal-builder-bids-proposer-payment-export-f1b14229
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_bwsMvrvATHpzoEVN6rBV0

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability seneschal-builder-bids-proposer-payment-export-f1b14229
```

Example prompt: Pull me the Seneschal builder bids and actual proposer payment data for blocks 19000000 to 19010000 as a CSV — I want to see who won each slot, the shadow bid, and what the proposer actually got in priority fees and coinbase transfers.

## When to prefer this

Use this endpoint when you need bulk historical or recent Ethereum builder bid and proposer payment data across many slots for analysis, backtesting, or audit. For a single live slot or real-time tail, prefer the cheaper /v1/q/proposer-payment endpoint. Choose CSV output for spreadsheet import or JSONL for streaming pipelines.

## Known failure modes

- Block range exceeds 100,000 blocks — returns error requiring narrower range
- window_ms exceeds 30 days (2,592,000,000 ms) — returns error
- Missing both from_block/to_block and window_ms — ambiguous query
- from_block greater than to_block — invalid range error
- Payment not included or insufficient — 402 Payment Required
- Data not yet available for very recent blocks — empty or partial result

## How this service works

Per-slot builder bids + realised proposer payment from the Seneschal shadow recorder, as CSV or JSON lines (?format=csv|jsonl). Range: ?from_block=&to_block= (max 100000 blocks) or ?window_ms= (max 30d). Columns: block, ts_ms, iso_time, miner, builder, actual_total_eth (= what the proposer actually got: priority + coinbase), actual_priority_eth, actual_coinbase_eth, shadow_bid_eth, would_have_won, tx_count. Live tail: GET /v1/q/proposer-payment ($0.001).

## Output

A CSV (or JSONL) file with one row per slot containing: block number, timestamp (ms and ISO), miner address, winning builder address, actual total ETH paid to proposer (priority + coinbase), priority ETH, coinbase ETH, the shadow bid in ETH, a boolean indicating whether the shadow bid would have won, and transaction count per block.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "properties": {
      "to_block": {
       "type": "integer",
       "description": "End block (inclusive); required with from_block; span ≤ 100000."
      },
      "window_ms": {
       "type": "integer",
       "description": "Trailing window in ms (used when no block range given; ≤ 30d)."
      },
      "from_block": {
       "type": "integer",
       "description": "Start block (inclusive)."
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "string",
     "description": "text/csv; one header row + one row per slot."
    }
   }
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": "block,ts_ms,iso_time,miner,builder,actual_total_eth,actual_priority_eth,actual_coinbase_eth,shadow_bid_eth,would_have_won,tx_count\n25009771,1777754812618,2026-05-02T...,0x4838...,beaverbuild,0.066254941,0.066254941,0.000000000,0.072000000,true,343\n"
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/seneschal-builder-bids-proposer-payment-export-f1b14229/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from api.seneschal.space](https://www.zero.xyz/host/api.seneschal.space/llms.txt)