# signaldaemon

**Narrative & signal intelligence for AI agents** — crypto, AI, and macro.
A dumb-but-trustworthy pipe: it delivers curated *narrative & signal*, not raw data,
and it **fails safe** — when it has no coverage it says so, rather than inventing.
Built for machines, not human eyes.

- **API + MCP**: `https://api.signaldaemon.com`
- **Docs**: https://signaldaemon.com/api
- **Self-serve key**: `POST /v1/request-key` (no signup)

This repo is the **front door** — quickstart, client configs, and the interface
contract. The pipeline itself (sources, scoring, curation) is not open source.

---

## What it is (and isn't)

| It is | It is not |
|---|---|
| Cross-source **narrative convergence** + **capital-vs-narrative divergence** | A price/market-data API (use CoinGecko etc. for that) |
| Coverage across ~14 crypto/AI/macro domains | A raw news firehose |
| **Fails safe** — "no coverage" over hallucination | A database you query for facts |
| For agents (API/MCP), token-cost-agnostic, quality-first | A human-facing dashboard |

## Quickstart

```bash
# 1 · self-serve a demo key (no signup)
KEY=$(curl -s -X POST https://api.signaldaemon.com/v1/request-key | jq -r .key)

# 2 · the day's ranked narratives + derived signals (cached, instant)
curl -s https://api.signaldaemon.com/v1/narratives \
  -H "x-api-key: $KEY" -d '{"limit":8}'

# 3 · clean narrative feed for a topic
curl -s https://api.signaldaemon.com/v1/feed \
  -H "x-api-key: $KEY" -d '{"query":"restaking","limit":8}'
```

## Connect from your agent (MCP)

Remote MCP over Streamable HTTP, authenticated with the `x-api-key` header.

```bash
# Claude Code
claude mcp add --transport http signaldaemon \
  https://api.signaldaemon.com/mcp --header "x-api-key: <KEY>"
```

```yaml
# Hermes Agent — ~/.hermes/config.yaml
mcp_servers:
  signaldaemon:
    url: "https://api.signaldaemon.com/mcp"
    headers: { x-api-key: "<KEY>" }
```

More clients (Cursor, Cline) in [`examples/mcp-configs.md`](examples/mcp-configs.md).
Tools: `get_market_narratives(limit)` · `get_clean_feed(query, category, limit)` ·
`vet_trade(symbol, side)` — all annotated `readOnlyHint`. `vet_trade` is the
pre-trade gate: hand it a candidate trade and it returns a narrative-layer stance
(`support`/`caution`/`contradict`/`no_signal`) with reason + confidence — it vets,
it does not recommend.

## Local stdio bridge

For clients that don't support remote MCP, this repo ships a thin **stdio
bridge** ([`mcp_server.py`](mcp_server.py)) exposing the same three tools over
the hosted API. It holds no methodology — just a client.

```bash
pip install mcp
export SIGNALDAEMON_API_KEY=cns_...   # https://signaldaemon.com/console
python mcp_server.py
```

Or with Docker:

```bash
docker build -t signaldaemon-mcp . && \
docker run -i -e SIGNALDAEMON_API_KEY=cns_... signaldaemon-mcp
```

The bridge starts and answers introspection (`tools/list`) without a key;
tool calls require one.

## Interface

Endpoints and response-field contract (incl. the `divergence` schema) in
[`API.md`](API.md). Field names are stable.

## License

Examples and docs in this repo: MIT (see [LICENSE](LICENSE)).
The signaldaemon service and pipeline are proprietary.
</content>