# MarketSchema — Cross-Asset Market Intelligence

> MarketSchema produces canonical Schema Scores for tracked assets.
> A Schema Score (0-100) answers: how structurally supportive is the
> current market environment for this asset right now?
> Built on 62 published indexes across 9 risk families.
> All formulas are published. All data sources are public and linked.

## Platform counts (machine-readable)

```yaml
platform:
  indices_public: 62          # canonicalPublicRegistry.PUBLIC_INDEX_COUNT
  families: 9                 # canonicalPublicRegistry.FAMILY_COUNT
  narratives: 32              # canonical narrative catalog
  narratives_risk: 12
  narratives_opportunity: 20
  assets: 586                 # canonicalPublicRegistry.MARKET_ASSET_COUNT
  asset_classes: 5            # equities, crypto, commodities, real-estate, rates-fx
  data_sources_operational: 9 # see OPERATIONAL_DATA_SOURCES
  public_api_endpoints: 14    # see list below — matches PUBLIC_KEEP in route_classification.py
```

All counts above are derived from the canonical registry at build/read time.
If a number here disagrees with a public UI surface, the UI surface is wrong.

## Core product

MarketSchema helps traders and AI agents make allocation and risk decisions
using deterministic, formula-backed intelligence. The canonical output is
the Schema Score packet: one number, one state, one confidence level,
one freshness marker — same truth for humans and bots.

Watchlist is the product surface: a trader's personal list of positions,
each carrying its current Schema Score, state, and driving narratives.
Open assets from any discovery surface (Markets, Narratives, Desk) and
they land there scored.

## Key concepts

- **Schema Score** (0-100): Canonical structural support rating for an asset.
- **Schema State**: strong_tailwind | tailwind | mixed | headwind | strong_headwind
- **Confidence** (0.0-1.0): Data-availability heuristic (coverage + freshness + agreement).
- **Freshness**: live | stale | degraded — how current the underlying data is.
- **Indexes**: 62 published indexes across 9 risk families. Deterministic proof layer.
- **Narratives**: 32 tracked cross-asset narratives (12 risk themes + 20 opportunity themes).
  The public `/narratives` board shows the currently active subset with Driver Strength,
  orientation, drivers, and affected tickers.

  Opportunity themes: AI Infrastructure Buildout, Nuclear Renaissance,
  Robotics & Physical AI, Space Economy, Fintech & Digital Money,
  Clean Energy Transition, Digital Infrastructure & Cloud,
  AI Observability & Telemetry, Operational Memory Layer,
  Data Center Thermal Bottleneck, Crypto Mining AI Compute Conversion,
  Stablecoin Payment Rails, Biology Data Platforms,
  Defense Autonomy & Warfare, Metals & Mining Supercycle,
  Bitcoin Treasury Adoption, GLP-1 & Peptide Revolution,
  Semiconductor Supercycle, Biomedical Innovation, Soft Landing.

  Risk themes: War/Oil Shock, Iran War/Sanctions, Credit Tightening,
  EM Stress, Japan Carry Unwind, CRE Refinancing Wall, SaaS Apocalypse,
  Power Bottleneck, Consumer Staples Resilience, Debasement/Real Assets Bid,
  Crypto Liquidity Regime, Disinflation Trade.
- **Risk Gauges**: Market-wide risk, volatility, and liquidity context.

## API access

- Base URL: https://api.marketschema.com
- Docs: https://marketschema.com/docs
- Auth: API key via header `X-API-Key: ms_...`
- Full reference: https://marketschema.com/llms-full.txt — every endpoint
  with params, response schemas, and prod-captured example responses
- OpenAPI: https://api.marketschema.com/openapi.json

## Public API endpoints (14 total)

The authoritative list is `PUBLIC_KEEP` in `src/api/route_classification.py`.
Counts here MUST match the list length. Anything outside this set is
internal-only and not part of the public contract.

### Auth (3)

- GET  /v1/bot/auth/whoami — Verify API key and return bot identity
- GET  /v1/bot/auth/capabilities — List available endpoints and quotas
- POST /v1/bot/auth/stream-token — Obtain SSE stream auth token

### Asset Packets (2)

- GET  /v1/asset/{ticker} — Canonical Schema Score packet for one asset
- POST /v1/check/batch — Batch score check: up to 25 tickers per call

### Delivery (5)

- GET    /v1/alerts/stream — SSE stream of score changes and alerts

### Market data — the five pillars
- GET /v1/gauges — Risk gauges by family (liquidity, credit, volatility…)
- GET /api/market-risk/current — Market risk composite (risk/vol/liquidity scores)
- GET /indices — All published macro indexes with current values
- GET /indices/{symbol}/history — Index value time series
- GET /v1/trust/narrative-graph — All tracked narratives w/ momentum + state
- GET /api/assets/{asset_id} — Asset detail incl. related_themes (equity:NVDA form)

### Agents & streaming
- GET /v1/agent/openai-tools — OpenAI function-calling manifest (6 tools, no auth)
- GET /v1/stream — Live SSE stream (indices, conditions, ticker_tape channels)

## Public pages

- /watchlist — **Watchlist**: the trader's scored position list (the product's north star)
- /markets — Cross-asset market rankings by Schema Score
- /narratives — current active market narratives with Driver Strength, drivers, affected tickers
- /desk — Pro trader dashboard with Schema Score context
- /indexes — Full index directory (62 public indices)
- /markets/{asset-class}/{ticker} — Schema Score explanation for a single asset
- /alerts — Real-time alert system for market signals (Pro)
- /methodology — Complete formula documentation
- /docs — API documentation with playground
- /compare — Cross-index relationship engine (Pro)
- /track-record — Evaluation metrics once the track-record window matures

## Data sources (operational)

FRED (macro, rates, credit, labor),
Massive.com (equities, ETFs, CBOE indices),
Massive Fundamentals (company financial statements and ratios),
CoinGecko (crypto prices), Binance (crypto funding rates),
Finnhub (company fundamentals fallback), EIA (energy & power),
GridStatus (power grid), Stooq (emergency spot metals fallback)

## Contact

https://marketschema.com/about