coinwatch-cli 0.1.0__py3-none-any.whl

coinwatch/__init__.py

@@ -0,0 +1,4 @@
+"""CoinWatch — local-first crypto market monitor & alert engine."""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

coinwatch/alert.py

@@ -0,0 +1,76 @@
+"""Threshold evaluation and alert generation."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .config import Config
+from .sources.base import Quote
+
+STATE_FILE = Path(".coinwatch_state.json")
+
+
+def load_baselines(path: Path = STATE_FILE) -> dict[str, float]:
+    try:
+        if path.exists():
+            raw = json.loads(path.read_text(encoding="utf-8"))
+            if isinstance(raw, dict):
+                return {k: float(v) for k, v in raw.items()}
+    except (OSError, ValueError):
+        pass
+    return {}
+
+
+def save_baselines(baselines: dict[str, float], path: Path = STATE_FILE) -> None:
+    try:
+        path.write_text(json.dumps(baselines, indent=2), encoding="utf-8")
+    except OSError:
+        pass
+
+
+def evaluate(
+    config: Config,
+    quotes: dict[str, Quote],
+    state_path: Path = STATE_FILE,
+) -> list[str]:
+    """Return a list of human-readable alert strings for the given quotes."""
+    alerts: list[str] = []
+    baselines = load_baselines(state_path)
+    next_baselines = dict(baselines)
+
+    for cid, quote in quotes.items():
+        # 1. Absolute 24h move.
+        if config.change_pct_alert > 0 and quote.change_24h_pct is not None:
+            if abs(quote.change_24h_pct) >= config.change_pct_alert:
+                direction = "涨" if quote.change_24h_pct >= 0 else "跌"
+                alerts.append(
+                    f"[{quote.symbol}] 24h {direction} {quote.change_24h_pct:+.2f}% "
+                    f"(阈值 ±{config.change_pct_alert:.1f}%) 现价 ${quote.price:,.2f}"
+                )
+
+        # 2. Static price barriers.
+        above = config.price_above.get(cid)
+        if above is not None and quote.price >= above:
+            alerts.append(f"[{quote.symbol}] 现价 ${quote.price:,.2f} 突破上方 ${above:,.2f}")
+
+        below = config.price_below.get(cid)
+        if below is not None and quote.price <= below:
+            alerts.append(f"[{quote.symbol}] 现价 ${quote.price:,.2f} 跌破下方 ${below:,.2f}")
+
+        # 3. Volume spike against a rolling baseline.
+        if config.volume_spike_pct > 0 and quote.volume_24h:
+            base = baselines.get(cid)
+            if base is None:
+                next_baselines[cid] = quote.volume_24h
+            else:
+                if quote.volume_24h >= base * (1 + config.volume_spike_pct / 100.0):
+                    alerts.append(
+                        f"[{quote.symbol}] 成交量异动 +{(quote.volume_24h / base - 1) * 100:.0f}% "
+                        f"(基线 ${base:,.0f} -> 现 ${quote.volume_24h:,.0f})"
+                    )
+                # Gentle exponential moving average keeps the baseline fresh.
+                next_baselines[cid] = base * 0.9 + quote.volume_24h * 0.1
+
+    save_baselines(next_baselines, state_path)
+    return alerts

coinwatch/cli.py

@@ -0,0 +1,145 @@
+"""Command line interface."""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import sys
+import time
+from pathlib import Path
+
+from . import __version__
+from . import web as web_module
+from .alert import evaluate
+from .config import DEFAULT_CONFIG_NAME, Config, load_config
+from .market import Market
+from .notifier import notify
+from .report import render_text
+
+
+def _render_alerts(alerts: list[str]) -> str:
+    return "\n".join(f"* {a}" for a in alerts)
+
+
+def _print_source_failures(market: Market) -> None:
+    """Surface *why* a snapshot came back empty instead of leaving users guessing."""
+    failures = getattr(market, "last_failures", {}) or {}
+    if not failures:
+        return
+    print("行情源不可用：")
+    for name, err in failures.items():
+        print(f"  ! {name}: {err}")
+    print("  -> 常见原因：本机网络到该 API 不通（部分地区需代理）、或被限流。")
+    print()
+
+
+def cmd_check(args: argparse.Namespace) -> int:
+    config = load_config(args.config)
+    market = Market()
+    quotes = market.snapshot(config.coin_ids, config.watchlist)
+    alerts = evaluate(config, quotes)
+
+    _print_source_failures(market)
+    print(render_text(quotes, []))
+    if alerts:
+        notify(config, "CoinWatch 告警:\n" + _render_alerts(alerts))
+    else:
+        print("无告警。")
+    return 0
+
+
+def cmd_list(args: argparse.Namespace) -> int:
+    config = load_config(args.config)
+    market = Market()
+    quotes = market.snapshot(config.coin_ids, config.watchlist)
+    _print_source_failures(market)
+    print(render_text(quotes, []))
+    return 0
+
+
+def cmd_watch(args: argparse.Namespace) -> int:
+    config = load_config(args.config)
+    market = Market()
+    interval = args.interval or config.interval_seconds
+    print(f"每 {interval}s 轮询一次。Ctrl+C 退出。")
+    # Report source outages once, not once per tick.
+    reported_failures = False
+    try:
+        while True:
+            quotes = market.snapshot(config.coin_ids, config.watchlist)
+            alerts = evaluate(config, quotes)
+            if not reported_failures:
+                _print_source_failures(market)
+                reported_failures = True
+            print(render_text(quotes, []))
+            if alerts:
+                notify(config, "CoinWatch 告警:\n" + _render_alerts(alerts))
+            time.sleep(interval)
+    except KeyboardInterrupt:
+        print("\n已停止。")
+    return 0
+
+
+def cmd_web(args: argparse.Namespace) -> int:
+    config = load_config(args.config)
+    market = Market()
+    web_module.run_web(config, market)
+    return 0
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    example = Path("config.example.toml")
+    target = Path(args.config or DEFAULT_CONFIG_NAME)
+    if target.exists():
+        print(f"{target} 已存在，未覆盖。")
+        return 0
+    if not example.exists():
+        print("未找到 config.example.toml（请在项目根目录运行）。")
+        return 1
+    shutil.copy(example, target)
+    print(f"已生成 {target}，请编辑其中的 watchlist / 阈值 / 通知渠道后使用。")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="coinwatch",
+        description="本地优先的加密货币行情监控与告警引擎。",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"coinwatch {__version__}"
+    )
+    parser.add_argument("--config", default=None, help=f"配置文件路径（默认 {DEFAULT_CONFIG_NAME}）")
+    sub = parser.add_subparsers(dest="command")
+
+    sub.add_parser("check", help="单次快照并触发告警")
+    sub.add_parser("list", help="列出自选行情")
+    watcher = sub.add_parser("watch", help="循环监控")
+    watcher.add_argument("--interval", type=int, default=None, help="轮询间隔（秒）")
+    sub.add_parser("web", help="启动本地 Web 面板")
+    sub.add_parser("init", help="从示例生成 config.toml")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not args.command:
+        parser.print_help()
+        return 0
+    handlers = {
+        "check": cmd_check,
+        "list": cmd_list,
+        "watch": cmd_watch,
+        "web": cmd_web,
+        "init": cmd_init,
+    }
+    try:
+        return handlers[args.command](args)
+    except FileNotFoundError as exc:
+        print(f"错误: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

coinwatch/config.py

@@ -0,0 +1,76 @@
+"""TOML configuration loading."""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+DEFAULT_CONFIG_NAME = "config.toml"
+
+
+@dataclass
+class Config:
+    """Runtime configuration."""
+
+    watchlist: dict[str, str] = field(default_factory=dict)
+    thresholds: dict[str, Any] = field(default_factory=dict)
+    notify: dict[str, Any] = field(default_factory=dict)
+    web: dict[str, Any] = field(default_factory=dict)
+    schedule: dict[str, Any] = field(default_factory=dict)
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def coin_ids(self) -> list[str]:
+        return list(self.watchlist.keys())
+
+    @property
+    def change_pct_alert(self) -> float:
+        return _as_float(self.thresholds.get("change_pct_alert"))
+
+    @property
+    def volume_spike_pct(self) -> float:
+        return _as_float(self.thresholds.get("volume_spike_pct"))
+
+    @property
+    def price_above(self) -> dict[str, float]:
+        return {k: _as_float(v) for k, v in (self.thresholds.get("price_above") or {}).items()}
+
+    @property
+    def price_below(self) -> dict[str, float]:
+        return {k: _as_float(v) for k, v in (self.thresholds.get("price_below") or {}).items()}
+
+    @property
+    def interval_seconds(self) -> int:
+        return int(_as_float(self.schedule.get("interval_seconds"), 300))
+
+
+def _as_float(value: Any, default: float = 0.0) -> float:
+    if value is None or value == "":
+        return default
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def load_config(path: str | Path | None = None) -> Config:
+    """Parse a TOML config file into a Config object."""
+    p = Path(path or DEFAULT_CONFIG_NAME)
+    if not p.exists():
+        raise FileNotFoundError(
+            f"Config not found: {p}\n"
+            "Copy config.example.toml -> config.toml and edit it first: "
+            "`coinwatch init` can do that for you."
+        )
+    with p.open("rb") as fh:
+        data = tomllib.load(fh)
+    return Config(
+        watchlist=data.get("watchlist") or {},
+        thresholds=data.get("thresholds") or {},
+        notify=data.get("notify") or {},
+        web=data.get("web") or {},
+        schedule=data.get("schedule") or {},
+        raw=data,
+    )

coinwatch/market.py

@@ -0,0 +1,44 @@
+"""Market data sources registry and failover-capable snapshot builder."""
+
+from __future__ import annotations
+
+from .sources.binance import Binance
+from .sources.coingecko import CoinGecko
+from .sources.okx import OKX
+from .sources.base import Quote, Source
+
+__all__ = ["Market", "Quote", "Source", "CoinGecko", "Binance", "OKX"]
+
+
+class Market:
+    """Aggregates several sources, falling back between them per coin.
+
+    Sources are tried in order. A coin is satisfied by the first source that
+    returns it, so a single broken provider never takes down the whole run.
+    """
+
+    def __init__(self, sources: list[Source] | None = None) -> None:
+        self.sources: list[Source] = sources or [CoinGecko(), Binance(), OKX()]
+
+    def snapshot(self, coin_ids: list[str], symbols: dict[str, str]) -> dict[str, Quote]:
+        """Fetch every requested coin, using whichever source can answer."""
+        results: dict[str, Quote] = {}
+        pending = list(coin_ids)
+        failures: dict[str, str] = {}
+
+        for source in self.sources:
+            if not pending:
+                break
+            try:
+                got = source.fetch(pending, symbols)
+            except RuntimeError as exc:
+                failures[source.name] = str(exc)
+                continue
+            for cid in list(pending):
+                quote = got.get(cid)
+                if quote is not None:
+                    results[cid] = quote
+                    pending.remove(cid)
+
+        self.last_failures = failures
+        return results

coinwatch/notifier.py

@@ -0,0 +1,82 @@
+"""Notification channels: log, Telegram, Discord, Email."""
+
+from __future__ import annotations
+
+import json
+import smtplib
+import urllib.request
+
+from email.message import EmailMessage
+
+from .config import Config
+
+
+def notify(config: Config, message: str) -> None:
+    """Fan a rendered report out to every enabled channel."""
+    message = message or ""
+    settings = config.notify
+
+    if str(settings.get("log", True)).lower() not in ("false", "0", "no"):
+        if message.strip():
+            print(message)
+
+    # An empty report means "nothing happened" — never spam external channels.
+    if not message.strip():
+        return
+
+    _telegram(settings, message)
+    _discord(settings, message)
+    _email(settings, message)
+
+
+def _post_json(url: str, payload: dict) -> None:
+    body = json.dumps(payload).encode("utf-8")
+    req = urllib.request.Request(
+        url, data=body, headers={"Content-Type": "application/json"}
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=10):
+            pass
+    except Exception:  # noqa: BLE001 - one bad channel must not break the run
+        pass
+
+
+def _telegram(settings: dict, message: str) -> None:
+    token = settings.get("telegram_token")
+    chat_id = settings.get("telegram_chat_id")
+    if not token or not chat_id:
+        return
+    _post_json(
+        f"https://api.telegram.org/bot{token}/sendMessage",
+        {"chat_id": chat_id, "text": message},
+    )
+
+
+def _discord(settings: dict, message: str) -> None:
+    webhook = settings.get("discord_webhook")
+    if not webhook:
+        return
+    # Discord hard-caps embeds/content at 2000 chars.
+    _post_json(webhook, {"content": message[:1900]})
+
+
+def _email(settings: dict, message: str) -> None:
+    host = settings.get("email_smtp_host")
+    recipient = settings.get("email_to")
+    if not host or not recipient:
+        return
+    try:
+        msg = EmailMessage()
+        msg["Subject"] = "CoinWatch Alert"
+        msg["From"] = settings.get("email_smtp_user") or "coinwatch@localhost"
+        msg["To"] = recipient
+        msg.set_content(message)
+
+        with smtplib.SMTP(host, int(settings.get("email_smtp_port", 587))) as server:
+            server.starttls()
+            user = settings.get("email_smtp_user")
+            if user:
+                server.login(user, settings.get("email_smtp_pass", ""))
+            server.send_message(msg)
+    except Exception:  # noqa: BLE001
+        pass

coinwatch/report.py

@@ -0,0 +1,36 @@
+"""Text and JSON report rendering."""
+
+from __future__ import annotations
+
+from .sources.base import Quote
+
+
+def render_text(quotes: dict[str, Quote], alerts: list[str]) -> str:
+    lines = ["", "=== CoinWatch 行情快照 ===", ""]
+    if quotes:
+        lines.append(f"{'SYMBOL':<8}{'PRICE':>14}{'24H':>10}   SOURCE")
+        lines.append("-" * 46)
+        for quote in quotes.values():
+            change = f"{quote.change_24h_pct:+.2f}%" if quote.change_24h_pct is not None else "n/a"
+            lines.append(
+                f"{quote.symbol:<8}{'$' + format(quote.price, ',.2f'):>14}"
+                f"{change:>10}   {quote.source}"
+            )
+    else:
+        lines.append("(无数据 — 所有行情源均不可用)")
+    lines.append("")
+
+    if alerts:
+        lines.append("--- 告警 ---")
+        lines.extend(f"* {a}" for a in alerts)
+    else:
+        lines.append("--- 无告警 ---")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def render_json(quotes: dict[str, Quote], alerts: list[str]) -> dict:
+    return {
+        "quotes": {cid: q.as_dict() for cid, q in quotes.items()},
+        "alerts": alerts,
+    }

coinwatch/sources/__init__.py

@@ -0,0 +1,8 @@
+"""Market data source implementations."""
+
+from .base import Quote, Source, SourceError
+from .binance import Binance
+from .coingecko import CoinGecko
+from .okx import OKX
+
+__all__ = ["Quote", "Source", "SourceError", "CoinGecko", "Binance", "OKX"]

coinwatch/sources/base.py

@@ -0,0 +1,69 @@
+"""Base abstractions for market data sources."""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any
+
+USER_AGENT = "CoinWatch/0.1 (+https://github.com/AlfredoJamesPacino/coinwatch)"
+DEFAULT_TIMEOUT = 10.0
+
+
+class Quote:
+    """A normalized single-coin quote, independent of which source produced it."""
+
+    __slots__ = ("coin_id", "symbol", "price", "change_24h_pct", "volume_24h", "source")
+
+    def __init__(
+        self,
+        coin_id: str,
+        symbol: str,
+        price: float,
+        change_24h_pct: float | None = None,
+        volume_24h: float | None = None,
+        source: str = "",
+    ) -> None:
+        self.coin_id = coin_id
+        self.symbol = symbol
+        self.price = price
+        self.change_24h_pct = change_24h_pct
+        self.volume_24h = volume_24h
+        self.source = source
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "coin_id": self.coin_id,
+            "symbol": self.symbol,
+            "price": self.price,
+            "change_24h_pct": self.change_24h_pct,
+            "volume_24h": self.volume_24h,
+            "source": self.source,
+        }
+
+    def __repr__(self) -> str:  # pragma: no cover - debugging aid
+        return f"<Quote {self.symbol} ${self.price} via {self.source}>"
+
+
+class SourceError(RuntimeError):
+    """Raised when a source cannot be reached or returns unparseable data."""
+
+
+class Source:
+    """Base class for a market data source."""
+
+    name = "base"
+
+    def fetch(self, coin_ids: list[str], symbols: dict[str, str]) -> dict[str, Quote]:
+        """Return quotes for as many of ``coin_ids`` as this source can provide."""
+        raise NotImplementedError
+
+    @staticmethod
+    def _get_json(url: str, timeout: float = DEFAULT_TIMEOUT) -> Any:
+        req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as resp:
+                return json.loads(resp.read().decode("utf-8"))
+        except (urllib.error.URLError, TimeoutError, ValueError) as exc:
+            raise SourceError(f"{url} -> {exc}") from exc

coinwatch/sources/binance.py

@@ -0,0 +1,60 @@
+"""Binance public REST API source (no API key required)."""
+
+from __future__ import annotations
+
+import json
+import urllib.parse
+
+from .base import Quote, Source
+
+_TIMEOUT = 10.0
+
+
+class Binance(Source):
+    name = "binance"
+    BASE = "https://api.binance.com/api/v3/ticker/24hr"
+
+    def fetch(self, coin_ids: list[str], symbols: dict[str, str]) -> dict[str, Quote]:
+        if not coin_ids:
+            return {}
+        # Mapbase symbol -> coin id, restricted to the coins actually requested.
+        wanted = {sym.upper(): cid for cid, sym in symbols.items() if cid in coin_ids}
+        if not wanted:
+            return {}
+
+        pairs = [f"{base}USDT" for base in wanted]
+        # Compact separators keep spaces (which urlencode turns into "+") out of the JSON.
+        query = urllib.parse.urlencode({"symbols": json.dumps(pairs, separators=(",", ":"))})
+        data = self._get_json(f"{self.BASE}?{query}")
+
+        # Binance answers API errors with an object instead of an array.
+        if isinstance(data, dict):
+            return {}
+
+        out: dict[str, Quote] = {}
+        for row in data:
+            pair = row.get("symbol", "")
+            if not pair.endswith("USDT"):
+                continue
+            cid = wanted.get(pair[: -len("USDT")])
+            if cid is None:
+                continue
+            try:
+                out[cid] = Quote(
+                    coin_id=cid,
+                    symbol=symbols.get(cid, pair[: -len("USDT")]),
+                    price=float(row["lastPrice"]),
+                    change_24h_pct=_opt_float(row.get("priceChangePercent")),
+                    volume_24h=_opt_float(row.get("quoteVolume")),
+                    source=self.name,
+                )
+            except KeyError:
+                continue
+        return out
+
+
+def _opt_float(value) -> float | None:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None

coinwatch/sources/coingecko.py

@@ -0,0 +1,42 @@
+"""CoinGecko public API source (no API key required)."""
+
+from __future__ import annotations
+
+from .base import Quote, Source
+
+
+class CoinGecko(Source):
+    name = "coingecko"
+    BASE = "https://api.coingecko.com/api/v3/simple/price"
+
+    def fetch(self, coin_ids: list[str], symbols: dict[str, str]) -> dict[str, Quote]:
+        if not coin_ids:
+            return {}
+        ids = ",".join(coin_ids)
+        url = (
+            f"{self.BASE}?ids={ids}&vs_currencies=usd"
+            "&include_24hr_change=true&include_24hr_vol=true"
+        )
+        data = self._get_json(url)
+
+        out: dict[str, Quote] = {}
+        for cid in coin_ids:
+            row = data.get(cid) if isinstance(data, dict) else None
+            if not row or "usd" not in row:
+                continue
+            out[cid] = Quote(
+                coin_id=cid,
+                symbol=symbols.get(cid, cid.upper()),
+                price=float(row["usd"]),
+                change_24h_pct=_opt_float(row.get("usd_24h_change")),
+                volume_24h=_opt_float(row.get("usd_24h_vol")),
+                source=self.name,
+            )
+        return out
+
+
+def _opt_float(value) -> float | None:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None

coinwatch/sources/okx.py

@@ -0,0 +1,50 @@
+"""OKX public REST API source (no API key required)."""
+
+from __future__ import annotations
+
+from .base import Quote, Source
+
+
+class OKX(Source):
+    name = "okx"
+    BASE = "https://www.okx.com/api/v5/market/tickers?instType=SPOT"
+
+    def fetch(self, coin_ids: list[str], symbols: dict[str, str]) -> dict[str, Quote]:
+        if not coin_ids:
+            return {}
+        wanted = {f"{sym.upper()}-USDT": cid for cid, sym in symbols.items() if cid in coin_ids}
+        if not wanted:
+            return {}
+
+        data = self._get_json(self.BASE)
+        rows = data.get("data") if isinstance(data, dict) else None
+        if not rows:
+            return {}
+
+        out: dict[str, Quote] = {}
+        for row in rows:
+            cid = wanted.get(row.get("instId", ""))
+            if cid is None:
+                continue
+            try:
+                last = float(row["last"])
+                open24h = float(row.get("open24h", last))
+                change = ((last - open24h) / open24h * 100) if open24h else None
+                out[cid] = Quote(
+                    coin_id=cid,
+                    symbol=symbols.get(cid, row["instId"].split("-")[0]),
+                    price=last,
+                    change_24h_pct=change,
+                    volume_24h=_opt_float(row.get("quoteVol24h")),
+                    source=self.name,
+                )
+            except (KeyError, ValueError, ZeroDivisionError):
+                continue
+        return out
+
+
+def _opt_float(value) -> float | None:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None

coinwatch/web.py

@@ -0,0 +1,90 @@
+"""Minimal local dashboard, powered by the standard library only."""
+
+from __future__ import annotations
+
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+from .alert import evaluate
+from .config import Config
+from .market import Market
+from .sources.base import Quote
+
+
+def build_page(quotes: dict[str, Quote], alerts: list[str]) -> str:
+    rows = ""
+    for quote in quotes.values():
+        change = f"{quote.change_24h_pct:+.2f}%" if quote.change_24h_pct is not None else "n/a"
+        color = "#ffffff"
+        if quote.change_24h_pct is not None:
+            # Chinese market convention: up = red, down = green.
+            color = "#ff4d4f" if quote.change_24h_pct >= 0 else "#0ecb81"
+        rows += (
+            f"<tr><td><b>{quote.symbol}</b></td>"
+            f"<td>${quote.price:,.2f}</td>"
+            f'<td style="color:{color}">{change}</td>'
+            f"<td>{quote.source}</td></tr>"
+        )
+    if not rows:
+        rows = '<tr><td colspan="4">无数据 — 所有行情源均不可用</td></tr>'
+
+    alert_html = (
+        "<br>".join(f"&bull; {a}" for a in alerts) if alerts else "当前无告警"
+    )
+
+    return f"""<!doctype html>
+<html><head><meta charset="utf-8">
+<meta http-equiv="refresh" content="60">
+<title>CoinWatch</title>
+<style>
+  body {{ font-family: -apple-system, "Segoe UI", sans-serif; background:#0f1115;
+         color:#e6e6e6; padding:2rem; max-width:900px; margin:0 auto; }}
+  h1 {{ color:#f7931a; margin-bottom:.2rem; }}
+  table {{ border-collapse:collapse; width:100%; margin-top:1rem; }}
+  th, td {{ padding:.6rem .8rem; border-bottom:1px solid #2a2f3a; text-align:left; }}
+  th {{ color:#8b93a7; font-weight:600; }}
+  .card {{ background:#161a22; border:1px solid #232833; border-radius:10px;
+           padding:1rem 1.2rem; margin-top:1.5rem; }}
+  .alert {{ color:#ff6b6b; }}
+  small {{ color:#6b7280; }}
+</style></head>
+<body>
+  <h1>CoinWatch</h1>
+  <small>本地优先 · 数据来源：CoinGecko / Binance / OKX 公开 API · 自动刷新 60s</small>
+  <table>
+    <tr><th>币种</th><th>价格</th><th>24h</th><th>数据源</th></tr>
+    {rows}
+  </table>
+  <div class="card"><b>告警</b><div class="alert">{alert_html}</div></div>
+  <p class="card small">本项目仅做行情监控与告警，不构成任何投资建议。加密货币市场高风险，请自行判断并控制风险。</p>
+</body></html>"""
+
+
+def make_handler(config: Config, market: Market):
+    class Handler(BaseHTTPRequestHandler):
+        def do_GET(self) -> None:  # noqa: N802 - stdlib naming
+            quotes = market.snapshot(config.coin_ids, config.watchlist)
+            alerts = evaluate(config, quotes)
+            body = build_page(quotes, alerts).encode("utf-8")
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html; charset=utf-8")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+        def log_message(self, *args, **kwargs) -> None:
+            pass  # keep the console clean; alerts already go through notify()
+
+    return Handler
+
+
+def run_web(config: Config, market: Market) -> None:
+    host = config.web.get("host", "127.0.0.1")
+    port = int(config.web.get("port", 8080))
+    server = ThreadingHTTPServer((host, port), make_handler(config, market))
+    print(f"CoinWatch dashboard: http://{host}:{port}  (Ctrl+C 退出)")
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        print("\n已停止。")
+    finally:
+        server.server_close()

coinwatch_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,250 @@
+Metadata-Version: 2.5
+Name: coinwatch-cli
+Version: 0.1.0
+Summary: Local-first crypto market monitor & alert engine. Multi-source failover, zero third-party dependencies.
+Project-URL: Homepage, https://github.com/AlfredoJamesPacino/coinwatch
+Project-URL: Repository, https://github.com/AlfredoJamesPacino/coinwatch
+Project-URL: Issues, https://github.com/AlfredoJamesPacino/coinwatch/issues
+Author: MT
+License: MIT
+License-File: LICENSE
+Keywords: alerting,bitcoin,cli,crypto,monitoring,price-tracker
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# CoinWatch
+
+[![CI](https://github.com/AlfredoJamesPacino/coinwatch/actions/workflows/ci.yml/badge.svg)](https://github.com/AlfredoJamesPacino/coinwatch/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+
+**本地优先的加密货币行情监控与告警引擎。**
+
+多数据源自动故障切换，标准库零依赖，调度无关（cron / Windows 任务计划 / WorkBuddy 自动化都能驱动）。
+
+> CoinWatch 只做**数据监控与告警**，不提供任何投资建议。加密货币市场高风险，请自行判断。
+
+---
+
+## 为什么要有它
+
+盯盘的实际痛点，其实就三个：
+
+1. **单一数据源不可靠** —— CoinGecko 免费额度会限流，Binance 在某些地区被墙，OKX 偶尔抖动。挂了就什么都看不到。
+2. **不想一直开着交易所 App** —— 只想在该动的时候被叫一声。
+3. **担心凭证乱飞** —— 没人希望自己的密钥躺在某个不知名软件的数据库里。
+
+CoinWatch 的设计回答就是：**多源兜底 + 阈值告警 + 完全不需要交易所密钥**（只用公开行情接口）。
+
+---
+
+## 特性
+
+- 🔁 **多源故障切换**：CoinGecko → Binance → OKX 逐级兜底，按币种补齐，单源挂掉不影响整体
+- 🔔 **多类告警**：24h 涨跌幅、上下方价格突破、成交量异动（滚动基线）
+- 📡 **多渠道通知**：终端日志 / Telegram / Discord / Email(SMTP)
+- 🌐 **本地面板**：内置 Web Dashboard（每 60s 自动刷新），只监听 `127.0.0.1`
+- 📦 **零第三方依赖**：核心只用 Python 标准库，克隆下来就能跑
+- 🕒 **调度无关**：不自带定时器，交给 cron / 任务计划 / WorkBuddy
+- 🧩 **易扩展**：新增数据源只需实现 `Source.fetch()`
+
+---
+
+## 快速开始
+
+要求 **Python 3.11+**（用到标准库 `tomllib`）。
+
+```bash
+git clone https://github.com/AlfredoJamesPacino/coinwatch.git
+cd coinwatch
+
+# 安装（可选；不装也能跑）
+pip install -e .
+
+# 确认版本
+coinwatch --version
+
+# 生成配置
+coinwatch init          # 从 config.example.toml 复制出 config.toml
+# 编辑 config.toml，设置自选币种、阈值、通知渠道
+
+# 跑一次
+coinwatch check
+```
+
+不想安装的话，直接用模块方式运行：
+
+```bash
+PYTHONPATH=src python -m coinwatch.cli check
+PowerShell:  $env:PYTHONPATH="src"; python -m coinwatch.cli check
+```
+
+首屏输出类似：
+
+```
+=== CoinWatch 行情快照 ===
+
+SYMBOL           PRICE        24H   SOURCE
+----------------------------------------------
+BTC         $67,432.10    +2.31%   coingecko
+ETH          $3,210.55    -1.04%   binance
+SOL            $178.22    +6.77%   coingecko
+
+无告警。
+```
+
+---
+
+## 配置
+
+编辑 `config.toml`（**该文件已被 `.gitignore` 忽略，别提交**）：
+
+```toml
+[watchlist]
+bitcoin  = "BTC"     # 左边是 CoinGecko coin id（小写）
+ethereum = "ETH"
+solana   = "SOL"
+
+[thresholds]
+change_pct_alert = 5.0                        # |24h 涨跌| >= 5% 就告警，0 关闭
+volume_spike_pct = 0.0                        # 成交量异动阈值，0 关闭
+price_above = { "bitcoin" = 200000 }          # 突破上方
+price_below = { "ethereum" = 500 }            # 跌破下方
+
+[notify]
+log = true
+telegram_token = ""          # 从 @BotFather 拿
+telegram_chat_id = ""
+discord_webhook = ""
+email_smtp_host = ""         # 留空即关闭邮件通道
+email_smtp_user = ""
+email_smtp_pass = ""         # 建议用应用专用密码
+email_to = ""
+```
+
+**安全注意**： bot token 和 SMTP 密码只存在本地 `config.toml` 里，**从不随代码提交**。仓库只提交脱敏的 `config.example.toml`。
+
+---
+
+## 命令
+
+| 命令 | 作用 |
+| --- | --- |
+| `coinwatch check` | 拉一次快照，评估阈值，有告警就推送 |
+| `coinwatch list` | 只列出自选行情，不触发告警 |
+| `coinwatch watch [--interval N]` | 循环监控，默认读配置里的 `interval_seconds` |
+| `coinwatch web` | 启动本地面板，默认 `http://127.0.0.1:8080` |
+| `coinwatch init` | 从示例生成 `config.toml` |
+
+所有命令都支持 `--config <path>` 指定配置文件位置；`coinwatch --version` 输出版本号。
+
+---
+
+## 网络与区域可用性
+
+CoinWatch 只用公开行情接口，但这些接口在**部分地区/网络下可能直连不通**（Binance、OKX、CoinGecko 均有被拦或限流的情况）。
+
+遇到这种情况时，CoinWatch **不会假装没数据**，而会把失败原因打出来：
+
+```
+行情源不可用：
+  ! coingecko: https://api.coingecko.com/... -> Tunnel connection failed: 502 Bad Gateway
+  ! binance:   https://api.binance.com/...   -> Tunnel connection failed: 502 Bad Gateway
+  -> 常见原因：本机网络到该 API 不通（部分地区需代理）、或被限流。
+```
+
+处理方式：给本机配好代理即可，`urllib` 会自动读取 `HTTP_PROXY` / `HTTPS_PROXY` 环境变量：
+
+```bash
+export HTTPS_PROXY=http://127.0.0.1:7890
+coinwatch check
+```
+
+由于 3 个源会互相兜底，即使只有一个能通，快照依然完整。
+
+---
+
+## 定时执行
+
+CoinWatch **不自带守护进程**，这是刻意的——交给更专业的调度器，也更省资源。
+
+**Linux / macOS（cron，每 5 分钟）：**
+
+```cron
+*/5 * * * * cd /path/to/coinwatch && python -m coinwatch.cli check >> coinwatch.log 2>&1
+```
+
+**Windows（任务计划程序）：**
+
+```powershell
+$action  = New-ScheduledTaskAction -Execute "python" `
+           -Argument "-m coinwatch.cli check" -WorkingDirectory "C:\path\to\coinwatch"
+$trigger = New-ScheduledTaskTrigger -RepetitionInterval (New-TimeSpan -Minutes 5) -Once -At (Get-Date)
+Register-ScheduledTask -TaskName "CoinWatch" -Action $action -Trigger $trigger
+```
+
+**WorkBuddy 自动化：** 创建一条定时任务，指令为「运行 `coinwatch check` 」，即可把告警接进 AI 工作流。
+
+---
+
+## 架构
+
+```
+src/coinwatch/
+├── config.py      # TOML 加载与阈值访问
+├── market.py      # Market：多源聚合 + 按币种 failover
+├── alert.py       # 阈值评估，成交量基线持久化
+├── notifier.py    # log / Telegram / Discord / Email
+├── report.py      # 文本 & JSON 渲染
+├── web.py         # 标准库 http.server 面板
+├── cli.py         # argparse 入口
+└── sources/
+    ├── base.py       # Quote / Source 抽象
+    ├── coingecko.py
+    ├── binance.py
+    └── okx.py
+```
+
+数据流：
+
+```
+config.toml → Market.snapshot() → alert.evaluate() → notifier.notify()
+                     ↑
+        CoinGecko → Binance → OKX（逐级兜底）
+```
+
+**新增一个数据源**：继承 `Source`，实现 `fetch(coin_ids, symbols) -> dict[str, Quote]`，然后丢进 `Market(sources=[...])`。解析逻辑请配一个 `monkeypatch` 单测，参考 `tests/test_sources.py`。
+
+---
+
+## 开发
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+```
+
+测试不访问网络——用 `monkeypatch` 打桩 `_get_json` 来验证解析逻辑，所以 CI 里跑得又快又稳。
+
+---
+
+## 免责声明
+
+本项目**仅用于行情监控与告警**，不提供任何投资建议、买卖信号或收益承诺。所有数据来自第三方公开 API，可能延迟或不准确，请以交易所实际成交为准。加密货币市场波动剧烈、风险极高，请自行判断并控制风险。
+
+---
+
+## License
+
+[MIT](LICENSE) © 2026 MT

coinwatch_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+coinwatch/__init__.py,sha256=DLLcAZ7ynmSk5HovyQ8fLnxB9372-MqPMYhO7CASnTg,119
+coinwatch/alert.py,sha256=CxhilXzAhVChJSdqZwIDJrxbb5umoU_h4kVm1sxByN4,2813
+coinwatch/cli.py,sha256=sUHjIWWlGPDmn8IxsLZ5amaz4F81YCWW6SUnAf3B6l0,4555
+coinwatch/config.py,sha256=Jdww8Ympr3EmMVfSVdqwd5q-YRDaV4_kPGVuZbAkEig,2329
+coinwatch/market.py,sha256=EU7CgILZC4feRiw16GJmTkPSfg2cz0mzWFCTZSyoQtI,1534
+coinwatch/notifier.py,sha256=k9MGOBAfy_gD7mot7m2EjMBpbbFQfntpGoD72j4QRvY,2437
+coinwatch/report.py,sha256=Jc_D8sEUViXbwU3lMkecuohAVmmACcITpGBiKu32jbc,1140
+coinwatch/web.py,sha256=X_KxclSnEvnM9jD8WkI7s1sNEN0qXKxsAVQBS3fKoQU,3567
+coinwatch/sources/__init__.py,sha256=CfbWgiJVQzXsciQ33C1-xsgZkjALbYJ99hVhsy0AWZU,248
+coinwatch/sources/base.py,sha256=xW0lfNeE9hgWdGqlfPjaSyo9-WZWmZiKoLZjzbx-JM0,2167
+coinwatch/sources/binance.py,sha256=dFTHVOoIl6yL9S2UeknXx5Jm2GswzAALVnxNefeF9B8,1934
+coinwatch/sources/coingecko.py,sha256=gM9Dx1bHXtn1Q0U9r_TczusQ-5zICVXDZr6sggBgJCc,1271
+coinwatch/sources/okx.py,sha256=r-XlPUgcKg-MYZtxh8u9_9kS9MW77b9avmihh3HH4qU,1605
+coinwatch_cli-0.1.0.dist-info/METADATA,sha256=kv4qCx1qY97LRUjrpZBYJ_VhQErtA1K2EKEiYjqbUDM,8593
+coinwatch_cli-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+coinwatch_cli-0.1.0.dist-info/entry_points.txt,sha256=h9uJDTwXIp-pixIGisxsANcuTqOrAn_orTBdbTRqjlo,49
+coinwatch_cli-0.1.0.dist-info/licenses/LICENSE,sha256=p0b81YSNTvs_zRPBcSf2vGoePFdGF16ul0nxKygZJNo,1080
+coinwatch_cli-0.1.0.dist-info/RECORD,,

coinwatch_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

coinwatch_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+coinwatch = coinwatch.cli:main

coinwatch_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.