Seneschal Data API

Pay-per-call data over HTTP and the Model Context Protocol. The headline product is Private Watch — view-key payment webhooks for Monero & Zcash (below). Also free and public: DeFi-liquidation telemetry (Aave, Morpho, Spark, Compound) and Ethereum block-builder market share from our own shadow recorder. No signup, no API key.

# 1. Create a watch (one x402 payment of $0.10 seeds $0.10 credit)
curl -s https://api.seneschal.space/v1/private/watch \
  -X POST -H 'content-type: application/json' \
  -H 'x-payment: <eip3009 payload, $0.10 USDC on Base>' \
  -d '{
    "chain": "monero",
    "address": "44AFFq…",
    "viewKey": "0123…",
    "webhookUrl": "https://shop.example.com/webhook/xmr"
  }'

# 2. Top up later (a $1 top-up buys ~50 idle days):
curl -X POST https://api.seneschal.space/v1/private/topup-1 \
  -H 'x-payment: <eip3009 payload, $1.00 USDC on Base>' \
  -H 'content-type: application/json' \
  -d '{"watchId":"...","watchToken":"..."}'

# 2b. ...or pay in Monero/Zcash instead (FREE quote, no x402, no key):
curl -X POST https://api.seneschal.space/v1/private/topup-crypto \
  -H 'content-type: application/json' \
  -d '{"watchId":"...","watchToken":"...","chain":"monero","amountUsdCents":500}'
# -> { quoteId, payTo, amount:{display,coin}, memo, confirmations, expiresAt }
# Send the exact amount (Monero) or include the memo (Zcash), then poll:
curl -s -H 'x-watch-token: ...' \
  https://api.seneschal.space/v1/private/topup-crypto/<quoteId>

# 3. One-off historical lookup (returns notes; view key never persists):
curl -X POST https://api.seneschal.space/v1/private/historical \
  -H 'x-payment: <eip3009 payload, $0.50 USDC on Base>' \
  -H 'content-type: application/json' \
  -d '{"chain":"zcash","address":"u1...","viewKey":"uview1...","includeNotes":true}'

# 4. FREE: derive a Zcash UFVK from a BIP-39 mnemonic (loud warning, rate-limited):
curl -X POST https://api.seneschal.space/v1/private/derive-viewkey \
  -H 'content-type: application/json' \
  -d '{"chain":"zcash","phrase":"abandon abandon ... 24 words"}'

Four endpoints, one prepaid balance

Why this exists

Seneschal runs an Ethereum block builder and a vertically-integrated liquidation searcher. As a side effect of doing our own work we continuously track ~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, same backend:

• REST API at https://api.seneschal.space — for dashboards, monitoring tools, anything that speaks HTTP.
• MCP server at https://mcp.seneschal.space — for AI agents (Claude, Cursor, Continue, etc.) using the Model Context Protocol.

Quick start

REST

curl https://api.seneschal.space/v1/liquidations/atrisk?max_hf=1.05

MCP (Claude Desktop / Cursor)

Add this to your MCP client config (e.g. ~/.cursor/mcp.json):

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

The full Seneschal tool surface becomes available to your agent: 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_flashloan_providers, seneschal_q (Penny Oracle dispatcher), plus the Private Watch suite: seneschal_private_watch_info, seneschal_private_watch_create, seneschal_private_watch_topup, seneschal_private_watch_topup_crypto, seneschal_private_watch_historical, seneschal_private_watch_derive_viewkey, seneschal_private_watch_status, seneschal_private_watch_cancel and seneschal_private_watch_test.

REST endpoints

Worked example

Find the most at-risk Aave borrower right now and pull their HF history:

$ curl -s 'https://api.seneschal.space/v1/liquidations/atrisk?protocol=aave&limit=1' | jq '.results[0]'
{
  "borrower": "0x...",
  "protocol": "aave",
  "health_factor": 1.011,
  "collateral_usd": 8412055,
  "debt_usd": 8240015,
  "liquidatable": false,
  ...
}

$ curl -s "https://api.seneschal.space/v1/borrowers/0x.../history?protocol=aave&granularity=hour"
{ "address": "0x...", "points": [ ... 168 hourly observations ... ] }

MCP tool reference

Identical surface to REST: every endpoint has a matching tool with the same parameters and same response shape (just wrapped as MCP tool content).

Premium tier (x402) — LIVE

Pay-per-call endpoints on Base mainnet, settled in USDC via the x402 protocol. Three price tiers — bulk feeds, builder analytics, and atomic single-fact queries:

Penny Oracle — /v1/q/* atomic-fact endpoints

Seventeen micro-priced endpoints, all GET, all $0.001 per call (1/100th of a cent). Each returns a flat object so an agent can branch directly on the answer without nested-field gymnastics. The free catalogue at GET /v1/q enumerates every question and its input parameters.

The privacy-chain set is the "joining the dots" of this product line: Monero and Zcash are the two chains where running a node yourself is genuinely awkward (~108 GB and ~270 GB respectively, plus syncing hours), public RPC endpoints rate-limit aggressively, and there is no Etherscan-style hosted explorer to fall back on. We run synced nodes already; the x402 sub-cent paywall finally makes selling individual reads worth the trouble. All responses are cached server-side for 10 s so an agent in a tight loop costs the daemon nothing extra.

Hand-rolled flow:

curl -s 'https://api.seneschal.space/v1/q/liquidatable?addr=0x...&protocol=aave'
# Pays $0.001 USDC on Base via x402-fetch and returns
# {"found":true,"protocol":"aave","liquidatable":false,"hf":1.03,"debt_usd":24500,"last_seen_ms":1716314400000}

MCP agents can use the single dispatcher tool seneschal_q with {question, params} rather than wiring up separate tool calls per question. The MCP path is currently free; the HTTP path is paywalled.

Payment uses the x402 protocol (spec v2). Unsigned requests get HTTP 402 with a base64-encoded Payment-Required header carrying machine-readable PaymentRequirements; the client signs an EIP-3009 transferWithAuthorization off-chain and retries with a X-PAYMENT header. We delegate verify + settle to Coinbase’s CDP facilitator, which broadcasts the EIP-3009 transfer on Base. No API keys for the payer, no subscriptions, no gas for the payer — the facilitator pays the gas. (Settling through Coinbase also lists the service in the Coinbase x402 Bazaar.)

Free metadata endpoint for budgeting before any paid call:

curl https://api.seneschal.space/v1/paywall
# → {"protocol":"x402","network":"eip155:8453",
#    "facilitator":"https://api.cdp.coinbase.com/platform/v2/x402",
#    "facilitator_mode":"cdp",
#    "payTo":"0x46Ba634261566CF242c853d1f49511f9268ba674",
#    "scheme":"exact (EIP-3009 transferWithAuthorization)",
#    "routes":[{"endpoint":"GET /v1/premium/opportunities","price":"$0.05",...},
#              {"endpoint":"GET /v1/premium/builder-stats","price":"$0.10",...},
#              {"endpoint":"GET /v1/q/liquidatable","price":"$0.001",...}, … ]}

Agents using x402-axios, x402-fetch, @x402/express, @x402/fastify or the official client libraries pay automatically on 402. Hand-rolled flow, in three lines of TypeScript:

import { wrapFetchWithPayment } from 'x402-fetch';
import { createWalletClient, http } from 'viem';
import { base } from 'viem/chains';

const wallet = createWalletClient({ account, transport: http(), chain: base });
const fetchPaid = wrapFetchWithPayment(fetch, wallet);
const r = await fetchPaid('https://api.seneschal.space/v1/premium/opportunities');
console.log(await r.json());

The account is any viem-compatible signer holding a small USDC balance on Base — a fresh EOA + 1 USDC will fund ~20 paid calls.

Private Watch — /v1/private/* (XMR/ZEC payment monitoring)

This is the headline product. The agent (or merchant, or wallet) hands us a public address, a view key, and a webhook URL. We scan every new block against the view key on the local NFPT wallet-scanner (driven by monerod for Monero and zebra + the Zcash orchard-scanner binary for Zcash) and POST a signed event to the webhook the moment the balance changes.

Pricing — prepaid credit meter. One payment of $0.10 opens a watch and seeds $0.10 of credit. The watch then drains at $0.02 per UTC day idle (proportional, billed each poll tick) plus $0.005 per webhook delivered. When credit hits a low threshold ($0.05) we POST a one-shot low_credit warning so your receiver can top up before going silent. Top up any time with one of three paywalled paths ($0.10 / $1 / $5). Credit balance is in every webhook body so well-behaved receivers can ignore the dedicated event.

Webhook contract. Every delivery is a POST with content-type: application/json and three Seneschal headers:

X-Seneschal-Watch-Id: <uuid>
X-Seneschal-Event: balance_change | scan_complete | status_change | low_credit | synthetic_test
X-Seneschal-Signature: sha256=<HMAC-SHA256(webhookSecret, exact request body)>

The body is plain JSON. Every delivery (including low_credit warnings) carries a credit block so receivers always know where they stand:

{
  "watchId": "fb1a29bd-…",
  "chain": "monero",
  "address": "46FzbF…",
  "event": "balance_change",
  "timestamp": "2026-05-21T08:06:54.626Z",
  "nonce": "mpf7j7he-30s7yx",
  "previous": { "balanceAtomic": "0", "scannedHeight": 3349800, … },
  "current":  { "balanceAtomic": "1234567890", "scannedHeight": 3349881, … },
  "delta": {
    "balance_atomic": "1234567890",
    "before_atomic": "0",
    "after_atomic":  "1234567890"
  },
  "credit": {
    "remaining_atomic": "94750",
    "remaining_usd": "0.0948",
    "days_remaining": 4.7,
    "low_credit": false,
    "rate_per_day_atomic": "20000",
    "rate_per_call_atomic": "5000",
    "low_credit_threshold_atomic": "50000"
  }
}

The low_credit event is fired once when remaining_atomic first drops below the threshold ($0.05 of credit, ~2.5 idle days). Top up >= the threshold to re-arm the warning. After credit reaches zero the watch stops being polled entirely; no further deliveries happen until the next top-up.

Receivers verify the signature with the per-watch webhookSecret returned at creation. Constant-time HMAC comparison defeats forgery; the secret is generated server-side and never reused across watches. Bodies are capped at 64 KB.

Security model. View keys decrypt incoming transactions but cannot spend — you can hand us one without giving up custody. We nonetheless encrypt the key at rest with AES-256-GCM under an operator-held master key (PRIVATE_WATCH_ENCRYPTION_KEY); plaintext only exists in memory while the poller is decrypting it for the next scan call. Webhook URLs are vetted at creation:

• HTTPS-only in production (http:// rejected unless the operator opts in for local dev).
• SSRF guard rejects RFC1918, loopback, link-local, RFC6598 CGNAT, IPv6 unique-local / link-local / loopback, and cloud-metadata IPs.
• DNS-resolve-and-recheck — we resolve the hostname and re-test every returned A/AAAA against the same blocklist, so evil.example.com can’t alias to 127.0.0.1.
• No userinfo — URLs containing https://user:pass@… are rejected so we never echo credentials onto the wire.

Tunables. Polling cadence is 3 min by default (stays inside NFPT's 5 min scanner idle window). Webhook receivers get an 8 s HTTP timeout and we cap drained response body at 4 KB to defeat slow-loris megabyte responses. On webhook failure we retry on the next tick; 50 consecutive failures retire the watch with a dead flag. After expiry the row is hard-deleted on the next tick.

Zcash birthday height. If omitted we default to NU6 (3,042,000) so the scanner never trips into a multi-hour autoDetect backwards-walk. Wallets created before April 2024 should pass an explicit birthdayHeight matching wallet age.

MCP. Agents already inside a paid MCP session can use seneschal_private_watch_create, seneschal_private_watch_topup, seneschal_private_watch_topup_crypto, seneschal_private_watch_historical, seneschal_private_watch_derive_viewkey, seneschal_private_watch_status, seneschal_private_watch_cancel and seneschal_private_watch_info for end-to-end flow without direct HTTP.

Historical lookups & view-key derivation

Two new on-demand services let agents recover state without committing to a long-running watch:

• POST /v1/private/historical — $0.50 one-off. For Zcash we run an Orchard scan with autoDetect: true (birthday height auto-discovered) and witness: true so the response includes per-note anchor + Merkle-path data alongside totals. For Monero we use the full monero-lws scan and aggregate incoming + outgoing notes into received_atomic / spent_atomic / spendable_atomic. View keys stream through the upstream NFPT API in-memory only — never written to our SQLite, never logged.
• POST /v1/private/derive-viewkey — FREE. Zcash only. Forwards a 12- or 24-word BIP-39 mnemonic to NFPT’s orchard-scanner derive-ufvk command and returns the matching read-only UFVK plus optional Sapling + transparent FVKs. Loud security warning in the response: the seed phrase transits our server (we never log or persist it, but a TLS-MitM on the network path would see the bytes). Whenever feasible, run orchard-scanner locally and supply the resulting UFVK directly. Rate-limited to 6 requests per IP per minute.

Data freshness & coverage

• Aave V3 mainnet — live, latest health factor refreshed every block for borrowers with non-trivial debt.
• Morpho Blue mainnet — live, latest snapshot ~10 minutes old.
• Spark — snapshot refreshed periodically; check /v1/health's spark_borrowers_mtime_ms.
• Compound — merged into the Aave snapshot table by the upstream writer; query with protocol=aave.
• Shadow blocks — one row per slot since May 2026 (~55k rows at launch, growing). Built from our own observation of relay-served payloads, not relay self-reporting.

Limits, terms, fair use

• 120 req/min per IP, soft. Heavy users should ask for an allow-list bump on Telegram (@OrknetP).
• No SLA. This is a free best-effort service. Expect occasional restarts.
• Use of the data must not violate any privacy or legal restrictions in your jurisdiction. We surface only on-chain data and our own observations.
• Crediting Seneschal (https://seneschal.space) in derived work is appreciated but not required.

About

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. By using the service you agree to the Terms and Privacy policy.