# Market Signal API - agent skill

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.

## Base URL & auth

- Base URL: `https://api.marketsignalapi.com`
- Auth: send your key in the `X-API-Key` header (never in the URL).
- Key format: `moc_...`. Get one at https://marketsignalapi.com/pricing
- All endpoints are read-only `GET`, responses are JSON, timestamps ISO-8601.
- Honest errors: `401` unknown key, `403` above your tier, `429` + `Retry-After` on rate limit.

## Recommended flow

1. `GET /api/docs` (no key) - machine-readable catalog.
2. `GET /api/scope` - the full breadth in one call (free tier).
3. `GET /api/facts?subject=NVDA` - typed, entity-resolved facts for a ticker (signal tier).
4. `GET /api/graphnet` -> pick a node id -> `GET /api/graphnode?id=...` (intelligence tier).

## Endpoints

### `GET /api/docs`  _[public]_
This document. Machine-readable API self-description.

Params: none

### `GET /api/graphnet`  _[intelligence / $99/mo]_
The full knowledge graph: nodes (assets, actors, sectors, canonical events, world-compass scenarios, discovery names, research theses) and typed edges (threads). Node fields include sig_count (signal activity) and has_chart.

Params: none

### `GET /api/graphnode`  _[intelligence / $99/mo]_
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.

Params: `id` (node id from /api/graphnet)

### `GET /api/knowledge`  _[intelligence / $99/mo]_
Aggregated knowledge layer (the 'brain'): entities with learned relevance.

Params: none

### `GET /api/weltkompass`  _[intelligence / $99/mo]_
World-compass scenarios: macro/geopolitical scenario tree with affected companies, winners, losers, safe havens.

Params: none

### `GET /api/canonik`  _[signal / $19/mo]_
Canonical-event ranking: which current events the council grades as structurally important (early-warning layer), with p_canonical scores.

Params: none

### `GET /api/alliances`  _[intelligence / $99/mo]_
Actor-alliance graph: which actors move together, learned from signals.

Params: none

### `GET /api/industrymap`  _[intelligence / $99/mo]_
Industry map: sectors, their assets and current signal pressure.

Params: none

### `GET /api/fundamentals`  _[intelligence / $99/mo]_
Point-in-time fundamentals from SEC XBRL: TTM revenue/income, YoY growth, margins, EPS, plus optional peer comparison.

Params: `ticker` (US ticker, e.g. NVDA (alias: symbol)), `xbrl` (1 = include SEC-XBRL brief), `peers` (1 = include SIC peer table)

### `GET /api/track`  _[signal / $19/mo]_
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. Forward-only, no backtest; control-group calls are reported separately, plus a parallel directional section (excluded-counters, signed ret_pct).

Params: none

### `GET /api/govawards`  _[signal / $19/mo]_
Dated US federal contract awards (source: USAspending.gov) resolved to public tickers: who receives government money, when, how much, which agency. Intelligence/monitoring, NOT a trading signal or price edge.

Params: none

### `GET /api/facts`  _[signal / $19/mo]_
Typed, entity-resolved, deduplicated facts distilled from the raw text stream (financial news + tracked-actor posts). Each fact carries an event_type, resolved subject ticker(s), a USD magnitude where present, a direction hint, and a source URL. Generic headlines are dropped at the source. This is the ETL an agent would otherwise build itself - structured, queryable, ready to consume. Rule-derived types; direction_hint is a hint, NOT a graded call.

Params: `type` (filter by event_type (whale_transfer|regulation|ma_deal|macro_policy|earnings|partnership|upgrade|hack_exploit|listing|sanction|etf_flow)), `subject` (filter by resolved ticker/coin symbol, e.g. NVDA or BTC), `limit` (max facts to return (default 100))

### `GET /api/resolve`  _[signal / $19/mo]_
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. Precision over recall - returns null rather than a wrong merge.

Params: `name` (raw company/coin name, handle or cashtag to canonicalize, e.g. 'Nvidia', '@nvidia' or '$NVDA'. Omit to list canonical coverage.)

### `GET /api/narrative`  _[signal / $19/mo]_
Research-narrative momentum from arXiv: preprint rate per strategic theme, recent (30d) vs baseline (180d), with a rising-flag. Early indicator of accelerating research themes before consensus. Theme radar, NOT a ticker signal or price edge.

Params: none

### `GET /api/dossier`  _[signal / $19/mo]_
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). One call, honest by design.

Params: none

### `GET /api/brainfork`  _[intelligence / $99/mo]_
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. hit/miss). Display only - NOT wired into any live decision; disclosed as an experiment, not a signal.

Params: none

### `GET /api/scope`  _[free / free]_
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. Machine-readable scale overview for agents.

Params: none

### `GET /api/regime`  _[intelligence / $99/mo]_
Current market-regime classification (vol/trend state) used by the risk layer.

Params: none

### `GET /api/risk`  _[intelligence / $99/mo]_
Portfolio risk snapshot of the paper books: correlated VaR/CVaR, stress scenarios, kill-switch state.

Params: none

## Legal

Operator: SCAFA INVESTMENTS LLC (info@scafa-investments.com). 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.