# signaldaemon — API reference

Base URL: `https://api.signaldaemon.com` · Auth: `x-api-key` header (self-serve via `POST /v1/request-key`).

## Endpoints

| method · path | auth | description |
|---|---|---|
| `POST /v1/request-key` | — | Mint a demo key (idempotent per IP). Returns key, expires, quota. |
| `POST /v1/narratives` | x-api-key | Day's ranked narratives + signals + market snapshot. Cached, instant. Body: `{limit}`. |
| `POST /v1/feed` | x-api-key | Clean narrative feed for a query/topic. Body: `{query, category?, limit}`. |
| `POST /v1/vet` | x-api-key | Pre-trade gate: vet a candidate trade against the narrative layer. Body: `{symbol, side, horizon?, source?}`. Returns `{verdict ∈ support/caution/contradict/no_signal, confidence, narrative, reason, evidence}`. Read-only; abstains (`no_signal`) when no single-asset coverage. |
| `GET /mcp` | x-api-key | MCP (Streamable HTTP). Tools: `get_market_narratives`, `get_clean_feed`, `vet_trade`. |
| `GET /v1/preview` | — | Public teaser: top-4 narratives + market snapshot (no sources/full feed). |
| `GET /v1/status` | — | Public: operational status — source count, domains, data freshness. |

Public endpoints are rate-limited (60 req/min/IP).

## Narrative fields (stable)

```
name              — narrative title
gist              — one-line summary
category          — market · protocol · defi · chain · security · mining_equities ·
                    ai_infra · ai_agents · stablecoins · rwa · exchanges · regulation ·
                    macro · prediction_markets   (or "news" when uncategorized)
strength          — cross-source convergence score (higher = more independent,
                    trust-weighted sources converging on the same story now)
distinct_sources / source_diversity / members
momentum          — { members_24h, members_prior } — flow acceleration
divergence        — { code, direction, vs_market, asset, price_change_7d/24h, rel_flow, breadth }
                    code ∈ narrative_price_aligned · narrative_no_flow · neutral · no_asset
                    direction ∈ up · down            — absolute 7d price move
                    vs_market ∈ outperform · underperform — rel_flow sign vs market_7d baseline
                    rel_flow  = asset 7d − market_7d  — narrative vs capital, RELATIVE to regime
                    ⚠ in a crash an asset can be vs_market=outperform yet direction=down
sources           — [ { name, tier } ] — contributing sources (auditable)
representative_items — [ { title, source, url, published_at } ] — deduped by URL

// top-level market_snapshot:
market_snapshot   — { btc/eth/sol {price,chg_24h,chg_7d}, fear_greed,
                    market_7d, market_regime ∈ crash · range · bull }

// /v1/feed items:
items             — [ { title, source, tier, url, published_at, category, summary } ]
coverage          — covered · thin   (fails safe: says "thin" rather than inventing)
```

## Quotas

Demo key: 200 narratives/day, 5 feed calls/day, valid 7 days, one active key per IP/day.
Quotas return HTTP 429 when exceeded. Higher quota / institutional access: apply at
https://signaldaemon.com/#access.
</content>