Seneschal Data

Seneschal Data API

Free, public 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.

Two paid tiers sit on top, both billed per call over x402 micropayments (USDC on Base — no account, no API key):

• Private Watch *(flagship)* — give us a Monero or Zcash view key and a webhook URL; we watch the chain on our own full nodes and POST you an HMAC-signed event for every inbound payment. Credit-metered ($0.02/day + $0.005/call), so small receivers pay pennies and you never run a node. Top up in USDC over x402 or pay in Monero/Zcash directly (POST /v1/private/topup-crypto — free quote, no x402, no key; we detect the coin payment with the same view-key scanner the product sells). Drive it from the API, the MCP tools, or the WalletConnect control panel.
• Premium data — expected-value-ranked liquidation opportunities, per-builder bid distributions, and Penny Oracle atomic single-fact endpoints (DeFi + Monero/Zcash) from $0.001/call.

Live endpoints

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/" } } }

This server is published to the official MCP Registry as io.github.Rotwang9000/seneschal-data (see server.json), so MCP-aware clients and aggregators can discover it automatically.

Eighteen tools become available to your agent — free read tools, plus paid tools that hand back the exact URL + body to settle over x402:

REST endpoints

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

539 jest tests covering the query layer (in-memory SQLite fixtures), the Fastify REST routes (via fastify.inject), the MCP server (both in-process via InMemoryTransport and end-to-end via StreamableHTTPClientTransport), the x402 paywall + bazaar-discovery wiring, the Private Watch credit meter / poller / surge pricing, and the ops watchdog. Plus test/live-smoke.mjs which exercises the live mcp.seneschal.space endpoint over Streamable HTTP.

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.

Premium tier (x402 paywall)

src/queries-premium.js plus src/x402.js add per-call payment to a small family of /v1/premium/* endpoints (and seneschal_premium_* MCP tools). The paywall is off unless the operator sets X402_RECIPIENT_ADDRESS. Once set, unsigned requests get HTTP 402 with machine-readable payment requirements, and an x402 facilitator settles a signed EIP-3009 transferWithAuthorization for USDC on Base mainnet.

Configure

| X402_PAYWALL_DESCRIPTION | … | Shown on /, /v1/paywall, and the stats da