内容
# 塞内沙尔数据API
[](https://github.com/Rotwang9000/seneschal-data-api/actions/workflows/ci.yml)
[](LICENSE)
免费、公开的REST + [模型上下文协议](https://modelcontextprotocol.io) 服务器，公开以太坊主网上的实时和历史DeFi清算遥测数据，适用于Aave、Morpho、Spark和Compound，以及来自操作员自己的插槽逐插槽影子记录器的区块构建市场份额数据。
在其上，有两个付费层级，均按调用次数通过 [x402](https://docs.x402.org) 微支付（Base上的USDC - 无需账户，无需API密钥）计费：
- **私人监控** *(旗舰版)* — 提供Monero或Zcash的**查看密钥** 和webhook URL；我们在自己的完整节点上监控链，并为每个传入的支付事件发送HMAC签名事件。按信用计费（$0.02/天 + $0.005/调用），因此小接收者支付几分钱，您永远不需要运行节点。可以通过API、MCP工具或 [WalletConnect控制面板](https://panel.seneschal.space) 驱动。
- **高级数据** — 预期价值排名的清算机会、按构建者划分的出价分布以及Penny Oracle原子单事实端点（DeFi + Monero/Zcash），价格为$0.001/调用。
监控也可以 **原生以XMR或ZEC充值** （我们报价，您在链上支付，我们的查看密钥扫描器充值监控 - 无桥接，无托管人）。所有付费路由都带有 [x402 Bazaar](https://docs.cdp.coinbase.com/x402/bazaar) 发现扩展，并通过Coinbase CDP促进者结算，因此代理可以通过CDP发现搜索、Agentic.Market和 [x402.eco](https://x402.eco) 在没有任何预制集成的情况下找到并支付它们。
支付引擎本身（x402支付墙、查看密钥监控、信用表、MCP工具）是开源的、品牌中立的 [支付网关](https://github.com/Rotwang9000/payments-gateway) — 嵌入它以收取您自己的服务费用。
## 直播端点
| 功能 | URL | 认证 |
| --- | --- | --- |
| REST API | `https://api.seneschal.space` | 无 |
| MCP（可流式HTTP） | `https://mcp.seneschal.space` | 无 |
| 控制面板（私人监控） | `https://panel.seneschal.space` | 钱包 |
| 文档 | `https://docs.seneschal.space` | - |
| 直播统计仪表盘 | `https://stats.seneschal.space` | - |
速率限制：REST主机每分钟120个请求/IP。MCP主机通过单个传输管道请求，因此相同的限制适用于每个会话。
## 快速入门
### REST
```bash
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`）：
```json
{
"mcpServers": {
"seneschal-data": {
"url": "https://mcp.seneschal.space/"
}
}
}
```
该服务器已发布到官方 [MCP注册表](https://registry.modelcontextprotocol.io) 中，名为 `io.github.Rotwang9000/seneschal-data` （参见 [`server.json`](server.json)），因此MCP感知的客户端和聚合器可以自动发现它。
十八种工具可供您的代理使用 — 免费读取工具，以及付费工具，返回确切的URL + 正文以通过x402结算：
| 工具 | 目的 |
| --- | --- |
| `seneschal_health` | 存活 + 数据新鲜度 |
| `seneschal_list_at_risk_borrowers` | 查找所有DeFi中的可清算头寸 |
| `seneschal_list_borrowers` | 协议的通用发现/分页 |
| `seneschal_recent_liquidations` | 最近的链上清算（由其他清算者或我们自己赢得） |
| `seneschal_get_borrower` | 借款人的最新状态，跨协议 |
| `seneschal_get_borrower_history` | 时间序列健康因子轨迹 |
| `seneschal_builder_leaderboard` | 以太坊区块构建市场份额（24小时，7天，30天，全部） |
| `seneschal_stats_overview` | 公共仪表盘的聚合快照，包括操作员活动（仅计数 - 无利润字段） |
| `seneschal_flashloan_providers` | 主网闪贷提供商的精选目录，包括LP侧提交资本路径（如果适用） |
| `seneschal_paywall_info` | x402支付墙的免费元数据（网络、收款人、每调用价格） |
| `seneschal_premium_opportunities` | 具有实现市场智能的、风险等级的借款人 *(x402, 付费)* |
| `seneschal_premium_builder_stats` | 每个构建者的出价分布 + 每小时插槽直方图，用于捆绑定价 *(x402, 付费)* |
| `seneschal_q` | Penny Oracle调度器 — DeFi + Monero/Zcash的原子单事实，$0.001/调用 *(x402, 付费)* |
| `seneschal_private_watch_info` | 私人监控的免费元数据：仪表、支持的链、NFPT上游健康、安全说明 |
| `seneschal_private_watch_create` | 将XMR/ZEC查看密钥订阅到webhook支付监控 *(x402, 付费)* |
| `seneschal_private_watch_topup` | URL + 正文，用于充值现有监控的信用（$0.10 / $1 / $5层级） |
| `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|morpho&since_ms&until_ms&granularity&limit` |
| `GET` | `/v1/builders/leaderboard` | `?window=24h|7d|30d|all&limit` |
| `GET` | `/v1/stats/overview` | 仪表盘的聚合快照 |
| `GET` | `/v1/flashloan/providers` | `?chain&max_fee_bps&multi_asset` |
完整的详细信息、参数表和示例参见 [`https://docs.seneschal.space`](https://docs.seneschal.space)。
## 为什么存在
Seneschal运行一个以太坊区块构建器（`extra_data = Seneschal/0.1`）和一个垂直集成的清算搜索器。搜索器已经跟踪约500个Morpho借款人、1300多个Spark借款人、每个Aave V3主网头寸（具有非琐碎债务）和自2026年5月以来每个插槽的获胜构建器。没有其他人发布此组合，因此我们公开它。
两个协议，一个后端：
- **REST API** — 仪表盘、监控工具、任何支持HTTP的工具。
- **MCP服务器** — 使用模型上下文协议的AI代理（Claude、Cursor、Continue等）。
## 本地开发
```bash
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
# 在另一个shell中：
curl http://127.0.0.1:8810/v1/health
```
## Docker
提供了一个 `Dockerfile` 用于自托管MCP服务器：
```bash
docker build -t seneschal-data-api .
docker run -p 8811:8811 -v /path/to/your-data:/data seneschal-data-api
# 将您的MCP客户端指向 http://localhost:8811/
```
数据源是SQLite + JSONL文件，由Seneschal机器人写入。模式在 `src/db.js` 中有文档；如果您有自己的编写器生成相同的形状，您可以将此服务器指向它。
## 测试
```bash
npm test
```
539个jest测试覆盖查询层（内存SQLitefixtures）、Fastify REST路由（通过 `fastify.inject`）、MCP服务器（通过 `InMemoryTransport` 和端到端通过 `StreamableHTTPClientTransport`）、x402支付墙 + bazaar发现线路、私人监控信用表/轮询器/涌入定价和操作监视狗。还有 `test/live-smoke.mjs` ，它通过Streamable HTTP练习直播 `mcp.seneschal.space` 端点。
## 架构
```
services/data-api/ ← 本仓库
├── bin/
│ ├── rest.mjs systemd入口 — Fastify REST监听器
│ └── mcp.mjs systemd入口 — MCP HTTP监听器
├── src/
│ ├── config.js 环境驱动配置（端口、路径、限制）
│ ├── db.js better-sqlite3只读句柄 + JSON缓存
│ ├── queries.js 两个REST和MCP使用的纯函数
│ ├── rest-server.js Fastify应用：`buildApp()`用于测试，`start()`用于生产
│ └── mcp-server.js McpServer + StreamableHTTPServerTransport
├── docs/ 公共文档，托管在docs.seneschal.space
└── test/ 查询/REST服务器/MCP服务器测试
```
共享设计规则：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促进者](https://docs.x402.org) 结算一个签名的EIP-3009 `transferWithAuthorization` 用于Base主网上的USDC。
### 配置
| 环境变量 | 默认值 | 备注 |
| --- | --- | --- |
| `X402_RECIPIENT_ADDRESS` | （空 - 支付墙关闭） | 选定网络上的收款人钱包。0x前缀20字节十六进制。 |
| `X402_NETWORK` | `eip155:8453` （Base主网） | 促进者支持的任何CAIP-2 EVM网络。 |
| `COINBASE_API_KEY` + `COINBASE_API_SECRET` | （空） | **推荐。** [CDP API密钥](https://docs.cdp.coinbase.com/x402/quickstart-for-sellers)。当两者都设置时，通过Coinbase的托管促进者（`api.cdp.coinbase.com/platform/v2/x402`）结算路由，并自动在 **Coinbase x402 Bazaar** 中列出服务。不需要业务/KYB验证；每月1000个免费结算。接受 `X402_CDP_API_KEY_ID` / `CDP_API_KEY_ID` 别名。 |
| `X402_FACILITATOR_URL` | `https://facilitator.openx402.ai` | 仅当未设置CDP凭证时使用的备用促进者。 |
| `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
```
返回实时网络/收款人/价格/路由表，以便代理在打开付费请求之前进行预算。
## 支持
- **每次调用支付** （代理首选）：支付$0.05 USDC到Base，调用 `GET /v1/premium/opportunities`。有关实时收款人 +轨道，请参见 `/v1/paywall`。
- **GitHub赞助商**：存储库顶部的赞助商按钮（`.github/FUNDING.yml`）。
- **直接提示**：ETH / BTC地址在 [stats.seneschal.space](https://stats.seneschal.space) 上显示，一旦操作员设置 `SENESCHAL_DONATE_ETH` / `SENESCHAL_DONATE_BTC`。
- **问题/允许列表提升**：Telegram [`@OrknetP`](https://t.me/OrknetP)。
Seneschal运行在一个 Helsinki 的单个盒子上；每一分钱都有助于保持它的在线状态。
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
## 操作员联系方式
Seneschal是一个单一操作员以太坊区块构建器和搜索器，从赫尔辛基的共置服务器运行 `rbuilder`分支。构建器链上extra_data是`Seneschal/0.1`。联系 [`@OrknetP`](https://t.me/OrknetP) 在Telegram上（定期检查）。
