Seneschal Data

Seneschal Data API

免费的公共 REST + Model Context Protocol 服务，提供 Ethereum 主网上 Aave、Morpho、Spark 和 Compound 的实时及历史 DeFi 清算遥测数据，以及来自运营方自有逐区块影子记录器的区块构建者市场份额数据。

此外还提供两个付费层级，均通过 x402 微支付按调用计费（Base 上的 USDC——无需账户或 API 密钥）：

• Private Watch （旗舰产品）——向我们提供 Monero 或 Zcash 查看密钥 和 webhook URL；我们通过自有全节点监控区块链，并为每笔入账付款向你发送 HMAC 签名事件。按额度计费 （每天 $0.02 + 每次调用 $0.005），小型接收方只需支付几美分，而且无需 运行节点。通过 x402 使用 USDC 充值，或直接使用 Monero/Zcash 付款 （POST /v1/private/topup-crypto——免费报价，无需 x402 或密钥；我们使用产品提供的同一查看密钥扫描器检测 加密货币付款）。可通过 API、MCP 工具或 WalletConnect 控制面板使用。
• Premium data——按预期价值排序的清算机会、按构建者划分的出价分布，以及 Penny Oracle 原子单事实端点（DeFi + Monero/Zcash），每次调用 $0.001 起。

在线端点

内容	URL	身份验证
REST API	https://api.seneschal.space	无
MCP（Streamable HTTP）	https://mcp.seneschal.space	无
控制面板（Private Watch）	https://panel.seneschal.space	钱包
文档	https://docs.seneschal.space	-
实时统计数据面板	https://stats.seneschal.space	-

REST 主机的速率限制为每个 IP 每分钟 120 个请求。MCP 主机会通过单一传输管道化处理请求，因此同一限制按会话适用。

快速开始

REST

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

MCP — Claude Desktop / Cursor / Continue

将以下内容添加到 MCP 客户端配置中（例如 ~/.cursor/mcp.json）：

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

此服务已发布到官方 MCP Registry，标识为 io.github.Rotwang9000/seneschal-data（参见 server.json）， 因此支持 MCP 的客户端和聚合器可以自动发现它。

Agent 可以使用 18 种工具——免费的读取工具，以及付费工具；后者会返回用于通过 x402 结算的确切 URL + 请求正文：

工具	用途
seneschal_health	存活状态 + 数据新鲜度
seneschal_list_at_risk_borrowers	查找所有 DeFi 中可被清算的头寸
seneschal_list_borrowers	对全部借款人集合进行通用发现 / 分页
seneschal_recent_liquidations	最近的链上清算（由其他清算者或我们自己赢得）
seneschal_get_borrower	查看某个借款人在各协议中的最新状态
seneschal_get_borrower_history	健康因子的时间序列轨迹
seneschal_builder_leaderboard	Ethereum 构建者市场份额（24 小时、7 天、30 天、历史累计）
seneschal_stats_overview	为公开仪表板提供汇总快照，包括运营方活动（仅计数，不含利润字段）
seneschal_flashloan_providers	精选的主网闪电贷提供方目录；适用时包括 LP 侧的承诺资本路径
seneschal_paywall_info	x402 付费墙的免费元数据（网络、收款方、单次调用价格）
seneschal_premium_opportunities	按 EV 排序的高风险借款人及已实现的市场情报 (x402，付费)
seneschal_premium_builder_stats	按构建者划分的出价分布 + 用于 Bundle 定价的每小时时隙直方图 (x402，付费)
seneschal_q	Penny Oracle 分发器——跨 DeFi + Monero/Zcash 查询原子级单项事实，$0.001/次调用 (x402，付费)
seneschal_private_watch_info	Private Watch 的免费元数据：计量器、支持的链、NFPT 上游运行状况、安全说明
seneschal_private_watch_create	订阅 XMR/ZEC 查看密钥，以监控 Webhook 付款 (x402，付费)
seneschal_private_watch_topup	为现有监控充值的 URL + 请求正文（$0.10 / $1 / $5 档位）
seneschal_private_watch_topup_crypto	免费报价：通过 Monero/Zcash 付款为监控充值；轮询状态直至结算（无 x402，无密钥）
seneschal_private_watch_historical	一次性付费扫描，返回查看密钥的可支用 + 已支用票据 (x402，付费；密钥永不留存)
seneschal_private_watch_derive_viewkey	免费、限速的 Zcash UFVK 派生功能，可从 BIP-39 助记词派生（附醒目的安全警告）

REST 端点

方法	路径	说明
GET	/v1/health	存活状态和数据新鲜度探测
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	跨协议借款人快照
GET	/v1/borrowers/:address/history	`?protocol=aave
GET	/v1/builders/leaderboard	`?window=24h
GET	/v1/stats/overview	适用于仪表板的汇总快照
GET	/v1/flashloan/providers	?chain&max_fee_bps&multi_asset

完整详情、参数表和示例请见 https://docs.seneschal.space。

为什么要构建它

Seneschal 运营着一个 Ethereum 区块构建器 （extra_data = Seneschal/0.1）和一个垂直整合的清算搜索器。该搜索器已追踪约 500 个 Morpho 借款人、1,300 多个 Spark 借款人、所有具有实质性债务的 Aave V3 主网头寸，以及自 2026 年 5 月以来每个时隙的获胜构建器。没有其他人发布这一组合数据，因此我们将其开放出来。

两种协议，一个后端：

• REST API — 适用于仪表板、监控工具及任何支持 HTTP 的应用。
• MCP 服务 — 供使用 Model Context Protocol 的 AI Agent（Claude、Cursor、Continue 等）使用。

本地开发

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

提供了一个 Dockerfile，用于自托管 MCP 服务：

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/

数据源是由 Seneschal bot 写入的 SQLite 和 JSONL 文件。src/db.js 中记录了架构；如果你有自己的写入程序，能生成相同的数据结构，就可以将此服务指向它。

测试

npm test

539 个 Jest 测试覆盖查询层（内存 SQLite 测试数据）、Fastify REST 路由（通过 fastify.inject）、MCP 服务（通过 InMemoryTransport 进行进程内测试，并通过 StreamableHTTPClientTransport 进行端到端测试）、x402 付费墙和 bazaar 发现接线、Private Watch 积分计量器／轮询器／激增定价，以及运维看门狗。此外，test/live-smoke.mjs 会通过 Streamable HTTP 调用线上 mcp.seneschal.space 端点进行测试。

架构

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

通用设计原则：REST 和 MCP 层都是围绕 queries.js 构建的轻量包装层。新增端点时，先在 queries.js 中实现（并添加测试），然后在同一个提交中更新两个包装层。

高级套餐（x402 付费墙）

src/queries-premium.js 和 src/x402.js 为一组 /v1/premium/* 端点（以及 seneschal_premium_* MCP 工具）添加了按次付费功能。除非运营者设置了 X402_RECIPIENT_ADDRESS，否则付费墙处于关闭状态。设置后，未签名请求会收到 HTTP 402 响应，其中包含机器可读的付款要求；随后，x402 facilitator 会为 Base 主网上的 USDC 结算经过签名的 EIP-3009 transferWithAuthorization。

配置

环境变量	默认值	说明
X402_RECIPIENT_ADDRESS	(empty — paywall off)	所选网络上的收款钱包。带 0x 前缀的 20 字节十六进制值。
X402_NETWORK	eip155:8453 (Base mainnet)	Facilitator 支持的任意 CAIP-2 EVM 网络。
COINBASE_API_KEY + COINBASE_API_SECRET	(empty)	推荐。 CDP API key。设置这两个值后，结算会通过 Coinbase 托管的 facilitator（api.cdp.coinbase.com/platform/v2/x402）进行，服务也会自动列入 Coinbase x402 Bazaar。无需进行商业/KYB 验证；每月可免费结算 1k 次。接受 X402_CDP_API_KEY_ID / CDP_API_KEY_ID 别名。
X402_FACILITATOR_URL	https://facilitator.openx402.ai	仅当未设置 CDP 凭据时使用的备用 facilitator。
X402_FEED_PRICE	$0.05	货币格式（$0.05）或最小单位（50000）。
X402_PAYWALL_DESCRIPTION	…	显示在 /、/v1/paywall 和统计信息仪表板上。
X402_MAX_TIMEOUT_SECONDS	120	每次调用的最长结算时间窗口。

免费元数据端点（零成本，无需签名）：

curl https://api.seneschal.space/v1/paywall

返回实时网络/收款方/支付渠道表，让 Agent 在发起付费请求前 为会话预留预算。

支持

• 按次付款（推荐给 Agent）：在 Base 上支付 $0.05 USDC， 调用 GET /v1/premium/opportunities。查看 /v1/paywall 获取 实时收款方和支付渠道。
• GitHub Sponsors：仓库顶部的 Sponsor 按钮 （.github/FUNDING.yml）。
• 直接打赏：操作者设置 SENESCHAL_DONATE_ETH / SENESCHAL_DONATE_BTC 后，ETH / BTC 地址会显示在 stats.seneschal.space 上。
• 问题 / 提高允许名单额度：Telegram @OrknetP。

Seneschal 在赫尔辛基的一台专用服务器上运行；每一分钱都有助于让它 保持在线。

许可证

MIT — 参见 LICENSE。

操作者联系方式

Seneschal 是由单一操作者运行的 Ethereum 区块构建者和搜索者， 在赫尔辛基的一台同机房服务器上运行 rbuilder 分支。 构建者链上 extra_data 为 Seneschal/0.1。请通过 Telegram 联系 @OrknetP（定期查看）。