Seneschal Data

Seneschal データ API

Aave、Morpho、Spark、Compoundを対象とするEthereumメインネット上のリアルタイムおよび過去のDeFi清算テレメトリーと、運営者独自のスロットごとのシャドーレコーダーによるブロックビルダーの市場シェアデータを公開する、無料のRESTおよびModel Context Protocolサーバーです。

その上に、x402のマイクロペイメント（Base上のUSDC。アカウントもAPIキーも不要）で呼び出しごとに課金される、有料プランが2つあります。

• Private Watch（主力プラン） — MoneroまたはZcashのビューキーとWebhook URLをお知らせいただければ、独自のフルノードでチェーンを監視し、入金のたびにHMAC署名付きイベントをPOSTします。クレジット従量制（1日$0.02＋1回あたり$0.005）のため、小規模な受信者はわずかな料金で利用でき、ノードを実行する必要もありません。x402でUSDCをチャージするか、Monero/Zcashで直接お支払いください（POST /v1/private/topup-crypto — 見積もり無料、x402不要、キー不要。提供サービスと同じビューキースキャナーでコインの支払いを検出します）。API、MCPツール、またはWalletConnectコントロールパネルから操作できます。
• Premium data — 期待値で順位付けされた清算機会、ビルダーごとの入札分布、そしてPenny Oracleの原子的な単一事実エンドポイント（DeFi＋Monero/Zcash）を、1回あたり$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 対応クライアントやアグリゲーターが自動的に検出できます。

エージェントで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ペイウォールの無料メタデータ（ネットワーク、受取人、1回あたりの料金）
seneschal_premium_opportunities	実現市場インテリジェンスを用いてEV順に並べた、リスクにさらされた借り手 (x402、有料)
seneschal_premium_builder_stats	バンドル価格設定用のビルダー別入札分布と時間単位のスロットヒストグラム (x402、有料)
seneschal_q	Penny Oracleディスパッチャー — DeFiおよびMonero/Zcash全体の個別の事実をアトミックに取得、1回あたり$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	BIP-39ニーモニックからZcash UFVKを導出する無料のレート制限付き機能（強いセキュリティ警告付き）

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月以降のすべてのスロットで勝利したビルダーを追跡しています。この情報を組み合わせて公開しているのはほかにないため、これを公開しています。

2つのプロトコルを1つのバックエンドで提供します。

• REST API — ダッシュボード、監視ツールなど、HTTPに対応するあらゆるもの。
• MCP サーバー — Model Context Protocolを使用するAIエージェント（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

MCP サーバーをセルフホストするためのDockerfileを用意しています。

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ボットが書き込むSQLiteとJSONLファイルです。スキーマはsrc/db.jsに記載されています。同じ形式のデータを生成する独自のライターがあれば、このサーバーからそのデータを参照できます。

テスト

npm test

クエリレイヤー（インメモリSQLiteフィクスチャ）、Fastify RESTルート（fastify.inject経由）、MCP サーバー（InMemoryTransport経由のインプロセスと、StreamableHTTPClientTransport経由のエンドツーエンドの両方）、x402ペイウォールとバザール検出の連携、Private Watchのクレジットメーター／ポーラー／サージ料金設定、運用ウォッチドッグを対象とする539件のJestテストがあります。さらに、Streamable HTTP経由でライブのmcp.seneschal.spaceエンドポイントをテストするtest/live-smoke.mjsもあります。

アーキテクチャ

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ファシリテーターが、Baseメインネット上のUSDCを対象とした署名済みEIP-3009 transferWithAuthorizationを決済します。

設定

環境変数	デフォルト	備考
X402_RECIPIENT_ADDRESS	(empty — paywall off)	選択したネットワーク上の受取人ウォレットです。0x で始まる 20 バイトの 16 進数です。
X402_NETWORK	eip155:8453 (Base mainnet)	ファシリテーターがサポートする任意の CAIP-2 EVM ネットワークです。
COINBASE_API_KEY + COINBASE_API_SECRET	(empty)	推奨。 CDP API キーです。両方が設定されている場合、決済は Coinbase のホスト型ファシリテーター（api.cdp.coinbase.com/platform/v2/x402）経由で行われ、サービスは Coinbase x402 Bazaar に自動掲載されます。事業者／KYB の確認は不要です。月 1,000 件の決済が無料です。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

ライブのネットワーク／受取人／料金／ルートの一覧を返すため、エージェントは有料リクエストを開始する前にセッションの予算を見積もれます。

サポート

• 呼び出しごとの支払い（エージェントに推奨）：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 はヘルシンキの 1 台のサーバーで稼働しています。オンライン状態を維持するため、どんな金額でも役立ちます。

ライセンス

MIT — LICENSE をご覧ください。

運営者へのお問い合わせ

Seneschal は、ヘルシンキのコロケーションサーバーで rbuilder のフォークを実行する、単独運営の Ethereum ブロックビルダー兼サーチャーです。 ビルダーのオンチェーン extra_data は Seneschal/0.1 です。Telegram で @OrknetP までご連絡ください（定期的に確認しています）。