# Market Signal API

> The denoised, entity-resolved market-fact layer for AI agents. Typed, deduplicated market facts with one canonical ID per company and coin across BOTH equities and crypto, dated canonical events, a knowledge graph, and a crypto hype-velocity detector. The ETL an AI agent would otherwise build itself - structured, entity-resolved and ready to consume, so your agent reasons over clean facts instead of a raw-headline firehose. Every fact is dated and traceable to its source; 91% of generic noise is dropped at ingestion. Convenience and provenance, not investment advice - no claimed price edge.

Operator: SCAFA INVESTMENTS LLC. Base URL: `https://api.marketsignalapi.com`. Auth: header `X-API-Key: moc_...`. All endpoints are read-only GET returning JSON.

## Machine-readable entry points

- [OpenAPI 3.1 spec](https://api.marketsignalapi.com/openapi.json): the full contract - generate a client or an MCP server from it.
- [API self-description](https://api.marketsignalapi.com/api/docs): endpoint catalog as JSON, no key required.
- [Agent skill file](https://marketsignalapi.com/skill.md): single-file routing, auth and examples for an agent.
- [Agent resource catalog](https://marketsignalapi.com/.well-known/ai-catalog.json): discoverable capabilities.

## Endpoints by tier

### public (no key)
- `/api/docs` - This document.

### free (free)
- `/api/scope` - The full breadth in ONE call: how many datapoints, live sources, tracked market actors, intelligence rails, knowledge-graph theses and dated forward-calls the system carries, with per-category breakdown and freshness.

### signal ($19/mo)
- `/api/canonik` - Canonical-event ranking: which current events the council grades as structurally important (early-warning layer), with p_canonical scores.
- `/api/track` - Honest aggregate track record of all forward predictions: hit-rate, Brier score, confidence-bucket calibration and discrimination (high- vs low-confidence), split by horizon (short <7d vs canonical 14d) plus council-verdict record.
- `/api/govawards` - Dated US federal contract awards (source: USAspending.gov) resolved to public tickers: who receives government money, when, how much, which agency.
- `/api/facts` - Typed, entity-resolved, deduplicated facts distilled from the raw text stream (financial news + tracked-actor posts).
- `/api/resolve` - One canonical identity per company/coin: resolves a raw name, @handle or $cashtag to a single ticker (NVDA/Nvidia/@nvidia/$NVDA -> NVDA), so an agent can deduplicate entities across the feed.
- `/api/narrative` - Research-narrative momentum from arXiv: preprint rate per strategic theme, recent (30d) vs baseline (180d), with a rising-flag.
- `/api/dossier` - The product pack: honest forward track record (hit-rate, Brier, control-group calibration) PLUS dated, source-traceable evidence grouped per ticker (who received federal money/when) PLUS an explicit 'what this is / is NOT' framing (intelligence & transparency, NOT a claimed price edge; global FDR disclosed).

### intelligence ($99/mo)
- `/api/graphnet` - The full knowledge graph: nodes (assets, actors, sectors, canonical events, world-compass scenarios, discovery names, research theses) and typed edges (threads).
- `/api/graphnode` - Dossier for one node: live price chart points, latest posts/news, forecasts with outcomes, paper-bot trades, world-compass roles, council verdicts, fundamentals, connected threads.
- `/api/knowledge` - Aggregated knowledge layer (the 'brain'): entities with learned relevance.
- `/api/weltkompass` - World-compass scenarios: macro/geopolitical scenario tree with affected companies, winners, losers, safe havens.
- `/api/alliances` - Actor-alliance graph: which actors move together, learned from signals.
- `/api/industrymap` - Industry map: sectors, their assets and current signal pressure.
- `/api/fundamentals` - Point-in-time fundamentals from SEC XBRL: TTM revenue/income, YoY growth, margins, EPS, plus optional peer comparison.
- `/api/brainfork` - Read-only view of the isolated brain_fork experiment (Phase 1 dataset): a point-in-time feature/target table (per graded forward-call, which signal types preceded it vs.
- `/api/regime` - Current market-regime classification (vol/trend state) used by the risk layer.
- `/api/risk` - Portfolio risk snapshot of the paper books: correlated VaR/CVaR, stress scenarios, kill-switch state.

## What this is / is NOT

All data is informational market intelligence provided by SCAFA INVESTMENTS LLC. It is NOT investment advice, NOT a recommendation to buy or sell any security, and carries no warranty of accuracy or completeness. You act at your own risk.