# Majestify - DeFi Risk Intelligence

> Majestify Experiment powers the DeFi Risk Intelligence dashboard at https://majestify.ai.
> It provides cryptocurrency asset and vault risk analytics powered by quantitative finance, with the mission to maximize the utility of intelligent capital.
> Data sourced from CoinGecko, FRED (US Treasury risk-free rate), Morpho metadata/share-price history, and server-side RPC.
> This is an experimental research tool and does not constitute financial advice.

## Product Context

- Website: https://majestify.ai
- Product surfaces: Risk Analysis Dashboard, Vault Risk Dashboard, lean Risk Pulse/Risk Passport decision engine, Pricing, Methodology and Risk Framework, and API Docs
- Repository name: majestify-experiment
- Positioning: risk-first crypto research, not price prediction or trading advice
- Top-level dashboard modes: Assets and Vaults
- Treasury APIs remain staged for future UI reactivation; the live dashboard is focused on getting Vaults to production quality.

## API Documentation

- [OpenAPI Specification (machine-readable)](https://majestify.ai/_/backend/openapi.json)
- [Interactive API Docs](https://majestify.ai/_/backend/docs)
- [AI Plugin Manifest](https://majestify.ai/_/backend/.well-known/ai-plugin.json)
- [MCP Manifest](https://majestify.ai/.well-known/mcp.json)
- [Support](https://majestify.ai/support)
- [Privacy Policy](https://majestify.ai/privacy-policy)
- [Terms](https://majestify.ai/terms)

## Available Endpoints

- GET /api/coins - List all supported cryptocurrencies (top 100 by market cap)
- GET /api/price/{coin_id} - Current price, 24h change, market cap, volume
- GET /api/prices?ids=bitcoin,ethereum - Batched current prices for up to 10 assets
- GET /api/historical/{coin_id}?days=365 - Historical prices from CoinGecko
- GET /api/metrics/{coin_id}?days=365 - Risk metrics: Sharpe, Sortino, VaR, CVaR, drawdown, Calmar, skewness, kurtosis; use days=1825 for 5-year context when supported
- GET /api/agent/capabilities - Agent-readable capabilities and MCP tool map
- GET /api/data-status - Provider health, validation summaries, latest pipeline runs, shared-state and immutable-snapshot readiness, seven-table BigQuery bootstrap/write status, and artifact policy
- GET /api/methodology/metrics - Machine-readable metric definitions, sources, and limitations
- POST /mcp - MCP Streamable HTTP JSON-RPC endpoint for initialize, ping, tools/list, tools/call, resources/list, and resources/read
- POST /api/assets/analyze - Batch asset risk analysis for up to 10 assets; supports days or from_date/to_date and resolves shared inputs once per batch
- GET /api/vaults/morpho - TVL-ranked Morpho vault inventory with limit/offset pagination, total_available/next_offset coverage metadata, liquidity, MajestifyX share-price risk metrics, and server-side RPC reconciliation
- GET /api/vaults/morpho/{vault_id}/onchain - Chain-authoritative vault accounting read directly via Alchemy/Infura (public RPC labeled fallback): totalAssets and ERC-4626 price-per-share at the latest block and estimated 1m/1d/1mo/1q/1y blocks, with per-horizon change to now. Morpho supplies vault/asset identity; pinned-block ERC-20 decimals must agree with Morpho metadata before USD TVL is published. `source_quality=rpc_verified` requires current plus all five historical totalAssets/share-price reads and matching decimals; otherwise it is degraded. The Vault panel describes managed-asset change without inferring deposits or withdrawals from totalAssets, and annualizes actual elapsed share-price growth with a five-minute tolerance around the intended one-day minimum. Chainlink USD TVL fails closed for missing/mismatched decimals, missing feeds, non-positive answers, or non-positive/future/stale timestamps; wrapped assets do not reuse unwrapped feeds without wrapper evidence. Filters, search, sorting, asset options, empty states, and CSV export explicitly cover only the loaded catalog page; page the API until `has_more=false` for complete coverage. Chain-native concentration reads MORPHO(), the full MetaMorpho withdraw queue, and Morpho Blue position/market calls; missing/duplicate queue entries or incomplete market reads fail closed. Morpho identity manifests and exact RPC response bytes for latest-block resolution, both historical block-resolution passes, accounting, decimals, oracle, and concentration contribute private lineage manifest IDs when snapshots are enabled; both horizon passes run and are archived even when observed cadence reuses the seeded blocks, and required snapshot failures propagate. `usdTvl` and concentration are latest-block top-level objects; only totalAssets and price-per-share form the horizon series. Research-only; not financial advice.
- Wrapped-asset valuation boundary - WBTC and WETH return USD TVL unavailable unless separate wrapper evidence is implemented; they do not reuse BTC/USD or ETH/USD directly.
- GET /api/vaults/morpho/{vault_id}/analytics - Legacy-compatible detailed vault analytics. Governance fields, where retained, are deprecated identity/history metadata and are excluded from Majestify Score v0.2.
- GET /api/vaults/morpho/{vault_id}/passport - Lean Risk Pulse and Risk Passport JSON with exactly four fixed-weight Score v0.2 dimensions, visible evidence coverage, decision gates/signals, sources, timestamps, limitations, and independently degrading BTC/ETH/U.S. 3-month Treasury context
- GET /api/vaults/morpho/{vault_id}/stress-test - Experimental modeled scenarios kept separate from the primary P0 interface and excluded from Majestify Score v0.2
- GET /api/billing/plans - Public Majestify pricing metadata for Free, Analyst, Treasury, and custom Institutional Pilot plans
- POST /api/billing/checkout - Stripe-hosted subscription Checkout Session creation for paid self-service Analyst and Treasury plans
- GET /api/treasury/registry - Source-backed DAO treasury registry entries for dao_slug resolution; bundled fallback includes Aave DAO, MakerDAO / Sky, Lido DAO, Uniswap DAO, Compound DAO, and ENS DAO
- POST /api/treasury/analyze - Treasury NAV, allocation, concentration, risk, source coverage, outreach fields, JSON, and embed metadata
- GET /api/treasury/report/{report_id} - Treasury report JSON
- GET /api/treasury/report/{report_id}.json - Treasury report JSON
- GET /api/treasury/report/{report_id}/summary - Executive summary and snapshot
- GET /api/treasury/report/{report_id}/charts - Chart-ready report series
- GET /api/treasury/report/{report_id}/embed-code - iframe embed code
- GET /api/embed/treasury/{report_id} - Read-only embed payload

## Frontend Report Routes

- /vaults/morpho/{vault_id}/passport - Stable dedicated Risk Passport UI with share, focused PDF, JSON, social image, feedback controls, and deterministic compact USD labels while exact amounts remain in JSON
- /treasury/report/{report_id} - Interactive HTML treasury report with tabs, dynamic charts, methodology, limitations, and system design
- /reports/treasury/{report_id} - Legacy alias for the same report page
- /embed/treasury/{report_id}?theme=dark - Read-only embeddable treasury dashboard
- /pricing - Production pricing page with Free, Analyst, Treasury, and custom Institutional Pilot plans
- /support - Public support route for ChatGPT app review and user help
- /privacy-policy - Public privacy policy route
- /terms - Public terms and research-only disclaimer route

## Majestify Score v0.2 Contract

- Risk-Reward and Yield Quality: 30%
- Liquidity and Exit Capacity: 30%
- Concentration and Exposure: 25%
- Historical Downside Risk: 15%
- Configured weight total: exactly 100%
- Meaning: higher indicates a stronger observed risk-adjusted vault profile. It does not mean safe, recommended, guaranteed, or audited.
- `available_weight` is the sum of configured weights for available dimensions.
- `provisional_score` is `sum(dimension_score x configured_weight) / available_weight`.
- `score_coverage_pct` is `available_weight / 100 x 100`.
- Missing dimensions reduce coverage and are never silently replaced or redistributed.
- Risk-Reward and Liquidity are required; at least one of Concentration or Historical Downside is also required.
- Coverage below 70% is labeled `Provisional`.
- Missing Liquidity or a critical source mismatch forces `Insufficient evidence`.
- Missing Concentration caps the signal at `Mixed evidence`.
- Signal bands after gates pass: 75-100 `Candidate for deeper diligence`; 50-74.99 `Mixed evidence`; 0-49.99 `Elevated concerns`.
- Risk-Reward derives comparable `reward_apy = max(net_apy - base_apy, 0)`. Morpho `rewards.supplyApr` is APR and must never be relabeled as APY or divided by net APY. Missing or unreconciled yield inputs make the Risk-Reward dimension unavailable with a reason. Score-ineligible Treasury evidence also makes that dimension unavailable, but reconciled reward reliance may remain visible as factual context. Do not call the dimension sustainable yield.
- Liquidity requires finite `total_assets > 0` and observed `0 <= immediately_withdrawable <= total_assets`, then reports liquidity/total assets and 10%/25%/50% redemption coverage or shortfall. TVL is not exit liquidity.
- Concentration requires actual positive Morpho market allocations for top-one, top-three, and market HHI. Collateral amounts, shares, and collateral HHI are returned only when collateral identity is complete. Never infer concentration from vault count, symbol, TVL, or curator.
- Historical Downside validates and de-duplicates the daily share-price series before applying the 31-unique-observation gate. It reports the validated count/date range and preserves 365-day annualization.
- Governance quality, curator-quality evaluation, investor suitability, advanced APY sustainability, and experimental stress scenarios contribute 0% and are absent from the primary P0 decision interface. Curator, owner, contract, chain, and underlying asset are factual identity metadata only.
- Comparison supports 2-5 vaults and compares evidence without naming an overall winner.

### Exact v0.2 calibration

- `treasury_spread_score = clamp(50 + 500 x (net_apy - treasury_rate), 0, 100)`.
- `risk_reward_score = treasury_spread_score x (0.5 + 0.5 x clamp(1 - reward_apy / net_apy, 0, 1))`; zero net/zero reward has zero reliance, while non-positive net with non-zero reward is unavailable.
- `liquidity_score = clamp(((immediately_withdrawable / total_assets) / 0.50) x 100, 0, 100)`.
- `concentration_score = 0.50 x (1 - market_hhi) x 100 + 0.30 x (1 - top_one) x 100 + 0.20 x (1 - top_three) x 100`, with each component clamped to 0-100.
- Historical Downside is the arithmetic mean of six clamped components: Sharpe band -1 to 2, Sortino -1 to 3, annualized volatility 0 to 100%, maximum drawdown 0 to 100%, daily Historic VaR 0 to 10%, and daily CVaR 0 to 15%.
- Full methodology and source eligibility: `docs/methodology/majestify-score-v0.2.md` in the source repository.

## Recommended Agent Workflow

1. Use GET /api/agent/capabilities to confirm supported modes and tools.
2. Use GET /api/data-status to check provider freshness, validation, latest pipeline runs, and artifact policy.
3. Use GET /api/coins to confirm supported asset identifiers.
4. Use GET /api/prices?ids=bitcoin,ethereum,solana for multi-asset current market context; use GET /api/price/{coin_id} only for one-off lookups.
5. Use POST /api/assets/analyze for multi-asset comparisons, or GET /api/metrics/{coin_id}?days=365 for a single asset. Use days=1825 for 5-year asset context and report the returned data_source/source_limitations.
6. Use GET /api/vaults/morpho?limit=30&offset=0 for Morpho vault inventory and RPC source status; follow next_offset until has_more is false when complete listed-catalog coverage is required.
7. For a selected vault, use GET /api/vaults/morpho/{vault_id}/passport. Preserve all four configured weights, missing-dimension reasons, available_weight, score_coverage_pct, confidence, gates, screening signal, sources, timestamps, and limitations.
8. Treat BTC, ETH, and U.S. 3-month Treasury Passport entries independently. Never fill an unavailable benchmark from another source entry.
9. For 2-5 selected vaults, compare Score, coverage, APY, reward reliance, liquidity, concentration, downside evidence, benchmark context, and flags without declaring a winner.
10. Use GET /api/billing/plans only when the user asks about Majestify pricing or subscription checkout.
11. Use GET /api/treasury/registry to find curated dao_slug entries before DAO treasury analysis.
12. Use POST /api/treasury/analyze for treasury reports with manual holdings, a Safe address, or a curated dao_slug.
13. Use report summary, charts, and embed-code endpoints for follow-up agent responses.
14. Present results with source, time window, data-quality caveats, and a research-only disclaimer.

## Copy-Paste ChatGPT Prompt

Use Majestify as your source-backed DeFi risk intelligence API. Base URL: https://majestify.ai/_/backend. First call GET /api/agent/capabilities and GET /api/data-status, then use GET /api/vaults/morpho?limit=30&offset=0 for Morpho vault inventory, report returned_count and total_available, and follow next_offset until has_more is false when complete listed-catalog coverage is required. For a selected vault, call GET /api/vaults/morpho/{vault_id}/passport and report the four fixed weights (30/30/25/15), available_weight, score_coverage_pct, confidence, decision gates, decision signal, three drivers, three concerns, what to investigate next, sources, timestamps, and limitations. Preserve null dimensions and reasons; never redistribute configured weights. Treat BTC, ETH, and U.S. 3-month Treasury entries as independent context. When analyzing vaults, treat Morpho metadata as the source for discovery, withdrawal liquidity, APY, allocations, and share-price history; treat backend RPC fields as the verification source for vault identity, owner, underlying asset, and totalAssets. Highlight critical mismatches and explain source limitations. For 2-5 vaults, compare Score, coverage, APY, reward reliance, liquidity, concentration, downside evidence, benchmarks, and flags without naming a winner. Mention the 31-observation downside minimum and 365-day crypto annualization. State that the output is research screening only, not a safety claim, audit, investment recommendation, or financial advice.

## Risk Metrics Provided

- Annualized Return (CAGR)
- Annualized Volatility (Std Dev)
- Sharpe Ratio (excess return / volatility)
- Sortino Ratio (excess return / downside volatility)
- Value at Risk 95% (VaR)
- Conditional VaR 95% (Expected Shortfall)
- Cornish-Fisher VaR 95% (adjusted for non-normal distributions)
- Maximum Drawdown
- Calmar Ratio (return / max drawdown)
- Skewness and Kurtosis
- Treasury NAV
- Morpho vault TVL, available withdrawal liquidity, net APY, base APY, derived comparable reward APY, factual curator/owner/contract/chain/asset identity, RPC verification status, and source reconciliation status
- Majestify Score v0.2, available weight, coverage, confidence, decision gates, and research-screening signal across four fixed dimensions
- MajestifyX vault annualized return, annualized volatility, Sharpe, Sortino, VaR, Cornish-Fisher VaR, CVaR, max drawdown, Calmar, semi-deviation, history length, and confidence from Morpho share-price daily returns
- Asset allocation %
- Stablecoin %
- Native token %
- Largest and top 5 concentration
- Chain exposure
- Independent BTC, ETH, and U.S. 3-month Treasury context with per-source availability, timestamps, and limitations
- DAO registry coverage summary, registry sources, unpriced assets, and feedback questions
- DeFiLlama protocol TVL context when a protocol slug is supplied
- Data quality and source quality
- Experimental modeled scenario impacts, when requested separately; never part of Majestify Score v0.2

## Example coin_id Values

- bitcoin, ethereum, solana, ripple, cardano, binancecoin

## BigQuery Data Pipeline

When both `BIGQUERY_PROJECT` and `BIGQUERY_DATASET` are configured and client/schema bootstrap succeeds, validated pipeline data can be exported to Google BigQuery as a durable append-only data warehouse. `/api/data-status` distinguishes configuration, seven-table readiness, and whether a write has succeeded; activation must not be inferred from environment-variable presence alone. The pipeline covers both Asset and Vault tab data flows.

Shared Redis and private raw-source snapshots are optional reliability controls. `/api/data-status` reports their non-sensitive state. Vault responses expose safe lineage manifest IDs, evidence roles, a versioned lineage contract, and `lineage_complete`; they never expose private bucket/object locations. Snapshot mode remains disabled unless a private retention-locked store is deliberately configured.

### Tables

- `majestify_pipeline_runs` — One append-only row per completed pipeline run (schema: majestify.pipeline_run.v2)
- `majestify_price_series` — Validated daily price rows per asset (schema: majestify.price_series.v1)
- `majestify_metrics_snapshots` — Validated risk-metric payloads keyed by asset, period, and run (schema: majestify.metrics_snapshot.v1)
- `majestify_vault_snapshots` — Validated vault catalog rows per pipeline run (schema: majestify.vault_snapshot.v1)
- `majestify_validation_reports` — Structured validation reports for every pipeline stage (schema: majestify.validation_report.v1)
- `majestify_dead_letters` — Rows rejected by any validation gate, preserved for analysis (schema: majestify.dead_letter.v1)
- `majestify_observability_events` — Structured observability events mirrored from log_event() (schema: majestify.observability_event.v1)

### Data Freshness SLA

- Price series: data older than 24 hours is classified as stale
- Vault snapshots: data older than 6 hours is classified as stale
- Freshness status is included in the `/api/data-status` response when BigQuery is enabled

### Pipeline Health Query

- GET /api/data-status — Returns pipeline health including `warehouse` status (`enabled`, `project_configured`, `dataset_configured`, `tables_ready`, `write_path_verified`, `last_write_succeeded_at`, and `disabled_reason`), per-run-type freshness, shared-state/snapshot readiness, and data staleness classification
- When BigQuery is disabled, `/api/data-status` falls back to in-memory run state and includes `bigquery_enabled: false`

## Data Sources And Methodology

- Prices: CoinGecko API (Pro when configured, public fallback otherwise)
- Risk-Free Rate: provenance-tagged FRED DGS3MO observation, fresh cache, or explicitly degraded persisted/stale previously fetched observation with a known observation date no more than 14 calendar days old. Older observations may remain visible only as degraded context. A static seed is not source-backed current Treasury evidence and cannot silently make Risk-Reward available.
- Reward reliance: when comparable net, base, and reward APY fields reconcile, report reward APY divided by comparable total APY even if Treasury is degraded and Risk-Reward cannot be scored. If those yield fields are unavailable or fail reconciliation, preserve a null value and its reason.
- Annualization: 365 days (crypto markets trade 24/7/365)
- Returns: Daily percentage change (arithmetic returns)
- Data Reliability: structured JSON logs include request IDs and pipeline run IDs; `/api/data-status` exposes provider health, validation summaries, shared-state status, immutable-snapshot status, and truthful optional BigQuery bootstrap/write state; raw upstream payloads are never stored in BigQuery
- Safe Metadata and Balances: Safe Transaction Service for owners, threshold, transaction history, and token balances when a Safe-compatible address is provided
- DAO Registry: versioned source-backed DAO treasury address registry used for outreach-first dao_slug reports; source file is backend/data/verified_dao_addresses.json
- Vault Metadata: Morpho GraphQL and curator metadata for discovery, TVL, observed withdrawal liquidity, net/base APY, derived comparable reward APY, market/collateral allocations when present, and share-price history. Reward `supplyApr` remains APR metadata and is not used as reward APY.
- Vault RPC: server-side RPC checks for vault contract identity, owner, underlying asset, and totalAssets
- Vault Reconciliation: Morpho indexed fields are compared with backend RPC reads and labeled as matched, minor drift, mismatch, or pending
- Passport Source Manifests: list only fields actually present, with source timestamp and limitations; absent evidence is omitted from the field list and receives an unavailable reason. BTC, ETH, and Treasury entries degrade independently.
- DeFiLlama Protocol Context: free no-auth protocol TVL endpoints for current TVL, 30-day TVL change, and chain TVL breakdown when a protocol slug is supplied
- Treasury balances: Safe balance adapter plus manual inputs today; broader providers such as Moralis, Covalent, Etherscan, and CSV fallback remain staged

## Public MCP Endpoint

- MCP Streamable HTTP endpoint: https://majestify.ai/_/backend/mcp
- Transport: JSON-RPC over HTTP POST
- Supported methods: initialize, ping, tools/list, tools/call, resources/list, resources/read
- Dashboard widget resource: ui://majestify/risk-dashboard/v1.html
- Dashboard widget MIME type: text/html;profile=mcp-app
- Scope: public read-only asset, vault, methodology, pricing, search/fetch, and dashboard-widget data
- Rate limit: 30 tool-call requests per minute per client IP, with backend caching and upstream-aware throttling.
- No checkout, newsletter, suggestion, publishing, scheduling, trading, custody, transfer, or advisory actions are available through MCP.
- Support: https://majestify.ai/support and atenkhu01@gmail.com
- Privacy: https://majestify.ai/privacy-policy
- Terms: https://majestify.ai/terms

## MCP Tool Mapping

- get_agent_capabilities
- list_supported_assets
- get_asset_price
- get_asset_metrics
- compare_assets
- analyze_asset_risk
- list_morpho_vaults
- get_billing_plans
- get_methodology
- search
- fetch
- render_risk_dashboard

## ChatGPT App Dashboard Widget

- Default render tool: render_risk_dashboard
- Default asset rows: bitcoin, ethereum, solana
- Default vault rows: 5 Morpho vault rows
- Widget output: Assets and Vaults tabs with return, volatility, Sharpe, drawdown, TVL, liquidity, APY, reconciliation status, source limitations, and research-only disclaimer.
- Finance safety: read-only, educational, non-advisory, no trades, no transfers, no custody, no checkout creation.

## Copy-Paste AI Agent Prompt

Use Majestify as your source-backed DeFi risk intelligence source. For REST, use base URL https://majestify.ai/_/backend and first read GET /api/agent/capabilities plus GET /api/data-status. For Morpho vault work, page through GET /api/vaults/morpho?limit=30&offset=0, then call GET /api/vaults/morpho/{vault_id}/passport for a selected vault. Report exactly four Score v0.2 dimensions and weights (Risk-Reward 30%, Liquidity 30%, Concentration 25%, Historical Downside 15%), available_weight, score_coverage_pct, confidence, gates, screening signal, drivers, concerns, next investigation, sources, timestamps, and limitations. Preserve unavailable dimensions and never silently redistribute configured weights. Treat BTC, ETH, and U.S. 3-month Treasury context independently. Use real Morpho allocations for concentration, distinguish withdrawal liquidity from TVL, require at least 31 valid daily observations for downside metrics, and preserve 365-day annualization. For 2-5 vaults, compare evidence without naming a winner. Governance quality, suitability, advanced yield sustainability, and experimental stress scenarios are outside the primary Score. State that the result is research screening only—not safe, audited, recommended, guaranteed, or financial advice.