Insight — Oracle Transparency & Risk Infrastructure

Insight is an oracle transparency and risk infrastructure platform for DeFi. It tracks prices across 10 oracle providers and 40+ blockchain networks — and turns that cross-oracle data into a decision-grade safety check that AI agents run before touching on-chain money, plus an always-on cross-oracle trust signal (Oracle Watch) that keeps running strategies safe between trades.

See through every oracle. Trust with clarity.

Insight is not a real-time oracle tracker. Price snapshots and feed health are collected every 15 minutes; reputation scores are recalculated hourly. All data is aggregated into daily reports. The API quotas are sized to this cadence.

Table of Contents

• The Flagship: Pre-Trade Oracle Safety Check
• Agent Guard SDK
• Independent Receipt Verification
• Protocol Release Isolation
• Oracle Watch: Always-On Cross-Oracle Monitoring
• Key Features
• Supported Oracles
• Supported Protocols
• Technology Stack
• Getting Started
• Project Structure
• API Access
• AI Agent Integration (MCP Server)
• Data Pipeline

The Flagship: Pre-Trade Oracle Safety Check

The "AI agent immune system." Before an agent (or human) executes any on-chain swap / borrow / lend / liquidate / repay, it calls one checkpoint that aggregates cross-oracle consensus prices, per-provider deviation, data freshness, stablecoin peg status, and reputation — and returns a single, machine-readable verdict:

PASS · CAUTION · DANGER · BLOCK + a recommended maximum position size

Agents must not execute when the verdict is DANGER or BLOCK. Every call is audit-logged, building the data flywheel for the ML risk model.

How it decides — deterministic rule engine

Signal	What it catches
Max provider deviation	One oracle diverging from consensus
Cross-provider spread	Oracles disagreeing with each other
Provider agreement	Consensus quality breaking down
Cadence-relative staleness	A feed falling behind its own observed rhythm (soft CAUTION) — plus a 7-day absolute hard-block backstop for genuinely dead feeds
Stablecoin depeg	Peg breakages contaminating lending markets
Protocol buffer consumption (lending)	How much of a protocol's max-LTV liquidation buffer the current oracle dispersion already eats

Lending freeze — the "decisive & actionable" layer. When cross-oracle dispersion consumes ≥95% of a protocol's max-LTV liquidation buffer and the erosion is sustained (24h z-score elevated or 3h deviation velocity still rising), new borrowing is frozen (BLOCK). One-tick volatility spikes are not frozen. Instead of only flagging risk, the check returns concrete actions: freeze_borrow, wait_convergence, add_collateral, reduce_position. Recommended borrow size shrinks in step with buffer consumption (floor 10%). Swap remains unaffected — a swap opens no liquidatable position.

ML augmentation (experimental — never drives the verdict)

• A multi-horizon ML model (1h + 6h) produces a manipulation risk score [0,1] that feeds the displayed risk level and audit log. The verdict itself is produced by the deterministic rule engine only.
• Unsupervised anomaly detection (z-score + EWMA residual vs 24h baseline) catches novel manipulation the supervised model has never seen.
• If no verified model is active, the score gracefully falls back to a hand-tuned rule-based formula — the check never depends on ML availability.

Verifiable attestations

Every check is signed, and every receipt can be verified by anyone, without trusting Insight. The public verify endpoint checks the signature against the published attester key, routes by the attestation's own schemaVersion, and at schema v3 both safety gates are recomputable from the bytes alone because both policy constants are inside the signed struct.

Every check can be signed as an EIP-712 offchain attestation — a portable, gasless, tamper-evident proof that "Insight verified oracle state for this trade at time T". Agents relay it in tx memo / calldata / logs so users and protocols can recognize the agent ran the oracle immune-system check.

• v1 — 11-field attestation (default, backward compatible).
• v2 — 26-field attestation: CAIP-19 asset-pair binding, request hash, provider-observations hash, reason-codes hash, plus a quorum gate (≥3 independent providers) and an independence gate (≥2 distinct non-derived operator groups) that escalate to BLOCK. Unresolvable assets are signed with an explicit unresolved: marker rather than silently dropped.
• v3 — 27-field attestation: identical evidence to v2 plus the independence threshold itself (requiredSourceGroupCount). v2 signs sourceGroupCount without the number it is compared against, so a third party cannot tell whether the gate passed without reading this codebase. v3 puts both operands inside the signature, which makes the gate checkable from the bytes alone. Same gates, same verdict policy as v2.

Anyone can verify a signature against the published attester address via POST /api/v1/safety/attestation/verify (public, no API key). The feature is disabled (non-breaking) when no signer key is configured. v1/v2/v3 coexist; the endpoint routes by the attestation's own schemaVersion and publishes all three type layouts from GET (latestSchemaVersion is 3).

Agent Guard SDK

The publishable TypeScript package in sdk/ turns the three agent-facing services into one explicit execution workflow:

two-sided Pre-Trade gate → transaction submission → VERIFIED Execution Receipt
                ↑
        Oracle Watch can halt the strategy between trades

oracle-insight-guard does not embed a copy of Insight's rules or signing keys. It calls the existing API with the integrator's API key, so risk decisions, EIP-712 attestations, audit logs, and C3/C4 credit metering stay server-side and authoritative. executeSwap() does not call the supplied transaction submitter when either pre-trade result is DANGER or BLOCK; when both signed v2/v3 proofs are available, it sends them with the transaction hash to issue a VERIFIED execution receipt.

For agents that also use PriorSeal, executeSwapWithPriorSeal() adds an exact-call authorization step before transaction broadcast and collects a companion PriorSeal receipt afterward. The signed PriorSeal intent also commits to both Insight pre-trade attestation UIDs, both request hashes and the slippage ceiling. Insight continues to attest quote/fill/slippage semantics; PriorSeal independently proves that the exact call and those external proof references were principal-authorized.

Integration surfaces and billing

These are distinct ways to integrate Insight, not separate wallets or feature tiers:

Surface	Best for	Credit behavior
REST API	Custom applications that need individual data, analysis, or risk endpoints	Each successful endpoint call draws its C1–C4 cost from the API key's wallet.
AI / MCP	Claude, Cursor, Windsurf, and other MCP-compatible agents	Each successful tool call draws the equivalent C1–C4 cost from the same wallet.
Guard SDK	Agents that should gate, execute, monitor, and retain proof as one workflow	No separate SDK fee. It calls the underlying endpoints: a successful two-sided executeSwap() uses two C3 pre-trade calls plus one C4 receipt call (20 credits at current prices), excluding optional Watch polling.

Oracle Watch polling is a C3 call per signal. Plans and prepaid top-ups only add credit capacity; every paying user can use every surface. See Pricing for the current wallet and plan details.

npm install oracle-insight-guard

See sdk/README.md for the package API, or visit /sdk and /docs/sdk for the product overview and integration guide.

Independent Receipt Verification

For integrations that should not depend on Insight being online, the repository also ships a standalone verifier package in verifier/. It can be published or copied into a separate consumer repository without importing the Next.js app.

Live in-browser verifier — the deployed site hosts a zero-trust demo at /verify. It fetches a public sample receipt and the published /.well-known/oracle-keys.json registry, then re-verifies the EIP-712 signature entirely in your browser with verify-insight-receipt. No server, no API key, no trust in Insight — the verdict is computed on the client and never sent back.

Published to npm: verify-insight-receipt v0.2.0.

# Published package (recommended)
npm install verify-insight-receipt

# Or from a checkout of this repository
npm install ./verifier

import { verifyReceipt } from 'verify-insight-receipt';

const result = await verifyReceipt(receipt, { keyRegistry });
if (result.code !== 'ok') {
  throw new Error(`Receipt failed: ${result.code}`);
}

verifyReceipt() performs EIP-712 verification locally with no API key, database, environment variable, or default network call. Pass the published /.well-known/oracle-keys.json document when the consumer also wants attester key-window status. Verification is not endorsement: a valid receipt proves that the signed bytes were issued by the listed signer and were not modified; it does not prove that the underlying trade or verdict was correct.

If a consumer explicitly wants to share anonymous verification outcomes, reportVerification() is a separate opt-in API. Insight does not use client-side verification calls as its primary usage metric. The reliable product metric is evidence utilization: the share of issued attestation UIDs that later appear as execution_receipts.pre_trade_uid. The read-only report script is verifier/scripts/evidence-utilization.mjs.

The package supports v1, v2, v3, and v2/v3 recheck receipts. Its schema constants are guarded against production drift by src/lib/attestations/__tests__/verifierParity.test.ts.

VRT1 (§8.6) — Insight's OracleSafetyCheck is listed as a vendor action type in the VRT1 specification, as a pointer to our machine-readable scale declaration: https://github.com/Ifasola34/vrt1-spec/blob/main/registry/vendor-action-types.json. The declaration pins the per-field integer scale and both policy constants (requiredParticipantCount, requiredSourceGroupCount); at schema v3 both constants are also inside the signed struct, so the gates are checkable from the bytes alone. Listing records that the type exists, where its declaration is, and what those bytes hashed to. It is not an endorsement of Insight's verdicts, and it does not describe Insight's default traffic: schema v1 (11 fields, no gates) remains the service default and v3 is opt-in.

Access

• MCP tool — pre_trade_safety_check (one of 37 tools).
• REST — GET /api/v1/safety/pre-trade?asset=ETH&chainId=1&action=swap&tradeAmountUsd=100000.
• Web — interactive demo at /ai; the same lending check is embedded live on every position at /safety-check.

Protocol Release Isolation

ExecutionReceipt v5 signs a content-addressed profileId alongside the receipt. That immutable profile fixes the commitment, sentinel, scale and verdict rules; schemaVersion continues to identify only the EIP-712 field layout. The public registry also exposes registryRevision, effectiveFrom, a small current pointer and immutable release/profile URLs. All partner code can coexist on main: independently activated, content-addressed partner policies ensure that one collaboration cannot silently advance another collaboration's path. See the oracle registry release policy. The end-to-end workflow is documented in main-only partner isolation.

Oracle Watch: Always-On Cross-Oracle Monitoring

The always-on companion to Pre-Trade. Pre-trade answers "can I trade this price right now?" for a single moment; Oracle Watch answers "can my strategy keep depending on this feed?" with a consolidated, live cross-oracle trust signal any agent can poll and gate on — no trade required.

NORMAL · CAUTION · DANGER + a proceed / proceed_with_caution / halt recommendation

Agents running long-lived strategies (yield bots, keepers, portfolio managers) should poll the signal on a schedule and pause when the verdict turns DANGER. It is the counterpart to the one-off pre-trade checkpoint for the between-trades window.

How it decides

Oracle Watch condenses the same underlying consensus data into one verdict using the same severity thresholds as Pre-Trade (max deviation: caution 1.0% / danger 3.0%; agreement: caution 0.95 / danger 0.85), so both surfaces speak one consistent risk language:

Signal	NORMAL	CAUTION	DANGER
Max cross-oracle deviation	< 1.0%	1.0% – 3.0%	≥ 3.0%
Cross-provider agreement	≥ 0.95	0.85 – 0.95	< 0.85
Outliers / staleness	none	any outlier or stale feed	— (escalated by deviation/agreement)
Independent operator groups	≥ 2	—	< 2 (insufficient_oracle_independence)
No cross-oracle coverage	—	—	DANGER / halt (no_cross_oracle_coverage) — degrades, never errors

Independence is not the same as headcount. Three responses can come from one operator — three white-labelled wrappers of Chainlink, or two real sources plus a TWAP — and still satisfy a quorum of 3 while describing a single point of failure. The independence gate counts distinct non-derived operator groups (sourceGroupCount); TWAP feeds the consensus and the quorum count but never the independence count. It is the same gate Pre-Trade has enforced since v2.1.

Reason codes

A single reason string can only name the dominant cause, so every response also carries reasonCodes — the full set of conditions that fired. That is what makes a "pause when DANGER" policy explainable after the fact:

NO_COVERAGE · INSUFFICIENT_QUORUM · INSUFFICIENT_INDEPENDENCE · MAX_DEVIATION · LOW_AGREEMENT · OUTLIER_PRESENT · STALE_DATA · ML_FORWARD_RISK_HIGH

v2 receipts sign reasonCodesHash alongside them, so the diagnosis travels with the proof instead of living only in a log.

Access

• MCP tools — oracle_watch (live point signal) and oracle_watch_history (retrospective trend), two of 37. Pair them with pre_trade_safety_check for the decision moment.
• REST — GET /api/v1/oracle-watch?symbol=ETH&chain=ethereum and GET /api/v1/oracle-watch/history?symbol=ETH&chain=arbitrum&days=7. Every paying key gets the full 90-day window; long windows roll up hourly or daily in Postgres so responses remain complete and bounded.
• Web — interactive demo with MCP + REST calling methods at /ai#oracle-watch.

History coverage — what we promise

Oracle Watch is positioned as always-on, but "always-on" cannot mean "every pair has a retrospective curve". Collection costs one full cross-oracle evaluation per pair every 30 minutes, so we publish a narrow promise and keep it:

History is guaranteed for ETH / BTC / USDC / USDT on Ethereum, Arbitrum and Base. Every other pair still returns a live point signal from oracle_watch, but no curve.

An out-of-universe pair returns an empty series plus meta.historyGuaranteed: false — never a silent empty array, which a dependent agent would otherwise read as "no incidents".

Per-issuance audit log

Every judgment actually returned to a caller — receipt or not — is recorded in oracle_watch_checks (uid, symbol, chain, verdict, recommendation, reason codes, both gate counts with their thresholds, validity window, issuing surface). That is what lets us answer "which receipt did this agent gate on" after the fact. The write is fire-and-forget: it can never fail, slow, or change a signal.

Signed Watch attestations (EIP-712)

Every Watch signal can carry a signed OracleWatchCheck receipt — the always-on counterpart to the pre-trade attestation. It uses the same attester key and the same evidence-binding primitives, so one verifier handles both surfaces. Pass ?attest=false to skip it.

New receipts are v2 — 26 signed fields: verdict, recommendation, trust score/level, consensus price, deviation, agreement, participant count, outlier/ stale counts, ML risk, reputation, providerObservationsHash, requestHash, evaluatedAt, validUntil, plus:

• The quorum threshold — requiredParticipantCount next to the participantCount it gates.
• The independence gate — sourceGroupCount, requiredSourceGroupCount and independenceSatisfied. Without them a holder cannot tell whether "quorum satisfied" means three independent operators or three wrappers of one.
• reasonCodesHash — binds the composable reason-code set above.

Every threshold is signed next to the value it judges, so a receipt is self-contained: a holder can re-derive the verdict without Insight's source code.

• v1 stays verifiable — its 22-field layout is frozen rather than rewritten, so receipts already in counterparties' hands keep validating. Both layouts are published in .well-known/oracle-keys.json, which also carries Watch's own verify / sample pointers.
• Sample — GET /api/v1/oracle-watch/attestation/sample?symbol=ETH.
• Verify — POST /api/v1/oracle-watch/attestation/verify with { "attestation": <receipt> }. Public and unauthenticated; anyone holding a receipt can check it.

Signing is additive: if no attester key is configured the field is null and the signal itself is unchanged.

Key Features

For DeFi Users

• Safety Check — enter a lending position to get the exact oracle price deviation that would trigger liquidation, health factor gauge, safety buffer analysis, and per-asset bidirectional deviation — now with the pre-trade lending check (buffer-consumption bar + recommended actions) right on the position page.
• Stablecoin Depeg Tracker — 15-minute tracking of USDC, USDT, DAI and others across providers and chains, with depeg duration, affected lending protocols, and impact explanation.
• Wrapped Asset Peg Tracker — WBTC, wstETH, cbETH and other wrapped / liquid-staking tokens vs their underlying, including on-chain LST exchange rates and protocol impact mapping.
• Price Query — query any provider with on-chain data, confidence intervals, and freshness at a glance.

For Researchers & Analysts

• Price Insight — unified cross-oracle / cross-chain analysis with 4 consensus algorithms, risk analysis, divergence signal detection, and feed health tracking.
• Oracle Reputation System — persistent 7-day rolling scores (accuracy, uptime, reliability, latency, freshness) with provider profiles and trend charts.
• Daily Reports — aggregated oracle market snapshots with consensus prices, provider rankings, depeg / peg summaries, and risk highlights.

For AI Agents

• Pre-Trade Oracle Safety Check — the flagship checkpoint described above.
• 37-tool MCP server — prices, consensus, risk, reputation, stablecoin pegs, protocol parameters, position safety, pre-trade checks — callable by Claude, Cursor, Windsurf, and any MCP-compatible client.
• Verifiable attestations — signed EIP-712 proof agents can relay to users and protocols, with a standalone local verifier for consumers that need independent verification.

Shared

• Data Export — CSV, JSON, Excel, PDF, PNG.
• Consensus Price — median, trimmed mean, weighted median, IQR-filtered.
• Data Transparency — source indicators and update-time tracking.
• Accessibility — keyboard navigation, colorblind mode, screen reader support.

Supported Oracles

Provider	Type	Supported Chains
Chainlink	On-chain	Ethereum, Arbitrum, Optimism, Polygon, Avalanche, BNB Chain, Base
API3	On-chain dAPIs	Ethereum, Arbitrum, Polygon, Avalanche, BNB Chain, Base, Optimism
RedStone	API / On-chain	Ethereum, Arbitrum, Optimism, Polygon, Avalanche, Base, BNB Chain, Fantom, Linea, Mantle, Scroll, zkSync
DIA	API / On-chain	Ethereum, Arbitrum, Polygon, Avalanche, BNB Chain, Base
WINkLink	On-chain	TRON
Supra	API / On-chain	Ethereum, Arbitrum, Optimism, Polygon, Base, Solana, BNB Chain, Avalanche, zkSync, Scroll, Mantle, Linea, Supra Chain, Aptos, Sui
TWAP	On-chain (DEX)	Ethereum, Arbitrum, Optimism, Polygon, Base, BNB Chain (Uniswap V3 TWAP)
Reflector	On-chain	Stellar (Soroban)
Flare	On-chain	Flare (FTSO)
Switchboard	API (Crossbar)	Ethereum, Arbitrum, Optimism, Polygon, Solana, Avalanche, BNB Chain, Base, Scroll, zkSync, Aptos, Sui, Mantle, Linea, Flare, Supra Chain

Supported Protocols (Safety Check)

Protocol	Chain	TVL	Supported Assets
Aave V3	Ethereum	$12B	ETH, WBTC, tBTC, USDC, USDT, LINK
Compound V3	Ethereum	$2.5B	ETH, WBTC, USDC, USDT
Morpho Blue	Ethereum	$8B	ETH, WBTC, tBTC, wstETH, USDC, USDT, DAI
Aave V3	Arbitrum	$3B	ETH, WBTC, cbBTC, tBTC, USDC, USDT, ARB
Compound V3	Arbitrum	$800M	ETH, WBTC, USDC, USDT
Aave V3	Optimism	$1.8B	ETH, WBTC, USDC, USDT, DAI, wstETH, OP
Aave V3	Polygon	$1.2B	ETH, WBTC, USDC, USDT, DAI, wstETH, MATIC
Aave V3	Base	$2B	ETH, WBTC, cbBTC, tBTC, USDC, USDT, cbETH
Compound V3	Base	$1B	ETH, WBTC, USDC, USDT
Morpho Blue	Base	$5B	ETH, WBTC, cbBTC, cbETH, wstETH, USDC, USDT, DAI
Venus Protocol	BNB Chain	$1.7B	BNB, BTCB, ETH, USDT, USDC
BENQI	Avalanche	$500M	AVAX, WETH, BTC.b, WBTC, USDC, USDt, DAI, LINK

The safety check calculates critical deviation percentage, liquidation trigger price, health factor (circular gauge), safety buffer level (safe / moderate / risky / dangerous), per-asset bidirectional deviation analysis, collateral ratio curve, and oracle reliability warnings. Per-asset deviation bounds are derived from each protocol's own liquidation-threshold parameters — the same values power the pre-trade lending freeze.

Technology Stack

• Framework: Next.js 16 (App Router) + React 19 + TypeScript 5
• Styling: Tailwind CSS 4
• State Management: React Query 5, Zustand 5
• Charts: Recharts 3
• Database & Auth: Supabase (PostgreSQL + RLS + pg_cron)
• Blockchain: viem 2, @api3/contracts, supra-oracle-sdk, @stellar/stellar-sdk
• AI Agent Layer: @modelcontextprotocol/sdk 1.x (stdio + HTTP transports)
• Billing: NOWPayments — USDC-denominated subscriptions, prepaid credit packs, and per-call credit-wallet metering
• Validation: zod 4
• Error Tracking: Sentry
• Observability: Vercel Analytics, Vercel Speed Insights

Getting Started

npm install
npm run dev

Set up environment variables first (see src/lib/config/serverEnv.ts for the full reference). Required in production: Supabase URL + anon key + service-role key, CSRF_SECRET, JWT_SECRET. In non-production, missing secrets fall back to safe dev defaults so the app runs without a full env setup. Optional: Sentry DSN, NOWPayments billing keys (checkout is unavailable when unset), per-chain ALCHEMY_<CHAIN>_RPC endpoints, TRON / WINkLink access, and ATTESTATION_SIGNER_PRIVATE_KEY to enable signed pre-trade attestations.

Project Structure

src/
├── app/          # Next.js App Router — pages + API routes (/api/v1, /api/mcp)
├── components/   # React UI components (incl. shared safety/ LendingSafetyPanel)
├── hooks/        # React hooks
├── lib/          # Core logic — analytics, api, attestations, billing, ml, oracles,
│                 #   protocols, risk, stablecoins, supabase, ...
├── mcp/          # MCP server implementation (stdio + http transports, 37 tools)
├── providers/    # React context providers
├── stores/       # Zustand state stores
├── types/        # TypeScript type definitions
└── __mocks__/    # Jest mocks

Database migrations and Supabase config live under supabase/. The ML training pipeline lives under ml/ (ml/train.py, models output to ml/models/). Standalone TypeScript runners for scheduled jobs live under scripts/.

API Access

Insight exposes a versioned REST API (/api/v1/) authenticated with X-API-Key (created from the Settings page; plaintext shown once, stored as SHA-256 hash). The full interactive reference (OpenAPI 3.1, live "Try It Out", code snippets) is at /docs/api.

Access & Billing

Access is gated by a credit wallet, not plan tiers. There is no recurring free tier and no feature gating — every paying user gets every endpoint and MCP tool. A call is allowed iff the key's credit balance covers its metering class cost.

Component	Description
Trial	New users get 100 one-time trial credits after email verification (POST /api/billing/signup-grant). It never refreshes and never re-issues.
Subscriptions	Developer ($49/mo → 60,000 credits/mo, 60 req/min), Team ($199/mo → 300,000 credits/mo, 300 req/min), and Scale ($499/mo → 1,000,000 credits/mo, 1,200 req/min). Yearly = 10× monthly. Enterprise is contact-sales unlimited. Features are identical across plans.
Credit packs	Prepaid top-ups, no subscription required: Starter (25,000 cr / $39), Builder (100,000 cr / $129), Agent (500,000 cr / $499).
Per-call metering	Every call is charged from the wallet by metering class C1–C4 (see src/lib/billing/metering.ts).

All paying users get the full 90-day history/reputation window. Payments are crypto-only via NOWPayments (USDC-denominated); subscriptions run one billing cycle with no auto-renewal. The public website (prices, protocols, rankings) stays free to browse — only API-key calls are metered.

Plans

Plan	Rate limit	Included credits/mo	Per-call metering	Price
Developer	60 req/min	60,000	C1–C4 (0.5 / 2 / 5 / 10)	$49/mo
Team	300 req/min	300,000	C1–C4 (0.5 / 2 / 5 / 10)	$199/mo
Scale	1,200 req/min	1,000,000	C1–C4 (0.5 / 2 / 5 / 10)	$499/mo
Enterprise	Unlimited	Unlimited	—	Contact sales

Credits are stored in credit_wallet / credit_ledger (migration 0039). The monthly allowance is credited on subscription activation and at each cycle (billing cron). Additional credits can be bought as prepaid packs from Settings → Billing or the pricing page.

See src/lib/billing/plans.ts for the single source of truth.

Key endpoint groups (all under /api/v1/): prices*, reputation*, feeds*, deviation, correlation, latency, anomalies, signals, safety/* (position, liquidation, pre-trade, attestation/verify), oracle-watch, stablecoins/depeg, wrapped-assets/peg, protocols*, cross-chain/spreads, incidents, coverage, reports/daily/[date], hourly-snapshots, price-snapshots, symbols, oracles/health, metrics, health.

AI Agent Integration (MCP Server)

Insight exposes its oracle and risk capabilities as an MCP (Model Context Protocol) server — 37 tools covering prices, consensus, risk summaries, liquidation stress tests, stablecoin pegs, reputation, feed health, and protocol parameters, with the flagship pre_trade_safety_check and the always-on oracle_watch signal on top. The MCP layer is a thin adapter over the same /api/v1/* services — no duplicated business logic.

Quick start:

npm run mcp:stdio   # stdio transport for local agents
npm run mcp:http    # HTTP transport on http://127.0.0.1:3001/mcp

When the Next.js app is running, the endpoint is also available at /api/mcp with the same authentication, rate limiting, and quota enforcement as the REST API.

Web hub — visit /ai in the app to run the interactive pre-trade safety demo and the Oracle Watch demo, copy one-click MCP configs for Cursor / Windsurf / Claude Desktop, manage API keys, and test all 37 tools in the browser-based MCP Playground.

Data Pipeline

Supabase pg_cron is the reliable clock for the six product-critical jobs. It uses pg_net plus a repository-scoped token in Vault to dispatch dependency-free GitHub Actions runners; GitHub performs the network/compute-heavy work and writes results directly to Supabase, so Vercel spends no background Active CPU. Guarded native GitHub schedules remain as stale-ledger fallbacks. Supporting jobs — feed discovery, feed reactivation, protocol TVL / risk-params sync, ML retraining, and billing lifecycle — remain low-frequency GitHub schedules. The authenticated /api/cron/* routes are manual recovery paths. Fine-grained, hourly, and market reference snapshots are retained for 120 days, preserving the advertised 90-day history window and the eight-week ML lookback.

Deployment and rollback instructions live in docs/operations/cron-dispatcher.md. The service objectives, monitoring, backups, release checks, load testing, incident response, and application rollback process are in docs/operations/production-readiness.md.