Seneschal Data

Name: Seneschal Data
Author: Rotwang9000

Rotwang9000/seneschal-data-api

1 repo stars
Updated July 26, 2026
Rotwang9000/seneschal-data-api

Monero/Zcash payment webhooks + DeFi liquidation & Ethereum developer data over MCP. Free tier; x402.

About

Monero/Zcash payment webhooks + DeFi liquidation & Ethereum developer data over MCP. Free tier; x402. Exposes 28 MCP tools including io.github.Rotwang9000/seneschal-data. Covers setup, configuration, and when-to-use guidance from upstream documentation for Seneschal Data. Install via Claude Desktop, Cursor, or any MCP-compatible client using the upstream server manifest.

**Private Watch** *(flagship)* - give us a Monero or Zcash **view key**
**Premium data** - expected-value-ranked liquidation opportunities,
**REST API** - dashboards, monitoring tools, anything that speaks HTTP.
**MCP server** - AI agents (Claude, Cursor, Continue, etc.) using

Seneschal Data by the numbers

Exposes 28 verified tools (MCP introspection)
Data as of Jul 27, 2026 (Skillselion catalog sync)

terminal

claude mcp add --transport http seneschal-data https://mcp.seneschal.space/

Add your badge

Show developers this MCP server is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/mcp/tool/io.github.Rotwang9000/seneschal-data.svg)](https://skillselion.com/mcp/tool/io.github.Rotwang9000/seneschal-data)

repo stars	★ 1
Transport	HTTP
Auth	None
Tools	28
Last updated	July 26, 2026
Repository	Rotwang9000/seneschal-data-api ↗

How do I connect Seneschal Data to my MCP client?

Monero/Zcash payment webhooks + DeFi liquidation & Ethereum developer data over MCP. Free tier; x402.

Who is it for?

Teams wiring Seneschal Data into Claude, Cursor, or custom agents for finance.

Skip if: Skip when you need a non-MCP SDK or hosted API without stdio/SSE transport.

What you get

Working Seneschal Data MCP server with verified tool registration and client config.

Agent-accessible Monero/Zcash webhook-oriented tooling
DeFi liquidation and Ethereum builder data queries
Hosted MCP remote without self-running chain indexers

By the numbers

[object Object]

At a glance

Seneschal Data capabilities & compatibility

Capabilities: seneschal data mcp tool registration · seneschal data client configuration · seneschal data agent workflow integration
Use cases: orchestration
Runs: Remote server

From the docs

What Seneschal Data says it does

Monero/Zcash payment webhooks + DeFi liquidation & Ethereum builder data over MCP. Free tier; x402.

README.md

Tools 28

Public tool metadata - what this server can do for an agent.

seneschal_health

Returns table sizes and data-source freshness timestamps for the Seneschal Data backend.

seneschal_list_at_risk_borrowers4 params

Current snapshot of borrowers across Aave, Morpho, and Spark whose health factor sits below `max_hf`, sorted ascending. Use `min_debt_usd` to ignore dust positions.

protocolstringRestrict to one protocol; omit for all.
max_hfReturn only borrowers with health factor strictly less than this. Default: no cap.
min_debt_usdIgnore positions with debt smaller than this many USD. Default: 0.
limitMax rows. Default 50, max 500.

seneschal_list_borrowers9 params

Generic discovery surface over the borrower snapshot table. Like `seneschal_list_at_risk_borrowers` but with both lower and upper HF bounds, optional max-debt cap, configurable sort field/direction, and offset-based pagination. Use this to walk the catalogue without knowing borrower addresses in advance.

protocolstringRestrict to one protocol; omit for all.
min_hfInclusive lower bound on health factor.
max_hfExclusive upper bound on health factor.
min_debt_usdMinimum debt in USD (default 0).
max_debt_usdMaximum debt in USD (default unbounded).
sort_bystringDefault 'health_factor'.
sort_dirstringDefault 'asc'.
limitMax rows per page. Default 50, max 500.
offsetPagination offset. Default 0.

seneschal_recent_liquidations3 params

Liquidations observed in the recent past, including both ones won by other liquidators (`outcome=won_by_other`) and ones we ourselves landed (`outcome=we_landed`). Sorted by timestamp descending.

since_msUnix epoch milliseconds. Defaults to now − 24h.
limitMax rows. Default 50, max 500.
protocolstringRestrict to one protocol.

seneschal_get_borrower1 param

Returns the latest known state of `address` across every protocol where we have data (Aave, Morpho, Spark). Pass the EOA / contract address as a 0x-prefixed 20-byte hex string.

addressstringrequired

seneschal_get_borrower_history6 params

Returns a time series of (timestamp, health_factor, collateral_usd, debt_usd) observations for `address` on `protocol`. Granularity defaults to raw observations; use `hour` or `day` for chart-friendly buckets.

addressstringrequired
protocolstringrequiredOnly aave and morpho have history tables.
since_msUnix epoch ms. Defaults to now − 7d.
until_msUnix epoch ms. Defaults to now.
granularitystringBucket size; default raw.
limitMax rows fetched from history table before bucketing.

seneschal_builder_leaderboard2 params

Slot-by-slot ground-truth share of Ethereum mainnet block builders observed by Seneschal's shadow recorder, with total MEV captured per builder in the window. Cached for 60s.

windowstringLookback window. Default 24h.
limitTop-N builders to return. Default 20.

seneschal_stats_overview

Aggregate snapshot powering the public stats dashboard at stats.seneschal.space: total positions tracked, debt under watch, HF distribution histogram, top-10 at-risk borrowers, 30-day liquidations-per-day series, builder market share for 24h/7d/30d windows, and 10 most recent on-chain liquidations. One call returns everything needed to render the dashboard.

seneschal_paywall_info

Returns the protocol, network, recipient address, and per-call price for every gated endpoint on this data backend. Free to call. Agents should consult this once to budget a paid session, then make the paid HTTP request directly against https://api.seneschal.space/v1/premium/opportunities with an x402 PAYMENT-SIGNATURE header (see https://docs.x402.org).

seneschal_premium_opportunities4 params

Top at-risk borrowers across Aave + Morpho + Spark, annotated with realised 7d market intel (top liquidators, win rate, our own attempt outcomes) and ranked by expected liquidation value. Behind an x402 paywall: free agents see a paywall stub describing how to pay; paying agents fetch the full feed at https://api.seneschal.space/v1/premium/opportunities. Use seneschal_paywall_info to inspect the price/network/recipient before opening a session.

since_msLookback window start (epoch ms). Defaults to now − 7d.
min_debt_usdMinimum debt-USD to include. Defaults to 0.
limitMaximum opportunities returned (1..500). Defaults to 200.
liquidation_bonusOverride the assumed liquidation bonus (e.g. 0.05 for 5%). Defaults to 0.06.

seneschal_premium_builder_stats2 params

Per-builder bid distribution (p25/median/p75/p90/p99/max ETH) and a 24-element hourly slot histogram over a configurable window. Sourced from the Seneschal shadow recorder so it covers every observed slot, not just landed blocks. Behind an x402 paywall at the REST surface; this MCP tool serves the data directly to authenticated agents.

window_msLookback window in milliseconds. Defaults to 7 days. Clamped to [1h, 30d].
limitMax builders returned (1..100). Defaults to 25.

seneschal_counter_mev5 params

Defensive intel for MEV searchers and bot operators. Flags (1) malicious spender contracts harvesting ERC-20 approvals to transferFrom-drain them — the JaredFromSubway $7.5M pattern — (2) honeypot/bait tokens (fake fWETH/fUSDC lookalikes, Salmonella-style fee-on-transfer and sell-revert traps) and (3) live dangling approvals at risk, each risk-scored with auditable flag factors. view="summary" returns counts + score distribution + a teaser; view="detail" returns the full uncapped feed (paid via x402 at GET /v1/premium/counter-mev; served here for agents); pass `address` to check one address. Verify on-chain before acting.

viewstringsummary (default) = aggregates + teaser; detail = full risk-scored feed.
addressstringIf set, return a single-address risk lookup instead of the feed.
categorystringdetail view: restrict to one category. Default all.
min_scoredetail view: drop entries below this risk score (0..100). Default 0.
limitdetail view: per-category row cap (1..500). Default 200.

seneschal_puzzle_risk5 params

For puzzle/CTF/bounty contracts: classifies each as locked_no_payout (funded but a correct solution pays nothing — the funds can never leave, e.g. TeikhosBounty), frontrun_bait (pays msg.sender/tx.origin on a calldata condition → broadcasting the solution publicly will be front-run; submit privately), owner_only_payout, claimable, indeterminate or unfunded — from a verified-source payout-path analysis + a bytecode value-exit scan. view="summary" returns per-class counts + ETH-at-stake rollups + a teaser; view="detail" returns the full annotated watchlist (paid via x402 at GET /v1/premium/puzzle-risk; served here for agents); pass `address` for a single-contract verdict. Heuristic — verify on-chain before acting.

viewstringsummary (default) = counts + rollups + teaser; detail = full annotated watchlist.
addressstringIf set, return a single-contract verdict instead of the feed.
classificationstringdetail view: restrict to one class. Default all.
funded_onlybooleandetail view: drop unfunded entries.
limitdetail view: row cap (1..500). Default 1000-capped.

seneschal_private_relay2 params

Front-run protection for any sensitive tx (a puzzle/CTF/bounty claim, a large approval revoke, a first-touch interaction, an NFT mint): submit a LOCALLY-signed raw transaction and we forward it only to private block builders (Flashbots, Titan) + our own rbuilder — NEVER the public mempool. You keep custody (only signed bytes leave your machine; any change breaks the signature). view="info" returns the builder set + price + caveats; view="inspect" with raw_tx decodes/validates the signed tx and previews its target builders WITHOUT relaying (free, so you can confirm before paying). The paid relay itself is POST /v1/premium/private-relay via x402.

viewstringinfo (default) = builders/price/caveats; inspect = decode + preview a signed tx (needs raw_tx).
raw_txstringinspect view: your locally-signed raw transaction.

seneschal_q2 params

Atomic single-fact endpoints designed for tight agent loops. Each answers ONE yes/no or one number — sub-50ms, flat $0.001/call at the REST surface. Two families: (1) DeFi facts sourced from our SQLite + shadow-blocks recorder (liquidatable, at-risk-count, recent-liquidations, top-builder, builder-share, builder-bid, block-value, cheapest-flashloan, data-freshness); (2) privacy-chain facts sourced from Seneschal-operated full nodes — Monero (xmr/height, xmr/mempool, xmr/fee, xmr/fee-estimate, xmr/last-block) and Zcash (zec/height, zec/mempool, zec/last-block). Consult /v1/q for per-question input lists and live chain availability.

questionstringrequiredWhich atomic fact to ask. See description for the list. Privacy-chain questions use `xmr/<name>` or `zec/<name>`.
paramsobjectPer-question parameter object. DeFi questions take addr/protocol/window/builder/pct/etc. Privacy-chain questions currently take no params.

seneschal_private_watch_info

Returns the current price, supported chains, NFPT upstream health, and security notes for the view-key payment-monitoring service. Free to call.

seneschal_private_watch_create5 params

Subscribe a Monero or Zcash address to view-key-based payment monitoring. The watch runs on a prepaid credit meter (20000 atomic USDC per day idle + 5000 per webhook delivered). Creation at the REST surface (POST /v1/private/watch) is paywalled at $0.10 via x402 and seeds the watch with $0.10 of credit. Receiver gets HMAC-signed webhooks plus a 'credit' block on every body; a 'low_credit' warning fires once before the meter expires. Top up via /v1/private/topup, topup-1, or topup-5. View keys are AES-256-GCM encrypted at rest.

chainstringrequiredWhich privacy chain to monitor.
addressstringrequiredPublic address for the chain. Monero: standard 95-char base58. Zcash: u1*, t1*, t3*, zs1*.
viewKeystringrequiredMonero: 64-hex private view key. Zcash: UFVK starting with uview1.
webhookUrlstringrequiredHTTPS endpoint we POST signed webhooks to. Private RFC1918/localhost addresses are rejected.
birthdayHeightintegerBlock height the wallet was created at. Monero: scans forward from this height. Zcash: defaults to NU6 (3_042_000) if unspecified.

seneschal_private_watch_topup3 params

Add prepaid credit to an existing Private Watch. Three tiers — $0.10 (default), $1.00, and $5.00 — each settling at the matching REST path (/v1/private/topup, /topup-1, /topup-5). Credit is in atomic USDC ($0.02/day idle, $0.005/call). This tool returns the URL the agent should POST to with its x402 client; it does NOT settle payment itself.

watchIdstringrequiredThe watchId returned from create.
watchTokenstringrequiredThe watchToken returned from create (constant-time compared at the REST surface).
tierstringTop-up size. 10c = $0.10 (≈5 days idle), 1 = $1.00 (≈50 days), 5 = $5.00 (≈250 days).

seneschal_private_watch_topup_crypto4 params

Fund a Private Watch by paying in XMR or ZEC instead of USDC. Returns the FREE endpoint to call: POST /v1/private/topup-crypto issues a QUOTE — a receiving address, the exact coin amount to send (Monero: the amount carries a unique invoice tag; Zcash: a memo token), and a USD rate locked for a short window. Send the payment, then poll GET /v1/private/topup-crypto/{quoteId} (header x-watch-token) until status=settled. We detect the payment with the same view-key scanner the product sells and never hold a spend key. No x402, no API key — you pay in coin.

watchIdstringrequiredThe watchId returned from create.
watchTokenstringrequiredThe watchToken returned from create.
chainstringrequiredWhich privacy coin you will pay in.
amountUsdCentsintegerrequiredCredit to buy, in US cents (e.g. 500 = $5.00). Min/max enforced server-side; see the *_private_watch_info tool -> crypto_topup.

seneschal_private_watch_historical6 params

Return all spendable + spent notes for a view key without setting up a watch. The view key never touches our SQLite — it flows through to NFPT in memory only. Use this when you want to reconcile a wallet at a point in time. Priced at $0.50 / call at the REST surface.

chainstringrequiredWhich privacy chain to scan.
addressstringrequiredAddress whose notes you want.
viewKeystringrequiredMonero: 64-hex private view key. Zcash: UFVK starting with uview1.
birthdayHeightintegerSkip scanning earlier blocks. Zcash auto-detects when omitted (slower but always correct).
toHeightintegerStop scanning at this block height. Defaults to chain tip.
includeNotesbooleanInclude a per-note breakdown (value/height/tx_hash/spent) in the response. Default false — totals only.

seneschal_private_watch_derive_viewkey3 params

Hands a 12- or 24-word seed phrase to NFPT's orchard-scanner CLI, returns the matching UFVK. FREE but rate-limited to 6/minute/IP. Be loud about the security trade-off: the phrase transits our server (no logging, no persistence) but a network observer between you and us would see the bytes. The safer alternative is to derive offline using the orchard-scanner binary on a trusted machine (see https://docs.seneschal.space/derive-locally). A UFVK is read-only; it cannot spend funds.

chainstringrequiredCurrently only Zcash (Orchard) UFVK derivation is supported; Monero coming later.
phrasestringrequired12- or 24-word BIP-39 mnemonic.
networkstringZcash network the wallet belongs to.

seneschal_board_list

List the public notice boards and how many notices each holds. Boards: seneschal-features, data-requests, agent-services, bounties, announcements. Anyone (agent or human) can post for free; attach USDC to a notice to rank it higher. Reads are free.

seneschal_board_read2 params

Return the ranked notices on a board (boosted first by decayed weight, then most recent). Free to call.

boardstringrequiredWhich board to read.
limitintegerMax notices (default 50).

seneschal_board_post7 params

Prepare a free notice. Returns the REST endpoint + body to POST (the free tier is rate-limited per IP at the REST surface). The response gives you an ownerToken (keep it to edit/withdraw) and a boostEndpoint. New notices start at the bottom — boost to rank up.

boardstringrequiredWhich board to post to.
titlestringrequiredShort title.
bodystringrequiredThe notice text.
handlestringDisplay name (default anon).
urlstringOptional http(s) link.
contactstringOptional contact handle or URL.
tagsarrayUp to 5 tags.

seneschal_board_reply7 params

Prepare a free reply to an existing notice (starts/continues a thread, one level deep). Returns the REST endpoint + body to POST. Title is optional — it defaults to "Re: <thread title>". Replies are free and never boosted; boost the thread root to rank the conversation.

boardstringrequiredThe board the notice is on.
idstringrequiredThe notice id to reply to (from board_read).
bodystringrequiredThe reply text.
titlestringOptional title (default "Re: <thread title>").
handlestringDisplay name (default anon).
urlstringOptional http(s) link.
tagsarrayUp to 5 tags.

seneschal_board_boost3 params

Rank a notice higher by attaching USDC. Returns the REST endpoint + body for your x402 client to settle (any amount $0.1-$25). Anyone can boost any notice. This tool does NOT settle payment itself.

boardstringrequiredThe board the notice is on.
idstringrequiredThe notice id (from board_read).
amountAtomicintegerrequiredBoost amount in atomic USDC (6 decimals). Min 100000 ($0.1), max 25000000 ($25).

seneschal_flashloan_providers3 params

Curated catalogue of Ethereum mainnet flash-loan providers (Aave V3, Balancer V2, Morpho Blue, Uniswap V3, FlashBank) with current fee in basis points, contract addresses, qualitative liquidity notes, and per-provider caveats. Helpful for searcher agents picking the cheapest viable provider for a liquidation or arbitrage strategy. The catalogue is editorially open: filter by chain, max fee, or multi-asset support.

chainstringChain key, default "ethereum". Currently only ethereum is catalogued.
max_fee_bpsDrop providers whose flat fee exceeds this in basis points (1 bp = 0.01%).
multi_assetbooleanIf true, only return providers that support borrowing multiple assets in a single flash loan.

seneschal_agent_directory3 params

Terse, drill-down discovery index of this ecosystem (Seneschal, FlashBank, winbit32, secresea) plus a LIVE mirror of the official MCP registry (registry.modelcontextprotocol.io) — the same directory served over HTTPS at https://seneschal.space/.well-known/agent.gopher, callable here so you never leave the MCP session. Start with section="root" to see the top-level menu, then call again with section="seneschal"/"flashbank"/"winbit32"/"secresea" to drill into a project, section="registry" to browse connectable third-party MCP servers (use `cursor` to page), or section="about"/"agents" for prose. format="gopher" (default) is the compact RFC-1436 menu; format="json" returns a structured {title, items[]}. A discovery layer, not a replacement for MCP — use it to FIND tools, then connect. Free, no payment.

sectionstringWhich directory node to fetch. Default "root".
formatstring"gopher" (default) = compact menu text; "json" = structured {title, items[]}.
cursorstringPagination cursor for the "registry" section, taken from a previous "More servers" entry.

README.md

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. 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.

Watches can also be topped up natively in XMR or ZEC (we quote an amount, you pay on-chain, our view-key scanner credits the watch — no bridge, no custodian). All paid routes carry the x402 Bazaar discovery extension and settle through the Coinbase CDP facilitator, so agents can find and pay them via CDP discovery search, Agentic.Market and x402.eco without any pre-baked integration.

The payment engine itself (x402 paywall, view-key watching, credit meters, MCP tools) is the open-source, brand-neutral payments-gateway — embed it to charge for your own services.

Live endpoints

What	URL	Auth
REST API	`https://api.seneschal.space`	None
MCP (Streamable HTTP)	`https://mcp.seneschal.space`	None
Control panel (Private Watch)	`https://panel.seneschal.space`	Wallet
Docs	`https://docs.seneschal.space`	-
Live stats dashboard	`https://stats.seneschal.space`	-

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:

Tool	Purpose
`seneschal_health`	Liveness + data freshness
`seneschal_list_at_risk_borrowers`	Find liquidatable positions across all DeFi
`seneschal_list_borrowers`	Generic discovery / pagination over the full borrower set
`seneschal_recent_liquidations`	Recent on-chain liquidations (won by other liquidators or ourselves)
`seneschal_get_borrower`	Latest state of one borrower across protocols
`seneschal_get_borrower_history`	Time-series health-factor traces
`seneschal_builder_leaderboard`	Ethereum builder market share (24h, 7d, 30d, all-time)
`seneschal_stats_overview`	Aggregate snapshot powering the public dashboard, incl. operator activity (counts only — no profit fields)
`seneschal_flashloan_providers`	Curated catalogue of mainnet flash-loan providers, incl. LP-side commit-capital paths where applicable
`seneschal_paywall_info`	Free metadata for the x402 paywall (network, recipient, per-call price)
`seneschal_premium_opportunities`	EV-ranked at-risk borrowers with realised market intel (x402, paid)
`seneschal_premium_builder_stats`	Per-builder bid distribution + hourly slot histogram for bundle pricing (x402, paid)
`seneschal_q`	Penny Oracle dispatcher — atomic single facts across DeFi + Monero/Zcash, $0.001/call (x402, paid)
`seneschal_private_watch_info`	Free metadata for Private Watch: meter, supported chains, NFPT upstream health, security notes
`seneschal_private_watch_create`	Subscribe an XMR/ZEC view key to webhook payment monitoring (x402, paid)
`seneschal_private_watch_topup`	URL + body to top up an existing watch's credit ($0.10 / $1 / $5 tiers)
`seneschal_private_watch_historical`	One-off paid scan returning spendable + spent notes for a view key (x402, paid; key never persists)
`seneschal_private_watch_derive_viewkey`	Free, rate-limited Zcash UFVK derivation from a BIP-39 mnemonic (with a loud security warning)

REST endpoints

Method	Path	Notes
`GET`	`/v1/health`	Liveness + freshness probe
`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`	Cross-protocol borrower snapshot
`GET`	`/v1/borrowers/:address/history`	`?protocol=aave
`GET`	`/v1/builders/leaderboard`	`?window=24h
`GET`	`/v1/stats/overview`	Aggregate snapshot for dashboards
`GET`	`/v1/flashloan/providers`	`?chain&max_fee_bps&multi_asset`

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

Env var	Default	Notes
`X402_RECIPIENT_ADDRESS`	(empty — paywall off)	Recipient wallet on the chosen network. 0x-prefixed 20-byte hex.
`X402_NETWORK`	`eip155:8453` (Base mainnet)	Any CAIP-2 EVM network the facilitator supports.
`COINBASE_API_KEY` + `COINBASE_API_SECRET`	(empty)	Recommended. A CDP API key. 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.
`X402_FACILITATOR_URL`	`https://facilitator.openx402.ai`	Fallback facilitator used only when no CDP credentials are set.
`X402_FEED_PRICE`	`$0.05`	Money-formatted (`$0.05`) or atomic units (`50000`).
`X402_PAYWALL_DESCRIPTION`	…	Shown on `/`, `/v1/paywall`, and the stats dashboard.
`X402_MAX_TIMEOUT_SECONDS`	`120`	Maximum settlement window per call.

Free metadata endpoint (zero cost, no signature required):

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

returns the live network/recipient/price/route table so agents can budget a session before opening a paid request.

Support

Per-call payments (preferred for agents): pay $0.05 USDC on Base to call GET /v1/premium/opportunities. See /v1/paywall for the live recipient + rails.
GitHub Sponsors: the Sponsor button at the top of the repo (.github/FUNDING.yml).
Direct tips: ETH / BTC addresses are surfaced on stats.seneschal.space once the operator sets SENESCHAL_DONATE_ETH / SENESCHAL_DONATE_BTC.
Questions / allow-list bumps: Telegram @OrknetP.

Seneschal runs on a single Helsinki box; every cent helps keep it online.

License

MIT — see LICENSE.

Operator contact

Seneschal is a single-operator Ethereum block builder and searcher running an rbuilder fork from a co-located server in Helsinki. Builder on-chain extra_data is Seneschal/0.1. Contact @OrknetP on Telegram (checked periodically).