GreptimeDB MEV Monitor

API Specification

1. Statistics API

GET /stats

Returns a list of all configured statistics groups.

Response:

[
  {
    "id": 1,
    "name": "default",
    "bids_payload_work_mode": 2,
    "proposer_payload_work_mode": 2
  },
  ...
]

---

GET /stats/:statId

Returns configuration and status of a specific statistic group.

Path Parameters:

• statId – ID of the statistics group.

---

GET /stats/:statId/builder-blocks

Returns aggregated builder bids statistics for the specified statistics group.

Query Parameters:

• slot (optional)
• fromSlot (optional)
• toSlot (optional)

---

GET /stats/:statId/signed_value

Returns signed bid values for included relays in the statistics group.

Query Parameters:

• slot (optional)
• fromSlot (optional)
• toSlot (optional)

---

2. Relay Metadata API

GET /relays

Returns a list of all configured relays with metadata and fetch/indexing statistics.

Response:

[
  {
    "id": 1,
    "pubkey": "0x...",
    "url": "https://relay.example.com",
    "requestLimitPerMinute": 300,
    "signedBidsStats": {
      "firstFetchedSlot": 123456,
      "lastFetchedSlot": 123999,
      "firstIndexedSlot": 123456,
      "lastIndexedSlot": 123980
    },
    "builderBlocksStats": {
      "firstFetchedSlot": 123456,
      "lastFetchedSlot": 123999,
      "firstIndexedSlot": 123456,
      "lastIndexedSlot": 123980
    }
  },
  ...
]

---

GET /relays/:relayId

Returns detailed metadata and slot statistics for the specified relay.

Path Parameters:

• relayId – ID of the relay.

---

3. Relay Data API

GET /relays/signed-bids/:slot

Returns signed bid data for all relays for a specific slot.

Query Parameters (optional):

• slot
• fromSlot
• toSlot

---

GET /relays/:relayId/signed-bids

Returns signed bid data for a specific relay.

Path Parameters:

• relayId – ID of the relay.

Query Parameters (optional):

• slot
• fromSlot
• toSlot

---

4. Configuration and Management API (Optional)

These endpoints are recommended for dynamic configuration management.

POST /relays

Registers a new relay.

Request Body:

{
  "pubkey": "0x...",
  "url": "https://relay.example.com",
  "requestLimitPerMinute": 300
}

---

PATCH /relays/:relayId

Updates configuration for an existing relay.

---

POST /stats

Creates a new statistics group.

Request Body:

{
  "name": "new_group",
  "bids_payload_work_mode": 2,
  "proposer_payload_work_mode": 1
}

---

PATCH /stats/:statId

Updates configuration for a statistics group.

---

POST /stats/:statId/relays

Adds a relay to a statistics group with start slot settings.

Request Body:

{
  "relay_id": 1,
  "proposer_payload_start_slot": 123456,
  "bids_payload": 123456
}

---

5. Monitoring and Observability

GET /metrics

Exposes system metrics in Prometheus-compatible format, including:

• API request usage per relay
• Fetch failures, retries
• Slots indexed/skipped
• Backlog per relay

---

GET /health

Liveness and readiness check endpoint.

---

API Endpoints

Method	Endpoint	Purpose
GET	/stats	List all statistic groups
GET	/stats/:statId	Get statistic group config
GET	/stats/:statId/builder-blocks	Get bid stats per group
GET	/stats/:statId/signed_value	Get signed bid values per group
GET	/relays	List all relays with metadata
GET	/relays/:relayId	Get relay metadata
GET	/relays/signed-bids/:slot	Get signed bids for all relays
GET	/relays/:relayId/signed-bids	Get signed bids for one relay
POST	/relays	Register a new relay (optional)
PATCH	/relays/:relayId	Update relay configuration
POST	/stats	Create a new statistics group
PATCH	/stats/:statId	Update statistics group settings
POST	/stats/:statId/relays	Add relay to stats group with slots
GET	/metrics	System metrics endpoint
GET	/health	Health check endpoint