# Crypto Market Sentinel

A read-only market anomaly MCP server for Hermes Agent. It watches BTC, ETH, and RENDER, applies volatility-aware P0/P1/P2 thresholds, and emits the shared `pif.event.v1` contract for Hermes to deliver through Feishu.

只看公开行情、不接账户、不交易。冷却、迟滞与断线 fail-closed 都在确定性状态机中执行，而不是交给模型猜。

## Why / 设计理念

- Alert only when the market changes behavior, not when a price merely changes.
- P0 is immediate; P1 enters a digest; P2 is audit-only.
- Repeats are suppressed for 45 minutes, unless the event escalates to 1.5× threshold.
- A triggered rule must fall below 80% of its threshold before it can rearm.
- Data older than 15 seconds pauses new alerts.
- No account, order, withdrawal, signature, or API Secret surface exists.

## Local run

```bash
npm ci
npm test
npm run demo
```

Optional one-shot public Binance snapshot (no API key):

```bash
node src/cli.js --live BTC
```

If Binance is unavailable in the current network, the command exits safely; deterministic demo and MCP tools remain available.

## Add to Hermes on macOS

```bash
git clone https://github.com/roclee2692/crypto-market-sentinel.git ~/Projects/crypto-market-sentinel
cd ~/Projects/crypto-market-sentinel && npm ci
hermes mcp add market-sentinel --command node --args "$HOME/Projects/crypto-market-sentinel/src/mcp.js"
hermes mcp test market-sentinel
```

Hermes exposes names such as `mcp_market_sentinel_evaluate_market_snapshot`. The MCP returns a Feishu-ready message; Hermes keeps using the Feishu channel you already configured.

## Tools

- `evaluate_market_snapshot`
- `simulate_market_scenario`
- `get_market_policy`

The companion repository is [`email-triage-agent`](https://github.com/roclee2692/email-triage-agent). Both use the same urgent/digest/audit event envelope.

See [Hermes macOS setup](docs/HERMES_SETUP.md) and the shared [PIF event contract](docs/PIF_EVENT_V1.md).

## License

MIT. See [LICENSE](LICENSE).