Seneschal Data API

Free, public, read-only REST + Model Context Protocol server exposing real-time and historical DeFi liquidation telemetry for Aave, Morpho, Spark and Compound on Ethereum mainnet, plus block-builder market share data from the operator's own slot-by-slot shadow recorder.

Live endpoints

What	URL	Auth
REST API	https://api.seneschal.space	None
MCP (Streamable HTTP)	https://mcp.seneschal.space	None
Docs	https://docs.seneschal.space	-
Live stats dashboard	https://stats.seneschal.space	-

Rate limit: 120 requests/min/IP at the REST host. The MCP host pipelines requests over a single transport so the same limit applies per session.

Quick start

REST

curl 'https://api.seneschal.space/v1/liquidations/atrisk?max_hf=1.05&min_debt_usd=1000'

MCP — Claude Desktop / Cursor / Continue

Add this to your MCP client config (e.g. ~/.cursor/mcp.json):

{
  "mcpServers": {
    "seneschal-data": {
      "url": "https://mcp.seneschal.space/"
    }
  }
}

Nine tools become available to your agent:

Tool	Purpose
seneschal_health	Liveness + data freshness
seneschal_list_at_risk_borrowers	Find liquidatable positions across all DeFi
seneschal_list_borrowers	Generic discovery / pagination over the full borrower set
seneschal_recent_liquidations	Recent on-chain liquidations (won by other liquidators or ourselves)
seneschal_get_borrower	Latest state of one borrower across protocols
seneschal_get_borrower_history	Time-series health-factor traces
seneschal_builder_leaderboard	Ethereum builder market share (24h, 7d, 30d, all-time)
seneschal_stats_overview	Aggregate snapshot powering the public dashboard
seneschal_flashloan_providers	Curated catalogue of mainnet flash-loan providers

REST endpoints

Method	Path	Notes
GET	/v1/health	Liveness + freshness probe
GET	/v1/liquidations/atrisk	?protocol&max_hf&min_debt_usd&limit
GET	/v1/liquidations/recent	?since_ms&protocol&limit
GET	/v1/borrowers	?protocol&min_hf&max_hf&min_debt_usd&max_debt_usd&sort_by&sort_dir&limit&offset
GET	/v1/borrowers/:address	Cross-protocol borrower snapshot
GET	/v1/borrowers/:address/history	`?protocol=aave
GET	/v1/builders/leaderboard	`?window=24h
GET	/v1/stats/overview	Aggregate snapshot for dashboards
GET	/v1/flashloan/providers	?chain&max_fee_bps&multi_asset

Full details, parameter tables, and worked examples at https://docs.seneschal.space.

Why this exists

Seneschal operates an Ethereum block builder (extra_data = Seneschal/0.1) and a vertically-integrated liquidation searcher. The searcher already tracks ~500 Morpho borrowers, 1,300+ Spark borrowers, every Aave V3 mainnet position with non-trivial debt, and the winning builder of every slot since May 2026. Nobody else publishes this combination, so we expose it.

Two protocols, one backend:

• REST API — dashboards, monitoring tools, anything that speaks HTTP.
• MCP server — AI agents (Claude, Cursor, Continue, etc.) using the Model Context Protocol.

Local dev

git clone https://github.com/Rotwang9000/seneschal-data-api
cd seneschal-data-api
npm install
SENESCHAL_MEV_LOGS_DB=/path/to/your-mev-data.sqlite \
SENESCHAL_MORPHO_BORROWERS=/path/to/morpho-borrowers.json \
SENESCHAL_SPARK_BORROWERS=/path/to/spark-borrowers.json \
SENESCHAL_SHADOW_BLOCKS=/path/to/shadow-blocks.jsonl \
  node bin/rest.mjs
# in another shell:
curl http://127.0.0.1:8810/v1/health

Docker

A Dockerfile is provided for self-hosting the MCP server:

docker build -t seneschal-data-api .
docker run -p 8811:8811 -v /path/to/your-data:/data seneschal-data-api
# point your MCP client at http://localhost:8811/

The data sources are SQLite + JSONL files written by the Seneschal bot. Schemas are documented in src/db.js; if you have your own writer producing the same shapes you can point this server at it.

Tests

npm test

45 jest tests covering the query layer (in-memory SQLite fixtures), the Fastify REST routes (via fastify.inject), and the MCP server (both in-process via InMemoryTransport and end-to-end via StreamableHTTPClientTransport).

Architecture

services/data-api/   ← this repository
├── bin/
│   ├── rest.mjs                  systemd entry — Fastify REST listener
│   └── mcp.mjs                   systemd entry — MCP HTTP listener
├── src/
│   ├── config.js                 env-driven config (ports, paths, limits)
│   ├── db.js                     better-sqlite3 read-only handle + JSON cache
│   ├── queries.js                pure functions used by both REST and MCP
│   ├── rest-server.js            Fastify app: `buildApp()` for tests, `start()` for prod
│   └── mcp-server.js             McpServer + StreamableHTTPServerTransport
├── docs/                         public docs served at docs.seneschal.space
└── test/                         queries / rest-server / mcp-server tests

Shared design rule: both REST and MCP layers are thin wrappers around queries.js. Any new endpoint goes in queries.js first (with tests), then both wrappers in the same commit.

License

MIT — see LICENSE.

Operator contact

Seneschal is a single-operator Ethereum block builder and searcher running an rbuilder fork from a co-located server in Helsinki. Builder on-chain extra_data is Seneschal/0.1. Contact @Rotwang9000 on Discord.