{
  "markdown": "# Seneschal Data API\n\n[![ci](https://github.com/Rotwang9000/seneschal-data-api/actions/workflows/ci.yml/badge.svg)](https://github.com/Rotwang9000/seneschal-data-api/actions/workflows/ci.yml)\n[![license](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n\nFree, public REST + [Model Context Protocol](https://modelcontextprotocol.io)\nserver exposing real-time and historical DeFi liquidation telemetry for\nAave, Morpho, Spark and Compound on Ethereum mainnet, plus block-builder\nmarket share data from the operator's own slot-by-slot shadow recorder.\n\nTwo paid tiers sit on top, both billed per call over\n[x402](https://docs.x402.org) micropayments (USDC on Base — no account, no\nAPI key):\n\n- **Private Watch** *(flagship)* — give us a Monero or Zcash **view key**\n  and a webhook URL; we watch the chain on our own full nodes and POST you\n  an HMAC-signed event for every inbound payment. Credit-metered\n  ($0.02/day + $0.005/call), so small receivers pay pennies and you never\n  run a node. Top up in USDC over x402 **or pay in Monero/Zcash directly**\n  (`POST /v1/private/topup-crypto` — free quote, no x402, no key; we detect\n  the coin payment with the same view-key scanner the product sells). Drive\n  it from the API, the MCP tools, or the\n  [WalletConnect control panel](https://panel.seneschal.space).\n- **Premium data** — expected-value-ranked liquidation opportunities,\n  per-builder bid distributions, and Penny Oracle atomic single-fact\n  endpoints (DeFi + Monero/Zcash) from $0.001/call.\n\n## Live endpoints\n\n| What                          | URL                              | Auth     |\n|-------------------------------|----------------------------------|----------|\n| REST API                      | `https://api.seneschal.space`    | None     |\n| MCP (Streamable HTTP)         | `https://mcp.seneschal.space`    | None     |\n| Control panel (Private Watch) | `https://panel.seneschal.space`  | Wallet   |\n| Docs                          | `https://docs.seneschal.space`   | -        |\n| Live stats dashboard          | `https://stats.seneschal.space`  | -        |\n\nRate limit: 120 requests/min/IP at the REST host. The MCP host pipelines\nrequests over a single transport so the same limit applies per session.\n\n## Quick start\n\n### REST\n\n```bash\ncurl 'https://api.seneschal.space/v1/liquidations/atrisk?max_hf=1.05&min_debt_usd=1000'\n```\n\n### MCP — Claude Desktop / Cursor / Continue\n\nAdd this to your MCP client config (e.g. `~/.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"seneschal-data\": {\n      \"url\": \"https://mcp.seneschal.space/\"\n    }\n  }\n}\n```\n\nThis server is published to the official\n[MCP Registry](https://registry.modelcontextprotocol.io) as\n`io.github.Rotwang9000/seneschal-data` (see [`server.json`](server.json)),\nso MCP-aware clients and aggregators can discover it automatically.\n\nEighteen tools become available to your agent — free read tools, plus\npaid tools that hand back the exact URL + body to settle over x402:\n\n| Tool                                 | Purpose                                                              |\n|--------------------------------------|----------------------------------------------------------------------|\n| `seneschal_health`                   | Liveness + data freshness                                            |\n| `seneschal_list_at_risk_borrowers`   | Find liquidatable positions across all DeFi                          |\n| `seneschal_list_borrowers`           | Generic discovery / pagination over the full borrower set            |\n| `seneschal_recent_liquidations`      | Recent on-chain liquidations (won by other liquidators or ourselves) |\n| `seneschal_get_borrower`             | Latest state of one borrower across protocols                        |\n| `seneschal_get_borrower_history`     | Time-series health-factor traces                                     |\n| `seneschal_builder_leaderboard`      | Ethereum builder market share (24h, 7d, 30d, all-time)               |\n| `seneschal_stats_overview`           | Aggregate snapshot powering the public dashboard, incl. operator activity (counts only — no profit fields) |\n| `seneschal_flashloan_providers`      | Curated catalogue of mainnet flash-loan providers, incl. LP-side commit-capital paths where applicable     |\n| `seneschal_paywall_info`             | Free metadata for the x402 paywall (network, recipient, per-call price)                                    |\n| `seneschal_premium_opportunities`    | EV-ranked at-risk borrowers with realised market intel *(x402, paid)*                                      |\n| `seneschal_premium_builder_stats`    | Per-builder bid distribution + hourly slot histogram for bundle pricing *(x402, paid)*                     |\n| `seneschal_q`                        | Penny Oracle dispatcher — atomic single facts across DeFi + Monero/Zcash, $0.001/call *(x402, paid)*       |\n| `seneschal_private_watch_info`       | Free metadata for Private Watch: meter, supported chains, NFPT upstream health, security notes             |\n| `seneschal_private_watch_create`     | Subscribe an XMR/ZEC view key to webhook payment monitoring *(x402, paid)*                                 |\n| `seneschal_private_watch_topup`      | URL + body to top up an existing watch's credit ($0.10 / $1 / $5 tiers)                                    |\n| `seneschal_private_watch_topup_crypto` | Free quote to top up a watch by paying in Monero/Zcash; poll status until settled (no x402, no key)      |\n| `seneschal_private_watch_historical` | One-off paid scan returning spendable + spent notes for a view key *(x402, paid; key never persists)*      |\n| `seneschal_private_watch_derive_viewkey` | Free, rate-limited Zcash UFVK derivation from a BIP-39 mnemonic (with a loud security warning)         |\n\n## REST endpoints\n\n| Method | Path                                  | Notes                                                          |\n|--------|---------------------------------------|----------------------------------------------------------------|\n| `GET`  | `/v1/health`                          | Liveness + freshness probe                                     |\n| `GET`  | `/v1/liquidations/atrisk`             | `?protocol&max_hf&min_debt_usd&limit`                          |\n| `GET`  | `/v1/liquidations/recent`             | `?since_ms&protocol&limit`                                     |\n| `GET`  | `/v1/borrowers`                       | `?protocol&min_hf&max_hf&min_debt_usd&max_debt_usd&sort_by&sort_dir&limit&offset` |\n| `GET`  | `/v1/borrowers/:address`              | Cross-protocol borrower snapshot                               |\n| `GET`  | `/v1/borrowers/:address/history`      | `?protocol=aave|morpho&since_ms&until_ms&granularity&limit`    |\n| `GET`  | `/v1/builders/leaderboard`            | `?window=24h|7d|30d|all&limit`                                 |\n| `GET`  | `/v1/stats/overview`                  | Aggregate snapshot for dashboards                              |\n| `GET`  | `/v1/flashloan/providers`             | `?chain&max_fee_bps&multi_asset`                               |\n\nFull details, parameter tables, and worked examples at\n[`https://docs.seneschal.space`](https://docs.seneschal.space).\n\n## Why this exists\n\nSeneschal operates an Ethereum block builder\n(`extra_data = Seneschal/0.1`) and a vertically-integrated liquidation\nsearcher. The searcher already tracks ~500 Morpho borrowers, 1,300+\nSpark borrowers, every Aave V3 mainnet position with non-trivial debt,\nand the winning builder of every slot since May 2026. Nobody else\npublishes this combination, so we expose it.\n\nTwo protocols, one backend:\n\n- **REST API** — dashboards, monitoring tools, anything that speaks HTTP.\n- **MCP server** — AI agents (Claude, Cursor, Continue, etc.) using\n  the Model Context Protocol.\n\n## Local dev\n\n```bash\ngit clone https://github.com/Rotwang9000/seneschal-data-api\ncd seneschal-data-api\nnpm install\nSENESCHAL_MEV_LOGS_DB=/path/to/your-mev-data.sqlite \\\nSENESCHAL_MORPHO_BORROWERS=/path/to/morpho-borrowers.json \\\nSENESCHAL_SPARK_BORROWERS=/path/to/spark-borrowers.json \\\nSENESCHAL_SHADOW_BLOCKS=/path/to/shadow-blocks.jsonl \\\n  node bin/rest.mjs\n# in another shell:\ncurl http://127.0.0.1:8810/v1/health\n```\n\n## Docker\n\nA `Dockerfile` is provided for self-hosting the MCP server:\n\n```bash\ndocker build -t seneschal-data-api .\ndocker run -p 8811:8811 -v /path/to/your-data:/data seneschal-data-api\n# point your MCP client at http://localhost:8811/\n```\n\nThe data sources are SQLite + JSONL files written by the Seneschal bot.\nSchemas are documented in `src/db.js`; if you have your own writer\nproducing the same shapes you can point this server at it.\n\n## Tests\n\n```bash\nnpm test\n```\n\n539 jest tests covering the query layer (in-memory SQLite fixtures), the\nFastify REST routes (via `fastify.inject`), the MCP server (both\nin-process via `InMemoryTransport` and end-to-end via\n`StreamableHTTPClientTransport`), the x402 paywall + bazaar-discovery\nwiring, the Private Watch credit meter / poller / surge pricing, and the\nops watchdog. Plus `test/live-smoke.mjs` which exercises the live\n`mcp.seneschal.space` endpoint over Streamable HTTP.\n\n## Architecture\n\n```\nservices/data-api/   ← this repository\n├── bin/\n│   ├── rest.mjs                  systemd entry — Fastify REST listener\n│   └── mcp.mjs                   systemd entry — MCP HTTP listener\n├── src/\n│   ├── config.js                 env-driven config (ports, paths, limits)\n│   ├── db.js                     better-sqlite3 read-only handle + JSON cache\n│   ├── queries.js                pure functions used by both REST and MCP\n│   ├── rest-server.js            Fastify app: `buildApp()` for tests, `start()` for prod\n│   └── mcp-server.js             McpServer + StreamableHTTPServerTransport\n├── docs/                         public docs served at docs.seneschal.space\n└── test/                         queries / rest-server / mcp-server tests\n```\n\nShared design rule: both REST and MCP layers are *thin* wrappers around\n`queries.js`. Any new endpoint goes in `queries.js` first (with tests),\nthen both wrappers in the same commit.\n\n## Premium tier (x402 paywall)\n\n`src/queries-premium.js` plus `src/x402.js` add per-call payment to a\nsmall family of `/v1/premium/*` endpoints (and `seneschal_premium_*`\nMCP tools). The paywall is off unless the operator sets\n`X402_RECIPIENT_ADDRESS`. Once set, unsigned requests get HTTP 402 with\nmachine-readable payment requirements, and an\n[x402 facilitator](https://docs.x402.org) settles a signed\nEIP-3009 `transferWithAuthorization` for USDC on Base mainnet.\n\n### Configure\n\n| Env var                    | Default                          | Notes                                                                  |\n| -------------------------- | -------------------------------- | ---------------------------------------------------------------------- |\n| `X402_RECIPIENT_ADDRESS`   | (empty — paywall off)            | Recipient wallet on the chosen network. 0x-prefixed 20-byte hex.       |\n| `X402_NETWORK`             | `eip155:8453` (Base mainnet)     | Any CAIP-2 EVM network the facilitator supports.                       |\n| `COINBASE_API_KEY` + `COINBASE_API_SECRET` | (empty) | **Recommended.** A [CDP API key](https://docs.cdp.coinbase.com/x402/quickstart-for-sellers). When both are set, settlement routes through Coinbase's hosted facilitator (`api.cdp.coinbase.com/platform/v2/x402`) and the service is auto-listed in the **Coinbase x402 Bazaar**. No business/KYB verification needed; 1k free settlements/month. Accepts `X402_CDP_API_KEY_ID` / `CDP_API_KEY_ID` aliases. |\n| `X402_FACILITATOR_URL`     | `https://facilitator.openx402.ai` | Fallback facilitator used only when no CDP credentials are set.        |\n| `X402_FEED_PRICE`          | `$0.05`                          | Money-formatted (`$0.05`) or atomic units (`50000`).                   |\n| `X402_PAYWALL_DESCRIPTION` | …                                | Shown on `/`, `/v1/paywall`, and the stats dashboard.                  |\n| `X402_MAX_TIMEOUT_SECONDS` | `120`                            | Maximum settlement window per call.                                    |\n\nFree metadata endpoint (zero cost, no signature required):\n\n```\ncurl https://api.seneschal.space/v1/paywall\n```\n\nreturns the live network/recipient/price/route table so agents can\nbudget a session before opening a paid request.\n\n## Support\n\n- **Per-call payments** (preferred for agents): pay $0.05 USDC on Base\n  to call `GET /v1/premium/opportunities`. See `/v1/paywall` for the\n  live recipient + rails.\n- **GitHub Sponsors**: the Sponsor button at the top of the repo\n  (`.github/FUNDING.yml`).\n- **Direct tips**: ETH / BTC addresses are surfaced on\n  [stats.seneschal.space](https://stats.seneschal.space) once the\n  operator sets `SENESCHAL_DONATE_ETH` / `SENESCHAL_DONATE_BTC`.\n- **Questions / allow-list bumps**: Telegram [`@OrknetP`](https://t.me/OrknetP).\n\nSeneschal runs on a single Helsinki box; every cent helps keep it\nonline.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n## Operator contact\n\nSeneschal is a single-operator Ethereum block builder and searcher\nrunning an `rbuilder` fork from a co-located server in Helsinki.\nBuilder on-chain extra_data is `Seneschal/0.1`. Contact\n[`@OrknetP`](https://t.me/OrknetP) on Telegram (checked periodically).\n",
  "bytes": 13339,
  "sha": "7a646e468b25a2368842181e54a44c5c793c52b12d059196b86b4dde74d978b8",
  "repo_slug": "rotwang9000/seneschal-data-api",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_rotwang9000_seneschal_data_7696a649/readme"
}