Seneschal Data

Official31 toolsLive

by Rotwang9000 · JavaScript

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

Seneschal Data (MCP)

This MCP server exposes real-time and historical DeFi liquidation telemetry and Ethereum block-builder data via MCP. It also provides a free, public REST API. The DeFi portion covers liquidation telemetry for Aave, Morpho, Spark, and Compound on Ethereum mainnet, and the builder portion includes block-builder market share data from the operator’s own slot-by-slot shadow recorder.

🛠️ Key Features

MCP server for DeFi liquidation telemetry and Ethereum builder data
Real-time and historical liquidation telemetry (Aave, Morpho, Spark, Compound)
Block-builder market share data from a slot-by-slot shadow recorder
31 tools; free tier available

🚀 Use Cases

Monitoring liquidation activity across Ethereum mainnet protocols
Tracking Ethereum block-builder market share metrics over time
Combining payment webhooks with DeFi/Builder data in MCP-based apps

⚡ Developer Benefits

Access via MCP (and free public REST)
Supports multiple data domains: ethereum, monero, zcash, and payment-webhooks
Tooling surface indicates broad integration options (31 tools)

⚠️ Limitations

Source text specifies a free tier and “two paid tiers” without details on functionality scope.

Topics

ethereummcpmoneroprivacy-coinswebhooksx402zcashpayment-webhooks

Captured live from the server via tools/list.

seneschal_health

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

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

seneschal_list_at_risk_borrowers

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.

Parameters4

protocol	string	optional	Restrict to one protocol; omit for all.
max_hf	any	optional	Return only borrowers with health factor strictly less than this. Default: no cap.
min_debt_usd	any	optional	Ignore positions with debt smaller than this many USD. Default: 0.
limit	any	optional	Max rows. Default 50, max 500.

Raw schema

{
  "type": "object",
  "properties": {
    "protocol": {
      "description": "Restrict to one protocol; omit for all.",
      "type": "string",
      "enum": [
        "aave",
        "morpho",
        "spark",
        "compound"
      ]
    },
    "max_hf": {
      "description": "Return only borrowers with health factor strictly less than this. Default: no cap.",
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string",
          "pattern": "^-?\\d+(\\.\\d+)?$"
        }
      ]
    },
    "min_debt_usd": {
      "description": "Ignore positions with debt smaller than this many USD. Default: 0.",
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string",
          "pattern": "^-?\\d+(\\.\\d+)?$"
        }
      ]
    },
    "limit": {
      "description": "Max rows. Default 50, max 500.",
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "string",
          "pattern": "^-?\\d+$"
        }
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

seneschal_list_borrowers

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.

Parameters9

protocol	string	optional	Restrict to one protocol; omit for all.
min_hf	any	optional	Inclusive lower bound on health factor.
max_hf	any	optional	Exclusive upper bound on health factor.
min_debt_usd	any	optional	Minimum debt in USD (default 0).
max_debt_usd	any	optional	Maximum debt in USD (default unbounded).
sort_by	string	optional	Default 'health_factor'.
sort_dir	string	optional	Default 'asc'.
limit	any	optional	Max rows per page. Default 50, max 500.
offset	any	optional	Pagination offset. Default 0.

Raw schema

{
  "type": "object",
  "properties": {
    "protocol": {
      "description": "Restrict to one protocol; omit for all.",
      "type": "string",
      "enum": [
        "aave",
        "morpho",
        "spark",
        "compound"
      ]
    },
    "min_hf": {
      "description": "Inclusive lower bound on health factor.",
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string",
          "pattern": "^-?\\d+(\\.\\d+)?$"
        }
      ]
    },
    "max_hf": {
      "description": "Exclusive upper bound on health factor.",
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string",
          "pattern": "^-?\\d+(\\.\\d+)?$"
        }
      ]
    },
    "min_debt_usd": {
      "description": "Minimum debt in USD (default 0).",
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string",
          "pattern": "^-?\\d+(\\.\\d+)?$"
        }
      ]
    },
    "max_debt_usd": {
      "description": "Maximum debt in USD (default unbounded).",
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string",
          "pattern": "^-?\\d+(\\.\\d+)?$"
        }
      ]
    },
    "sort_by": {
      "description": "Default 'health_factor'.",
      "type": "string",
      "enum": [
        "health_factor",
        "debt_usd",
        "collateral_usd",
        "last_observed_ms"
      ]
    },
    "sort_dir": {
      "description": "Default 'asc'.",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    },
    "limit": {
      "description": "Max rows per page. Default 50, max 500.",
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "string",
          "pattern": "^-?\\d+$"
        }
      ]
    },
    "offset": {
      "description": "Pagination offset. Default 0.",
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string",
          "pattern": "^-?\\d+(\\.\\d+)?$"
        }
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

seneschal_recent_liquidations

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.

Parameters3

since_ms	any	optional	Unix epoch milliseconds. Defaults to now − 24h.
limit	any	optional	Max rows. Default 50, max 500.
protocol	string	optional	Restrict to one protocol.

Raw schema

{
  "type": "object",
  "properties": {
    "since_ms": {
      "description": "Unix epoch milliseconds. Defaults to now − 24h.",
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "string",
          "pattern": "^-?\\d+$"
        }
      ]
    },
    "limit": {
      "description": "Max rows. Default 50, max 500.",
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "string",
          "pattern": "^-?\\d+$"
        }
      ]
    },
    "protocol": {
      "description": "Restrict to one protocol.",
      "type": "string",
      "enum": [
        "aave",
        "morpho",
        "spark",
        "compound"
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

seneschal_get_borrower

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.

Parameters1

address

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$"
    }
  },
  "required": [
    "address"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

seneschal_get_borrower_history

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.

Parameters6

address	string	required
protocol	string	required	Only aave and morpho have history tables.
since_ms	any	optional	Unix epoch ms. Defaults to now − 7d.
until_ms	any	optional	Unix epoch ms. Defaults to now.
granularity	string	optional	Bucket size; default raw.
limit	any	optional	Max rows fetched from history table before bucketing.

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$"
    },
    "protocol": {
      "type": "string",
      "enum": [
        "aave",
        "morpho"
      ],
      "description": "Only aave and morpho have history tables."
    },
    "since_ms": {
      "description": "Unix epoch ms. Defaults to now − 7d.",
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "string",
          "pattern": "^-?\\d+$"
        }
      ]
    },
    "until_ms": {
      "description": "Unix epoch ms. Defaults to now.",
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "string",
          "pattern": "^-?\\d+$"
        }
      ]
    },
    "granularity": {
      "description": "Bucket size; default raw.",
      "type": "string",
      "enum": [
        "raw",
        "hour",
        "day"
      ]
    },
    "limit": {
      "description": "Max rows fetched from history table before bucketing.",
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "string",
          "pattern": "^-?\\d+$"
        }
      ]
    }
  },
  "required": [
    "address",
    "protocol"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

seneschal_builder_leaderboard

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.

Parameters2

window	string	optional	Lookback window. Default 24h.
limit	any	optional	Top-N builders to return. Default 20.

Raw schema

{
  "type": "object",
  "properties": {
    "window": {
      "description": "Lookback window. Default 24h.",
      "type": "string",
      "enum": [
        "24h",
        "7d",
        "30d",
        "all"
      ]
    },
    "limit": {
      "description": "Top-N builders to return. Default 20.",
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "string",
          "pattern": "^-?\\d+$"
        }
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

seneschal_premium_opportunities

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.

Parameters4

since_ms	any	optional	Lookback window start (epoch ms). Defaults to now − 7d.
min_debt_usd	any	optional	Minimum debt-USD to include. Defaults to 0.
limit	any	optional	Maximum opportunities returned (1..500). Defaults to 200.
liquidation_bonus	any	optional	Override the assumed liquidation bonus (e.g. 0.05 for 5%). Defaults to 0.06.

Raw schema

{
  "type": "object",
  "properties": {
    "since_ms": {
      "description": "Lookback window start (epoch ms). Defaults to now − 7d.",
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "string",
          "pattern": "^-?\\d+$"
        }
      ]
    },
    "min_debt_usd": {
      "description": "Minimum debt-USD to include. Defaults to 0.",
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string",
          "pattern": "^-?\\d+(\\.\\d+)?$"
        }
      ]
    },
    "limit": {
      "description": "Maximum opportunities returned (1..500). Defaults to 200.",
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "string",
          "pattern": "^-?\\d+$"
        }
      ]
    },
    "liquidation_bonus": {
      "description": "Override the assumed liquidation bonus (e.g. 0.05 for 5%). Defaults to 0.06.",
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string",
          "pattern": "^-?\\d+(\\.\\d+)?$"
        }
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

seneschal_premium_builder_stats

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.

Parameters2

window_ms	any	optional	Lookback window in milliseconds. Defaults to 7 days. Clamped to [1h, 30d].
limit	any	optional	Max builders returned (1..100). Defaults to 25.

Raw schema

{
  "type": "object",
  "properties": {
    "window_ms": {
      "description": "Lookback window in milliseconds. Defaults to 7 days. Clamped to [1h, 30d].",
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "string",
          "pattern": "^-?\\d+$"
        }
      ]
    },
    "limit": {
      "description": "Max builders returned (1..100). Defaults to 25.",
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "string",
          "pattern": "^-?\\d+$"
        }
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

seneschal_counter_mev

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.

Parameters5

view	string	optional	summary (default) = aggregates + teaser; detail = full risk-scored feed.
address	string	optional	If set, return a single-address risk lookup instead of the feed.
category	string	optional	detail view: restrict to one category. Default all.
min_score	any	optional	detail view: drop entries below this risk score (0..100). Default 0.
limit	any	optional	detail view: per-category row cap (1..500). Default 200.

Raw schema

{
  "type": "object",
  "properties": {
    "view": {
      "description": "summary (default) = aggregates + teaser; detail = full risk-scored feed.",
      "type": "string",
      "enum": [
        "summary",
        "detail"
      ]
    },
    "address": {
      "description": "If set, return a single-address risk lookup instead of the feed.",
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$"
    },
    "category": {
      "description": "detail view: restrict to one category. Default all.",
      "type": "string",
      "enum": [
        "all",
        "spenders",
        "tokens",
        "approvals",
        "bleeding_bots"
      ]
    },
    "min_score": {
      "description": "detail view: drop entries below this risk score (0..100). Default 0.",
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string",
          "pattern": "^-?\\d+(\\.\\d+)?$"
        }
      ]
    },
    "limit": {
      "description": "detail view: per-category row cap (1..500). Default 200.",
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "string",
          "pattern": "^-?\\d+$"
        }
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

seneschal_puzzle_risk

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.

Parameters5

view	string	optional	summary (default) = counts + rollups + teaser; detail = full annotated watchlist.
address	string	optional	If set, return a single-contract verdict instead of the feed.
classification	string	optional	detail view: restrict to one class. Default all.
funded_only	boolean	optional	detail view: drop unfunded entries.
limit	any	optional	detail view: row cap (1..500). Default 1000-capped.

Raw schema

{
  "type": "object",
  "properties": {
    "view": {
      "description": "summary (default) = counts + rollups + teaser; detail = full annotated watchlist.",
      "type": "string",
      "enum": [
        "summary",
        "detail"
      ]
    },
    "address": {
      "description": "If set, return a single-contract verdict instead of the feed.",
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$"
    },
    "classification": {
      "description": "detail view: restrict to one class. Default all.",
      "type": "string",
      "enum": [
        "all",
        "locked_no_payout",
        "frontrun_bait",
        "owner_only_payout",
        "claimable",
        "indeterminate",
        "unfunded"
      ]
    },
    "funded_only": {
      "description": "detail view: drop unfunded entries.",
      "type": "boolean"
    },
    "limit": {
      "description": "detail view: row cap (1..500). Default 1000-capped.",
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "string",
          "pattern": "^-?\\d+$"
        }
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

seneschal_private_relay

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.

Parameters2

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

Raw schema

{
  "type": "object",
  "properties": {
    "view": {
      "description": "info (default) = builders/price/caveats; inspect = decode + preview a signed tx (needs raw_tx).",
      "type": "string",
      "enum": [
        "info",
        "inspect"
      ]
    },
    "raw_tx": {
      "description": "inspect view: your locally-signed raw transaction.",
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]+$"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

seneschal_q

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, address-risk, base-fee, proposer-payment); (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, zec/pools). Consult /v1/q for per-question input lists and live chain availability.

Parameters2

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

Raw schema

{
  "type": "object",
  "properties": {
    "question": {
      "type": "string",
      "enum": [
        "liquidatable",
        "at-risk-count",
        "recent-liquidations",
        "top-builder",
        "builder-share",
        "builder-bid",
        "block-value",
        "cheapest-flashloan",
        "data-freshness",
        "address-risk",
        "base-fee",
        "proposer-payment",
        "xmr/height",
        "xmr/mempool",
        "xmr/fee",
        "xmr/fee-estimate",
        "xmr/last-block",
        "zec/height",
        "zec/mempool",
        "zec/last-block",
        "zec/pools"
      ],
      "description": "Which atomic fact to ask. See description for the list. Privacy-chain questions use `xmr/<name>` or `zec/<name>`."
    },
    "params": {
      "description": "Per-question parameter object. DeFi questions take addr/protocol/window/builder/pct/etc. Privacy-chain questions currently take no params.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "required": [
    "question"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

seneschal_private_watch_create

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.

Parameters5

chain	string	required	Which privacy chain to monitor.
address	string	required	Public address for the chain. Monero: standard 95-char base58. Zcash: u1, t1, t3, zs1.
viewKey	string	required	Monero: 64-hex private view key. Zcash: UFVK starting with uview1.
webhookUrl	string	required	HTTPS endpoint we POST signed webhooks to. Private RFC1918/localhost addresses are rejected.
birthdayHeight	integer	optional	Block height the wallet was created at. Monero: scans forward from this height. Zcash: defaults to NU6 (3_042_000) if unspecified.

Raw schema

{
  "type": "object",
  "properties": {
    "chain": {
      "type": "string",
      "enum": [
        "monero",
        "zcash"
      ],
      "description": "Which privacy chain to monitor."
    },
    "address": {
      "type": "string",
      "minLength": 1,
      "description": "Public address for the chain. Monero: standard 95-char base58. Zcash: u1*, t1*, t3*, zs1*."
    },
    "viewKey": {
      "type": "string",
      "minLength": 1,
      "description": "Monero: 64-hex private view key. Zcash: UFVK starting with uview1."
    },
    "webhookUrl": {
      "type": "string",
      "minLength": 1,
      "description": "HTTPS endpoint we POST signed webhooks to. Private RFC1918/localhost addresses are rejected."
    },
    "birthdayHeight": {
      "description": "Block height the wallet was created at. Monero: scans forward from this height. Zcash: defaults to NU6 (3_042_000) if unspecified.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "chain",
    "address",
    "viewKey",
    "webhookUrl"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

seneschal_private_watch_topup

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.

Parameters3

watchId	string	required	The watchId returned from create.
watchToken	string	required	The watchToken returned from create (constant-time compared at the REST surface).
tier	string	optional	Top-up size. 10c = $0.10 (≈5 days idle), 1 = $1.00 (≈50 days), 5 = $5.00 (≈250 days).

Raw schema

{
  "type": "object",
  "properties": {
    "watchId": {
      "type": "string",
      "minLength": 36,
      "maxLength": 36,
      "description": "The watchId returned from create."
    },
    "watchToken": {
      "type": "string",
      "minLength": 1,
      "description": "The watchToken returned from create (constant-time compared at the REST surface)."
    },
    "tier": {
      "default": "10c",
      "description": "Top-up size. 10c = $0.10 (≈5 days idle), 1 = $1.00 (≈50 days), 5 = $5.00 (≈250 days).",
      "type": "string",
      "enum": [
        "1",
        "5",
        "10c"
      ]
    }
  },
  "required": [
    "watchId",
    "watchToken"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

seneschal_private_watch_create_crypto

The all-coin onboarding path: POST /v1/private/watch-crypto creates a Monero/Zcash payment watch AND returns a coin payment quote in one call — no x402, no USDC, no EVM wallet anywhere in the flow. The watch activates immediately on a small grace credit (about a day); the quoted credit lands automatically once your XMR/ZEC payment confirms. Returns the FREE endpoint + body to call. Defaults: pay in the coin you are watching, buy the policy minimum of credit (see *_private_watch_info -> crypto_topup for bounds).

Parameters7

chain	string	required	Which privacy chain to monitor.
address	string	required	Public address for the chain. Monero: standard 95-char base58. Zcash: u1, t1, t3, zs1.
viewKey	string	required	Monero: 64-hex private view key. Zcash: UFVK starting with uview1.
webhookUrl	string	required	HTTPS endpoint we POST signed webhooks to.
birthdayHeight	integer	optional	Optional scan-from height.
payWith	string	optional	Coin to pay in; defaults to `chain`.
amountUsdCents	integer	optional	Credit to buy in US cents; defaults to the server minimum.

Raw schema

{
  "type": "object",
  "properties": {
    "chain": {
      "type": "string",
      "enum": [
        "monero",
        "zcash"
      ],
      "description": "Which privacy chain to monitor."
    },
    "address": {
      "type": "string",
      "minLength": 1,
      "description": "Public address for the chain. Monero: standard 95-char base58. Zcash: u1*, t1*, t3*, zs1*."
    },
    "viewKey": {
      "type": "string",
      "minLength": 1,
      "description": "Monero: 64-hex private view key. Zcash: UFVK starting with uview1."
    },
    "webhookUrl": {
      "type": "string",
      "minLength": 1,
      "description": "HTTPS endpoint we POST signed webhooks to."
    },
    "birthdayHeight": {
      "description": "Optional scan-from height.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "payWith": {
      "description": "Coin to pay in; defaults to `chain`.",
      "type": "string",
      "enum": [
        "monero",
        "zcash"
      ]
    },
    "amountUsdCents": {
      "description": "Credit to buy in US cents; defaults to the server minimum.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "chain",
    "address",
    "viewKey",
    "webhookUrl"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

seneschal_private_watch_topup_crypto

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.

Parameters4

watchId	string	required	The watchId returned from create.
watchToken	string	required	The watchToken returned from create.
chain	string	required	Which privacy coin you will pay in.
amountUsdCents	integer	required	Credit to buy, in US cents (e.g. 500 = $5.00). Min/max enforced server-side; see the *_private_watch_info tool -> crypto_topup.

Raw schema

{
  "type": "object",
  "properties": {
    "watchId": {
      "type": "string",
      "minLength": 36,
      "maxLength": 36,
      "description": "The watchId returned from create."
    },
    "watchToken": {
      "type": "string",
      "minLength": 1,
      "description": "The watchToken returned from create."
    },
    "chain": {
      "type": "string",
      "enum": [
        "monero",
        "zcash"
      ],
      "description": "Which privacy coin you will pay in."
    },
    "amountUsdCents": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Credit to buy, in US cents (e.g. 500 = $5.00). Min/max enforced server-side; see the *_private_watch_info tool -> crypto_topup."
    }
  },
  "required": [
    "watchId",
    "watchToken",
    "chain",
    "amountUsdCents"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

seneschal_checkout_invoice_create

Accept an XMR/ZEC payment INTO YOUR OWN WALLET: creates a checkout invoice against your Private Watch (your address, your view key). Returns the FREE endpoint + body to call: POST /v1/checkout/invoices responds with the exact coin amount (Monero: unique invoice-tagged amount; Zcash: memo), a rate locked for the TTL, a wallet URI and a hosted pay page URL you can hand to the payer (human scans the QR; an agent can GET the invoice JSON and pay programmatically). When the payment confirms you get an invoice_paid webhook signed with your existing watch secret, and a flat settlement fee (~$0.02) is debited from the watch credit meter — never a percentage. Use your watchId+watchToken server-side, or a restricted checkoutKey (mint one with POST /v1/checkout/keys) anywhere you cannot keep secrets.

Parameters8

amountUsdCents	integer	required	Sale amount in US cents (e.g. 500 = $5.00). Converted to coin at a locked rate.
watchId	string	optional	Your watchId (pair with watchToken). Omit when using checkoutKey.
watchToken	string	optional	Your watchToken. Keep server-side.
checkoutKey	string	optional	Restricted ck_… key minted via POST /v1/checkout/keys — safe for client-side/bot use; can only create invoices paying your wallet.
orderId	string	optional	Your order reference; echoed on the invoice, the pay page and every webhook.
description	string	optional	Shown to the payer on the hosted pay page.
successUrl	string	optional	Where the pay page sends the payer after payment confirms.
ttlMinutes	integer	optional	Invoice lifetime (default 30). The exchange rate is locked for the whole TTL.

Raw schema

{
  "type": "object",
  "properties": {
    "amountUsdCents": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Sale amount in US cents (e.g. 500 = $5.00). Converted to coin at a locked rate."
    },
    "watchId": {
      "description": "Your watchId (pair with watchToken). Omit when using checkoutKey.",
      "type": "string",
      "minLength": 36,
      "maxLength": 36
    },
    "watchToken": {
      "description": "Your watchToken. Keep server-side.",
      "type": "string",
      "minLength": 8
    },
    "checkoutKey": {
      "description": "Restricted ck_… key minted via POST /v1/checkout/keys — safe for client-side/bot use; can only create invoices paying your wallet.",
      "type": "string",
      "minLength": 1
    },
    "orderId": {
      "description": "Your order reference; echoed on the invoice, the pay page and every webhook.",
      "type": "string",
      "maxLength": 120
    },
    "description": {
      "description": "Shown to the payer on the hosted pay page.",
      "type": "string",
      "maxLength": 200
    },
    "successUrl": {
      "description": "Where the pay page sends the payer after payment confirms.",
      "type": "string"
    },
    "ttlMinutes": {
      "description": "Invoice lifetime (default 30). The exchange rate is locked for the whole TTL.",
      "type": "integer",
      "minimum": 5,
      "maximum": 1440
    }
  },
  "required": [
    "amountUsdCents"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

seneschal_checkout_invoice_status

Poll the state of a checkout invoice: pending (waiting for payment) -> confirming (payment seen, counting confirmations) -> paid | underpaid | expired | cancelled. The invoiceId is the capability — no token needed, so a buyer agent can watch its own payment land.

Parameters1

invoiceId

string

required

The invoiceId returned from create.

Raw schema

{
  "type": "object",
  "properties": {
    "invoiceId": {
      "type": "string",
      "minLength": 36,
      "maxLength": 36,
      "description": "The invoiceId returned from create."
    }
  },
  "required": [
    "invoiceId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

seneschal_private_watch_historical

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.

Parameters6

chain	string	required	Which privacy chain to scan.
address	string	required	Address whose notes you want.
viewKey	string	required	Monero: 64-hex private view key. Zcash: UFVK starting with uview1.
birthdayHeight	integer	optional	Skip scanning earlier blocks. Zcash auto-detects when omitted (slower but always correct).
toHeight	integer	optional	Stop scanning at this block height. Defaults to chain tip.
includeNotes	boolean	optional	Include a per-note breakdown (value/height/tx_hash/spent) in the response. Default false — totals only.

Raw schema

{
  "type": "object",
  "properties": {
    "chain": {
      "type": "string",
      "enum": [
        "monero",
        "zcash"
      ],
      "description": "Which privacy chain to scan."
    },
    "address": {
      "type": "string",
      "minLength": 1,
      "description": "Address whose notes you want."
    },
    "viewKey": {
      "type": "string",
      "minLength": 1,
      "description": "Monero: 64-hex private view key. Zcash: UFVK starting with uview1."
    },
    "birthdayHeight": {
      "description": "Skip scanning earlier blocks. Zcash auto-detects when omitted (slower but always correct).",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "toHeight": {
      "description": "Stop scanning at this block height. Defaults to chain tip.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "includeNotes": {
      "description": "Include a per-note breakdown (value/height/tx_hash/spent) in the response. Default false — totals only.",
      "type": "boolean"
    }
  },
  "required": [
    "chain",
    "address",
    "viewKey"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

seneschal_private_watch_derive_viewkey

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.

Parameters3

chain	string	required	Currently only Zcash (Orchard) UFVK derivation is supported; Monero coming later.
phrase	string	required	12- or 24-word BIP-39 mnemonic.
network	string	optional	Zcash network the wallet belongs to.

Raw schema

{
  "type": "object",
  "properties": {
    "chain": {
      "type": "string",
      "enum": [
        "zcash"
      ],
      "description": "Currently only Zcash (Orchard) UFVK derivation is supported; Monero coming later."
    },
    "phrase": {
      "type": "string",
      "minLength": 1,
      "description": "12- or 24-word BIP-39 mnemonic."
    },
    "network": {
      "default": "mainnet",
      "description": "Zcash network the wallet belongs to.",
      "type": "string",
      "enum": [
        "mainnet",
        "testnet",
        "regtest"
      ]
    }
  },
  "required": [
    "chain",
    "phrase"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

seneschal_board_read

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

Parameters2

board	string	required	Which board to read.
limit	integer	optional	Max notices (default 50).

Raw schema

{
  "type": "object",
  "properties": {
    "board": {
      "type": "string",
      "enum": [
        "seneschal-features",
        "data-requests",
        "agent-services",
        "bounties",
        "announcements"
      ],
      "description": "Which board to read."
    },
    "limit": {
      "description": "Max notices (default 50).",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    }
  },
  "required": [
    "board"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

seneschal_board_post

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.

Parameters7

board	string	required	Which board to post to.
title	string	required	Short title.
body	string	required	The notice text.
handle	string	optional	Display name (default anon).
url	string	optional	Optional http(s) link.
contact	string	optional	Optional contact handle or URL.
tags	array	optional	Up to 5 tags.

Raw schema

{
  "type": "object",
  "properties": {
    "board": {
      "type": "string",
      "enum": [
        "seneschal-features",
        "data-requests",
        "agent-services",
        "bounties",
        "announcements"
      ],
      "description": "Which board to post to."
    },
    "title": {
      "type": "string",
      "minLength": 3,
      "maxLength": 160,
      "description": "Short title."
    },
    "body": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1200,
      "description": "The notice text."
    },
    "handle": {
      "description": "Display name (default anon).",
      "type": "string",
      "maxLength": 48
    },
    "url": {
      "description": "Optional http(s) link.",
      "type": "string",
      "maxLength": 400
    },
    "contact": {
      "description": "Optional contact handle or URL.",
      "type": "string",
      "maxLength": 140
    },
    "tags": {
      "description": "Up to 5 tags.",
      "maxItems": 5,
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "board",
    "title",
    "body"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

seneschal_board_reply

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.

Parameters7

board	string	required	The board the notice is on.
id	string	required	The notice id to reply to (from board_read).
body	string	required	The reply text.
title	string	optional	Optional title (default "Re: <thread title>").
handle	string	optional	Display name (default anon).
url	string	optional	Optional http(s) link.
tags	array	optional	Up to 5 tags.

Raw schema

{
  "type": "object",
  "properties": {
    "board": {
      "type": "string",
      "enum": [
        "seneschal-features",
        "data-requests",
        "agent-services",
        "bounties",
        "announcements"
      ],
      "description": "The board the notice is on."
    },
    "id": {
      "type": "string",
      "minLength": 1,
      "description": "The notice id to reply to (from board_read)."
    },
    "body": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1200,
      "description": "The reply text."
    },
    "title": {
      "description": "Optional title (default \"Re: <thread title>\").",
      "type": "string",
      "minLength": 3,
      "maxLength": 160
    },
    "handle": {
      "description": "Display name (default anon).",
      "type": "string",
      "maxLength": 48
    },
    "url": {
      "description": "Optional http(s) link.",
      "type": "string",
      "maxLength": 400
    },
    "tags": {
      "description": "Up to 5 tags.",
      "maxItems": 5,
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "board",
    "id",
    "body"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

seneschal_board_boost

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.

Parameters3

board	string	required	The board the notice is on.
id	string	required	The notice id (from board_read).
amountAtomic	integer	required	Boost amount in atomic USDC (6 decimals). Min 100000 ($0.1), max 25000000 ($25).

Raw schema

{
  "type": "object",
  "properties": {
    "board": {
      "type": "string",
      "enum": [
        "seneschal-features",
        "data-requests",
        "agent-services",
        "bounties",
        "announcements"
      ],
      "description": "The board the notice is on."
    },
    "id": {
      "type": "string",
      "minLength": 1,
      "description": "The notice id (from board_read)."
    },
    "amountAtomic": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Boost amount in atomic USDC (6 decimals). Min 100000 ($0.1), max 25000000 ($25)."
    }
  },
  "required": [
    "board",
    "id",
    "amountAtomic"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

seneschal_flashloan_providers

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.

Parameters3

chain	string	optional	Chain key, default "ethereum". Currently only ethereum is catalogued.
max_fee_bps	any	optional	Drop providers whose flat fee exceeds this in basis points (1 bp = 0.01%).
multi_asset	boolean	optional	If true, only return providers that support borrowing multiple assets in a single flash loan.

Raw schema

{
  "type": "object",
  "properties": {
    "chain": {
      "description": "Chain key, default \"ethereum\". Currently only ethereum is catalogued.",
      "type": "string"
    },
    "max_fee_bps": {
      "description": "Drop providers whose flat fee exceeds this in basis points (1 bp = 0.01%).",
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ]
    },
    "multi_asset": {
      "description": "If true, only return providers that support borrowing multiple assets in a single flash loan.",
      "type": "boolean"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

seneschal_agent_directory

Terse, drill-down discovery index of this ecosystem (Seneschal, FlashBank, winbit32, secresea, ZecBus) 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"/"zecbus" to drill into a project. Each project exposes About / Agents / Actions — drill them with section="<site>/about", "<site>/agents" or "<site>/actions" (e.g. "winbit32/actions"). Seneschal additionally drills into its own services with section="seneschal/<service>" where <service> is one of private-watch, checkout, oracle, shovels, builder, data, paymaster, board, ironwood, mcp — every website + MCP capability, grouped and priced. section="registry" browses connectable third-party MCP servers (use `cursor` to page); section="about"/"agents" is the directory’s own 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.

Parameters3

section	string	optional	Which directory node to fetch. Default "root". Top level: root, seneschal, flashbank, winbit32, secresea, zecbus, registry, about, agents. Drill a project with "<site>/about", "<site>/agents" or "<site>/actions" (e.g. "winbit32/actions"). Seneschal also exposes per-service sections: "seneschal/private-watch", "seneschal/checkout", "seneschal/oracle", "seneschal/shovels", "seneschal/builder", "seneschal/data", "seneschal/paymaster", "seneschal/board", "seneschal/ironwood", "seneschal/mcp".
format	string	optional	"gopher" (default) = compact menu text; "json" = structured {title, items[]}.
cursor	string	optional	Pagination cursor for the "registry" section, taken from a previous "More servers" entry.

Raw schema

{
  "type": "object",
  "properties": {
    "section": {
      "description": "Which directory node to fetch. Default \"root\". Top level: root, seneschal, flashbank, winbit32, secresea, zecbus, registry, about, agents. Drill a project with \"<site>/about\", \"<site>/agents\" or \"<site>/actions\" (e.g. \"winbit32/actions\"). Seneschal also exposes per-service sections: \"seneschal/private-watch\", \"seneschal/checkout\", \"seneschal/oracle\", \"seneschal/shovels\", \"seneschal/builder\", \"seneschal/data\", \"seneschal/paymaster\", \"seneschal/board\", \"seneschal/ironwood\", \"seneschal/mcp\".",
      "type": "string"
    },
    "format": {
      "description": "\"gopher\" (default) = compact menu text; \"json\" = structured {title, items[]}.",
      "type": "string",
      "enum": [
        "gopher",
        "json"
      ]
    },
    "cursor": {
      "description": "Pagination cursor for the \"registry\" section, taken from a previous \"More servers\" entry.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

README.md13 KBView on GitHub

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. Top up in USDC over x402 or pay in Monero/Zcash directly (POST /v1/private/topup-crypto — free quote, no x402, no key; we detect the coin payment with the same view-key scanner the product sells). 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.

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

bash

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):

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_topup_crypto`	Free quote to top up a watch by paying in Monero/Zcash; poll status until settled (no x402, no key)
`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

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
# in another shell:
curl http://127.0.0.1:8810/v1/health

Docker

A Dockerfile is provided for self-hosting the MCP server:

bash

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

bash

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

code

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):

code

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

Install

Tools (31)

seneschal_healthseneschal_list_at_risk_borrowersseneschal_list_borrowersseneschal_recent_liquidationsseneschal_get_borrowerseneschal_get_borrower_historyseneschal_builder_leaderboardseneschal_stats_overview

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://mcp.seneschal.space/

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "seneschal-data": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.seneschal.space/"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

Seneschal Data (MCP)

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

seneschal_health

seneschal_list_at_risk_borrowers

seneschal_list_borrowers

seneschal_recent_liquidations

seneschal_get_borrower

seneschal_get_borrower_history

seneschal_builder_leaderboard

seneschal_stats_overview

seneschal_paywall_info

seneschal_premium_opportunities

seneschal_premium_builder_stats

seneschal_counter_mev

seneschal_puzzle_risk

seneschal_private_relay

seneschal_q

seneschal_private_watch_info

seneschal_private_watch_create

seneschal_private_watch_topup

seneschal_private_watch_create_crypto

seneschal_private_watch_topup_crypto

seneschal_checkout_invoice_create

seneschal_checkout_invoice_status

seneschal_private_watch_historical

seneschal_private_watch_derive_viewkey

seneschal_board_list

seneschal_board_read

seneschal_board_post

seneschal_board_reply

seneschal_board_boost

seneschal_flashloan_providers

seneschal_agent_directory

Seneschal Data API

Live endpoints

Quick start

REST

MCP — Claude Desktop / Cursor / Continue

REST endpoints

Why this exists

Local dev

Docker

Tests

Architecture

Premium tier (x402 paywall)

Configure

Support

License

Operator contact

Install

Remote endpoint

Related servers