crypto-terminal 2.0.0__py3-none-any.whl

crypto_terminal/__main__.py

@@ -0,0 +1,9 @@
+from .app import TerminalApp
+
+
+def main():
+    TerminalApp().run()
+
+
+if __name__ == "__main__":
+    main()

crypto_terminal/alerts.py

@@ -0,0 +1,68 @@
+"""Price alerts: fire once when a pair reaches a level or moves a percentage from where the alert was set."""
+
+import math
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+
+from .history import SYMBOL_RE
+from .widgets import fmt_price
+
+KINDS = (">", "<", "move")
+
+
+@dataclass(frozen=True)
+class Alert:
+    symbol: str
+    kind: str  # one of KINDS
+    level: float  # price for > and <, percent for move
+    ref: float | None = None  # move only: the price when the alert was set
+
+    def __str__(self):
+        if self.kind == "move":
+            return f"{self.symbol} moves ±{self.level:g}% from {fmt_price(self.ref)}"
+        return f"{self.symbol} {self.kind} {fmt_price(self.level)}"
+
+
+def valid_level(kind: str, level: float) -> bool:
+    # chained comparisons reject NaN, inf, zero and negatives
+    return 0 < level < (100 if kind == "move" else math.inf)
+
+
+def valid_alert(alert: Alert) -> bool:
+    """Full check for alerts read back from disk (the file is user-editable)."""
+    return (isinstance(alert.symbol, str) and bool(SYMBOL_RE.fullmatch(alert.symbol)) and alert.kind in KINDS
+            and valid_level(alert.kind, alert.level)
+            and (alert.kind != "move" or (alert.ref is not None and 0 < alert.ref < math.inf)))
+
+
+def triggered(alert: Alert, price: float) -> bool:
+    if alert.kind == ">":
+        return price >= alert.level
+    if alert.kind == "<":
+        return price <= alert.level
+    return abs(price - alert.ref) / alert.ref * 100 >= alert.level
+
+
+def check(alerts: list[Alert], symbol: str, price: float) -> tuple[list[Alert], list[Alert]]:
+    """Split alerts into (fired, remaining) for one tick."""
+    fired = [a for a in alerts if a.symbol == symbol and triggered(a, price)]
+    return fired, [a for a in alerts if a not in fired]
+
+
+def desktop_notify(title: str, message: str):
+    """Best effort: osascript on macOS, notify-send on Linux, silently skipped if neither exists."""
+    if sys.platform == "darwin" and shutil.which("osascript"):
+        # text goes in as argv, never spliced into the script, so it can't inject AppleScript
+        args = ["osascript", "-e", "on run argv", "-e",
+                "display notification (item 2 of argv) with title (item 1 of argv)",
+                "-e", "end run", title, message]
+    elif shutil.which("notify-send"):
+        args = ["notify-send", "--", title, message]
+    else:
+        return
+    try:
+        subprocess.Popen(args, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    except OSError:
+        pass

crypto_terminal/app.py

@@ -0,0 +1,369 @@
+import json
+import math
+import os
+import re
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+import httpx
+from textual import work
+from textual.app import App, ComposeResult
+from textual.containers import Horizontal
+from textual.widgets import Input, Static
+
+from .alerts import KINDS, Alert, desktop_notify, valid_alert, valid_level
+from .alerts import check as check_alerts
+from .feed import Feed, Tick
+from .history import GRANULARITIES, SYMBOL_RE, fetch_candles, fetch_products, product_exists, search_products
+from .widgets import INDICATORS, ChartPane, PairPicker, PriceTable, fmt_price
+
+CONFIG_DIR = Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config") / "crypto-terminal"
+WATCHLIST_FILE = CONFIG_DIR / "watchlist.json"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+ALERTS_FILE = CONFIG_DIR / "alerts.json"
+DEFAULT_WATCHLIST = ["BTC-USD", "ETH-USD", "XRP-USD", "SOL-USD", "ADA-USD"]
+QUERY_RE = re.compile(r"[A-Z0-9]{1,20}")  # coin search: `add sol`, `add solana`
+STALE_AFTER = 10  # seconds without any feed frame before the status line shows STALE
+
+
+# ── Watchlist, config + commands ──────────────────────────────────────────────
+
+def write_json(path: Path, data):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2))
+
+
+def load_watchlist() -> list[str]:
+    try:
+        data = json.loads(WATCHLIST_FILE.read_text())
+    except (OSError, ValueError):
+        return list(DEFAULT_WATCHLIST)
+    symbols = data.get("symbols") if isinstance(data, dict) else None
+    if not isinstance(symbols, list):
+        return list(DEFAULT_WATCHLIST)
+    # file is user-editable: keep only well-formed pairs, drop duplicates
+    return list(dict.fromkeys(s for s in symbols if isinstance(s, str) and SYMBOL_RE.fullmatch(s)))
+
+
+def save_watchlist(symbols: list[str]):
+    write_json(WATCHLIST_FILE, {"symbols": symbols})
+
+
+def load_indicators() -> list[str]:
+    try:
+        data = json.loads(CONFIG_FILE.read_text())
+    except (OSError, ValueError):
+        return []
+    names = data.get("indicators") if isinstance(data, dict) else None
+    return [n for n in INDICATORS if isinstance(names, list) and n in names]
+
+
+def save_indicators(names):
+    write_json(CONFIG_FILE, {"indicators": [n for n in INDICATORS if n in names]})
+
+
+def load_alerts() -> list[Alert]:
+    try:
+        data = json.loads(ALERTS_FILE.read_text())
+    except (OSError, ValueError):
+        return []
+    out = []
+    for a in data if isinstance(data, list) else []:
+        try:
+            alert = Alert(a["symbol"], a["kind"], float(a["level"]), None if a.get("ref") is None else float(a["ref"]))
+        except (TypeError, KeyError, ValueError, AttributeError):
+            continue
+        if valid_alert(alert):
+            out.append(alert)
+    return out
+
+
+def save_alerts(alerts: list[Alert]):
+    write_json(ALERTS_FILE, [vars(a) for a in alerts])
+
+
+ALERT_USAGE = "usage: alert BTC-USD > 90000 · alert BTC-USD < 80000 · alert BTC-USD move 5%"
+
+
+def parse_command(text: str) -> tuple[str, str | list[str] | Alert | int | None]:
+    """`add SOL-USD` -> ("add", "SOL-USD"), `add sol` -> ("find", "SOL"), `ind rsi` -> ("ind", ["rsi"]),
+    `alert BTC-USD > 90000` -> ("alert", Alert(...)), `unalert 2` -> ("unalert", 2), `quit` -> ("quit", None).
+
+    Raises ValueError with a user-facing message.
+    """
+    parts = text.split()
+    if not parts:
+        raise ValueError("empty command")
+    cmd, args = parts[0].lower(), parts[1:]
+    if cmd == "quit" and not args:
+        return "quit", None
+    if cmd in ("add", "rm"):
+        if len(args) != 1:
+            raise ValueError(f"usage: {cmd} BASE-QUOTE, e.g. {cmd} SOL-USD")
+        symbol = args[0].upper()
+        if SYMBOL_RE.fullmatch(symbol):
+            return cmd, symbol
+        if cmd == "add" and QUERY_RE.fullmatch(symbol):
+            return "find", symbol
+        raise ValueError(f"not a pair: {args[0]} (expected e.g. SOL-USD{', or a coin: add solana' if cmd == 'add' else ''})")
+    if cmd == "ind":
+        names = [a.lower() for a in args]
+        if names == ["off"]:
+            return "ind", []
+        if not names or any(n not in INDICATORS for n in names):
+            raise ValueError(f"usage: ind {' '.join(INDICATORS)} (toggles) or ind off")
+        return "ind", names
+    if cmd == "alert":
+        if len(args) != 3 or not SYMBOL_RE.fullmatch(args[0].upper()) or args[1].lower() not in KINDS:
+            raise ValueError(ALERT_USAGE)
+        kind = args[1].lower()
+        try:
+            level = float(args[2].removesuffix("%") if kind == "move" else args[2])
+        except ValueError:
+            level = math.nan
+        if not valid_level(kind, level):
+            raise ValueError("move must be between 0 and 100%" if kind == "move" else "price must be a positive number")
+        return "alert", Alert(args[0].upper(), kind, level)
+    if cmd == "alerts" and not args:
+        return "alerts", None
+    if cmd == "unalert":
+        try:
+            index = int(args[0]) if len(args) == 1 else 0
+        except ValueError:
+            index = 0
+        if index < 1:
+            raise ValueError("usage: unalert N (numbers from `alerts`)")
+        return "unalert", index
+    raise ValueError(f"unknown command: {text.strip()} (try add / rm / ind / alert / alerts / unalert / quit)")
+
+
+# ── App ───────────────────────────────────────────────────────────────────────
+
+class TerminalApp(App):
+    TITLE = "Crypto Terminal"
+    CSS = """
+    Screen { background: black; }
+    #title { height: 1; padding: 0 1; background: #ffb000; color: black; text-style: bold; }
+    #main { height: 1fr; }
+    PriceTable { width: 65; height: 1fr; background: black; border-right: solid #ffb000; }
+    PriceTable > .datatable--header { background: black; color: #ffb000; text-style: bold; }
+    PriceTable > .datatable--cursor { background: #3a2a00; }
+    #cmd { display: none; background: black; border: solid #ffb000; }
+    #status { height: 1; padding: 0 1; background: #1c1c1c; color: #ffb000; }
+    """
+    BINDINGS = [
+        ("slash", "command", "Command"),
+        ("colon", "command", "Command"),
+        ("escape", "close_command", "Close command bar"),
+        *((key, f"timeframe('{key}')", label) for key, (label, _) in GRANULARITIES.items()),
+    ]
+
+    def compose(self) -> ComposeResult:
+        yield Static("CRYPTO TERMINAL · COINBASE SPOT · [1-6] 1m 5m 15m 1h 6h 1d · [/] command", id="title", markup=False)
+        with Horizontal(id="main"):
+            yield PriceTable(id="watchlist")
+            yield ChartPane(id="chart")
+        yield Input(placeholder="add SOL-USD · add solana · rm ADA-USD · ind sma20 ema50 vwap rsi · ind off · "
+                                "alert BTC-USD > 90000 · alerts · unalert 1 · quit   (esc closes)", id="cmd")
+        yield Static(id="status", markup=False)  # status carries server text: never parse it as markup
+
+    def on_mount(self):
+        self.symbols = load_watchlist()
+        self.http = httpx.AsyncClient()
+        self.products = None  # online Coinbase pairs, loaded once at startup for `add` search
+        self.feed: Feed | None = None
+        self.feed_status = "idle"
+        self.last_tick = 0.0
+        self.selected: str | None = None
+        self.timeframe = "1"
+        table = self.query_one(PriceTable)
+        table.set_symbols(self.symbols)
+        table.focus()
+        self.query_one(ChartPane).set_indicators(load_indicators())
+        self.alerts = load_alerts()
+        table.set_alerts({a.symbol for a in self.alerts})
+        self.restart_feed()
+        self.load_products()
+        self.set_interval(1, self.refresh_status)
+        self.refresh_status()
+
+    async def on_unmount(self):
+        await self.http.aclose()
+
+    # ── feed ──
+
+    def restart_feed(self):
+        if self.symbols:
+            self.run_feed()  # exclusive worker: cancels the previous connection
+        else:
+            self.workers.cancel_group(self, "feed")
+            self.feed = None
+            self.handle_feed_status("idle")
+
+    @work(exclusive=True, group="feed")
+    async def run_feed(self):
+        self.feed = Feed(self.symbols, self.handle_tick, self.handle_feed_status)
+        await self.feed.run()
+
+    def handle_tick(self, tick: Tick):
+        self.last_tick = time.monotonic()
+        self.query_one(PriceTable).update_tick(tick)
+        if tick.symbol == self.selected:
+            self.query_one(ChartPane).update_price(tick.symbol, tick.price)
+        if self.alerts:
+            fired, self.alerts = check_alerts(self.alerts, tick.symbol, tick.price)
+            if fired:
+                self.alerts_changed()
+                self.bell()
+                for alert in fired:
+                    message = f"{alert} · now {fmt_price(tick.price)}"
+                    self.notify(message, title="🔔 alert", severity="error", timeout=15)
+                    desktop_notify("crypto-terminal alert", message)
+
+    def handle_feed_status(self, status: str):
+        self.feed_status = status
+        self.refresh_status()
+
+    def refresh_status(self):
+        now = time.monotonic()
+        state = self.feed_status.upper()
+        if self.feed and self.feed_status == "live" and now - self.feed.last_msg > STALE_AFTER:
+            state = "STALE"
+        age = f"{now - self.last_tick:.0f}s ago" if self.last_tick else "—"
+        clock = datetime.now(timezone.utc).strftime("%H:%M:%S UTC")
+        self.query_one("#status", Static).update(f"● {state}  │  last tick {age}  │  {clock}")
+
+    @work(exclusive=True, group="products")
+    async def load_products(self):
+        try:
+            self.products = await fetch_products(self.http)
+        except (httpx.HTTPError, ValueError):
+            pass  # `add` falls back to a per-pair lookup; search stays unavailable
+
+    # ── chart ──
+
+    def on_data_table_row_highlighted(self, event: PriceTable.RowHighlighted):
+        self.selected = event.row_key.value
+        self.load_chart()
+
+    def action_timeframe(self, key: str):
+        self.timeframe = key
+        self.load_chart()
+
+    @work(exclusive=True, group="chart")
+    async def load_chart(self):
+        # exclusive: a newer selection cancels this fetch, so a slow reply can't draw the wrong pair
+        chart = self.query_one(ChartPane)
+        if self.selected not in self.symbols:
+            chart.show_message("watchlist empty: press / then `add BTC-USD`")
+            return
+        symbol, (label, granularity) = self.selected, GRANULARITIES[self.timeframe]
+        chart.show_message(f"loading {symbol} {label}…")
+        try:
+            candles = await fetch_candles(self.http, symbol, granularity)
+        except httpx.HTTPError as e:
+            chart.show_message(f"{symbol} {label}: history unavailable ({type(e).__name__})")
+            return
+        chart.show(symbol, label, granularity, candles)
+
+    # ── command bar ──
+
+    def action_command(self):
+        cmd = self.query_one("#cmd", Input)
+        cmd.display = True
+        cmd.focus()
+
+    def action_close_command(self):
+        cmd = self.query_one("#cmd", Input)
+        cmd.value, cmd.display = "", False
+        self.query_one(PriceTable).focus()
+
+    def on_input_submitted(self, event: Input.Submitted):
+        text = event.value
+        self.action_close_command()
+        try:
+            cmd, arg = parse_command(text)
+        except ValueError as e:
+            self.notify(str(e), severity="error")
+            return
+        if cmd == "quit":
+            self.exit()
+        elif cmd == "add":
+            self.add_symbol(arg)
+        elif cmd == "find":
+            self.find_pair(arg)
+        elif cmd == "ind":
+            chart = self.query_one(ChartPane)
+            chart.set_indicators(chart.indicators ^ set(arg) if arg else ())  # toggle
+            save_indicators(chart.indicators)
+        elif cmd == "alert":
+            self.add_alert(arg)
+        elif cmd == "alerts":
+            self.notify("\n".join(f"{i}. {a}" for i, a in enumerate(self.alerts, 1)) or "no alerts", markup=False)
+        elif cmd == "unalert":
+            if arg > len(self.alerts):
+                self.notify(f"no alert {arg} (see `alerts`)", severity="error")
+            else:
+                self.notify(f"removed: {self.alerts.pop(arg - 1)}", markup=False)
+                self.alerts_changed()
+        elif arg not in self.symbols:
+            self.notify(f"{arg} is not on the watchlist", severity="error")
+        else:
+            self.symbols.remove(arg)
+            self.watchlist_changed()
+
+    @work(group="commands")
+    async def add_symbol(self, symbol: str):
+        if symbol in self.symbols:
+            self.notify(f"{symbol} is already on the watchlist")
+            return
+        try:
+            exists = (any(p.id == symbol for p in self.products) if self.products
+                      else await product_exists(self.http, symbol))
+        except httpx.HTTPError as e:
+            self.notify(f"could not check {symbol} with Coinbase ({type(e).__name__})", severity="error")
+            return
+        if not exists:
+            self.notify(f"unknown pair: {symbol}", severity="error")
+        elif symbol not in self.symbols:  # re-check: a second `add` may have landed while we awaited
+            self.symbols.append(symbol)
+            self.watchlist_changed()
+
+    def find_pair(self, query: str):
+        if not self.products:
+            self.notify("coin search unavailable (Coinbase product list not loaded): add an exact pair, e.g. add SOL-USD",
+                        severity="error")
+            return
+        matches = search_products(self.products, query)
+        if not matches:
+            self.notify(f"no matches for {query}", severity="error")
+        else:
+            self.push_screen(PairPicker(query, matches), lambda symbol: symbol and self.add_symbol(symbol))
+
+    def add_alert(self, alert: Alert):
+        # ticks only arrive for watchlist pairs, so an alert anywhere else could never fire
+        if alert.symbol not in self.symbols:
+            self.notify(f"{alert.symbol} is not on the watchlist: add it first", severity="error")
+            return
+        if alert.kind == "move":
+            ref = self.query_one(PriceTable).last_price(alert.symbol)
+            if ref is None:
+                self.notify(f"no price for {alert.symbol} yet: try again in a moment", severity="error")
+                return
+            alert = Alert(alert.symbol, alert.kind, alert.level, ref)
+        self.alerts.append(alert)
+        self.alerts_changed()
+        self.notify(f"alert set: {alert}", markup=False)
+
+    def alerts_changed(self):
+        save_alerts(self.alerts)
+        self.query_one(PriceTable).set_alerts({a.symbol for a in self.alerts})
+
+    def watchlist_changed(self):
+        save_watchlist(self.symbols)
+        self.query_one(PriceTable).set_symbols(self.symbols)
+        self.query_one(PriceTable).set_alerts({a.symbol for a in self.alerts})
+        self.restart_feed()
+        if not self.symbols:
+            self.load_chart()

crypto_terminal/feed.py

@@ -0,0 +1,98 @@
+"""Coinbase Exchange public websocket feed (ticker + heartbeat channels, no API key)."""
+
+import asyncio
+import json
+import math
+import random
+import ssl
+import time
+from dataclasses import dataclass
+from typing import Callable
+
+import certifi
+from websockets.asyncio.client import connect
+
+FEED_URL = "wss://ws-feed.exchange.coinbase.com"
+RECONNECT_AFTER = 30  # seconds of silence (heartbeats arrive every 1s) before the socket is presumed dead
+MAX_BACKOFF = 30
+
+# python.org macOS builds ship without a CA bundle; use certifi's so wss:// works everywhere
+SSL_CONTEXT = ssl.create_default_context(cafile=certifi.where())
+
+
+@dataclass(frozen=True)
+class Tick:
+    symbol: str
+    price: float
+    open_24h: float
+
+
+def parse_tick(msg: dict) -> Tick | None:
+    """Validate a `ticker` message. Returns None for anything malformed."""
+    if msg.get("type") != "ticker":
+        return None
+    try:
+        symbol = msg["product_id"]
+        price = float(msg["price"])
+        open_24h = float(msg["open_24h"])
+    except (KeyError, TypeError, ValueError):
+        return None
+    # chained comparisons reject NaN, inf, zero and negatives
+    if not isinstance(symbol, str) or not (0 < price < math.inf and 0 < open_24h < math.inf):
+        return None
+    return Tick(symbol, price, open_24h)
+
+
+class Feed:
+    """Streams ticks for `symbols` forever, reconnecting with exponential backoff.
+
+    `status` is one of: connecting, live, reconnecting in Ns (reason).
+    `last_msg` is the monotonic time of the last frame received (ticks or heartbeats).
+    """
+
+    def __init__(self, symbols: list[str], on_tick: Callable[[Tick], None],
+                 on_status: Callable[[str], None] = lambda s: None, url: str = FEED_URL,
+                 reconnect_after: float = RECONNECT_AFTER):
+        self.symbols = list(symbols)
+        self.on_tick = on_tick
+        self.on_status = on_status
+        self.url = url
+        self.reconnect_after = reconnect_after
+        self.last_msg = 0.0
+
+    async def run(self):
+        delay = 1
+        while True:
+            self.on_status("connecting")
+            try:
+                async with connect(self.url, ssl=SSL_CONTEXT if self.url.startswith("wss") else None,
+                                   open_timeout=10) as ws:
+                    await ws.send(json.dumps({"type": "subscribe", "product_ids": self.symbols,
+                                              "channels": ["ticker", "heartbeat"]}))
+                    live = False
+                    while True:
+                        # wait_for catches a half-open socket that never errors
+                        raw = await asyncio.wait_for(ws.recv(), self.reconnect_after)
+                        try:
+                            msg = json.loads(raw)
+                        except ValueError:
+                            continue
+                        if not isinstance(msg, dict):
+                            continue
+                        if msg.get("type") == "error":
+                            raise RuntimeError(str(msg.get("reason") or msg.get("message")))
+                        tick = parse_tick(msg)
+                        if tick or msg.get("type") == "heartbeat":
+                            self.last_msg = time.monotonic()
+                            if not live:
+                                # only data proves the link works, so backoff resets here, not on connect
+                                live, delay = True, 1
+                                self.on_status("live")
+                        if tick:
+                            self.on_tick(tick)
+            except asyncio.CancelledError:
+                raise
+            except Exception as e:  # network errors, closes, timeouts, server errors: all mean reconnect
+                self.on_status(f"reconnecting in {delay}s ({str(e) or type(e).__name__})")
+            await asyncio.sleep(delay + random.uniform(0, delay / 4))
+            delay = min(delay * 2, MAX_BACKOFF)

crypto_terminal/history.py

@@ -0,0 +1,113 @@
+"""Coinbase Exchange REST: candle history and product lookup (public, no API key)."""
+
+import math
+import re
+import time
+from typing import NamedTuple
+
+import httpx
+
+REST_BASE = "https://api.exchange.coinbase.com"
+SYMBOL_RE = re.compile(r"[A-Z0-9]{1,10}-[A-Z0-9]{2,10}")
+QUOTE_RANK = ("USD", "USDC", "USDT", "EUR", "GBP", "BTC")  # search lists these quotes first, in this order
+MAX_CANDLES = 300  # Coinbase caps a request at 300 candles
+
+# key -> (label, candle granularity in seconds): every granularity Coinbase offers
+GRANULARITIES = {
+    "1": ("1m", 60),
+    "2": ("5m", 300),
+    "3": ("15m", 900),
+    "4": ("1h", 3600),
+    "5": ("6h", 21600),
+    "6": ("1d", 86400),
+}
+
+
+class Candle(NamedTuple):
+    t: float  # bucket start, unix seconds
+    o: float
+    h: float
+    l: float
+    c: float
+    v: float
+
+
+class Product(NamedTuple):
+    id: str
+    base: str
+    quote: str
+    name: str  # base coin's full name ("Solana"), "" if unknown
+
+
+async def fetch_products(client: httpx.AsyncClient) -> list[Product]:
+    """Every online pair, with coin names from /currencies when available. Raises httpx.HTTPError / ValueError."""
+    resp = await client.get(f"{REST_BASE}/products", timeout=10)
+    resp.raise_for_status()
+    rows = resp.json()
+    names = {}
+    try:  # names are a nicety: search by symbol still works without them
+        cur = await client.get(f"{REST_BASE}/currencies", timeout=10)
+        cur.raise_for_status()
+        currencies = cur.json()
+        names = {c["id"]: c["name"] for c in currencies if isinstance(c, dict)
+                 and isinstance(c.get("id"), str) and isinstance(c.get("name"), str)} if isinstance(currencies, list) else {}
+    except (httpx.HTTPError, ValueError):
+        pass
+    out = []
+    for row in rows if isinstance(rows, list) else []:
+        if (isinstance(row, dict) and row.get("status") == "online" and row.get("trading_disabled") is False
+                and isinstance(row.get("id"), str) and SYMBOL_RE.fullmatch(row["id"])):
+            base, quote = row["id"].split("-")
+            out.append(Product(row["id"], base, quote, names.get(base, "")))
+    return out
+
+
+def search_products(products: list[Product], query: str) -> list[Product]:
+    """Pairs whose coin symbol or name matches `query` (exact before prefix), best-known quote currencies first."""
+    q = query.upper()
+
+    def rank(p: Product):
+        exact = q in (p.base, p.name.upper())
+        quote = QUOTE_RANK.index(p.quote) if p.quote in QUOTE_RANK else len(QUOTE_RANK)
+        return not exact, quote, p.id
+
+    return sorted((p for p in products if p.base.startswith(q) or p.name.upper().startswith(q)), key=rank)
+
+
+async def fetch_candles(client: httpx.AsyncClient, symbol: str, granularity: int) -> list[Candle]:
+    """Return the last MAX_CANDLES candles, oldest first. Raises httpx.HTTPError on network/HTTP failure."""
+    end = int(time.time())
+    resp = await client.get(f"{REST_BASE}/products/{symbol}/candles", params={
+        "granularity": granularity, "start": end - MAX_CANDLES * granularity, "end": end,
+    }, timeout=10)
+    resp.raise_for_status()
+    # rows are [time, low, high, open, close, volume], newest first; skip anything malformed
+    rows = resp.json()
+    out = []
+    for row in rows if isinstance(rows, list) else []:
+        try:
+            t, low, high, open_, close, volume = map(float, row[:6])
+        except (TypeError, ValueError, KeyError):
+            continue
+        if all(map(math.isfinite, (t, low, high, open_, close, volume))):
+            out.append(Candle(t, open_, high, low, close, volume))
+    return sorted(out)
+
+
+def apply_tick(candles: list[Candle], price: float, now: float, granularity: int):
+    """Fold a live price into the last candle, or roll over to a new candle once `now` leaves its bucket."""
+    bucket = now - now % granularity
+    last = candles[-1]
+    if bucket <= last.t:
+        candles[-1] = last._replace(h=max(last.h, price), l=min(last.l, price), c=price)
+    else:
+        candles.append(Candle(bucket, price, price, price, price, 0.0))
+        del candles[0]
+
+
+async def product_exists(client: httpx.AsyncClient, symbol: str) -> bool:
+    resp = await client.get(f"{REST_BASE}/products/{symbol}", timeout=10)
+    if resp.status_code in (400, 404):
+        return False
+    resp.raise_for_status()
+    return True

crypto_terminal/indicators.py

@@ -0,0 +1,44 @@
+"""Chart indicators as pure functions. Each returns a list aligned with its input, None until there is enough data."""
+
+DAY = 86400
+
+
+def sma(values: list[float], n: int) -> list[float | None]:
+    return [None] * min(n - 1, len(values)) + [sum(values[i - n:i]) / n for i in range(n, len(values) + 1)]
+
+
+def ema(values: list[float], n: int) -> list[float | None]:
+    """Seeded with the SMA of the first n values, then smoothed with k = 2 / (n + 1)."""
+    if len(values) < n:
+        return [None] * len(values)
+    out, k = [None] * (n - 1) + [sum(values[:n]) / n], 2 / (n + 1)
+    for v in values[n:]:
+        out.append(v * k + out[-1] * (1 - k))
+    return out
+
+
+def rsi(closes: list[float], n: int = 14) -> list[float | None]:
+    """Wilder's RSI: average gain / loss over n changes, then Wilder smoothing."""
+    out = [None] * len(closes)
+    if len(closes) <= n:
+        return out
+    deltas = [b - a for a, b in zip(closes, closes[1:])]
+    gain = sum(max(d, 0) for d in deltas[:n]) / n
+    loss = sum(max(-d, 0) for d in deltas[:n]) / n
+    for i in range(n, len(closes)):
+        if i > n:
+            d = deltas[i - 1]
+            gain, loss = (gain * (n - 1) + max(d, 0)) / n, (loss * (n - 1) + max(-d, 0)) / n
+        out[i] = 100.0 if loss == 0 else 100 - 100 / (1 + gain / loss)
+    return out
+
+
+def vwap(candles) -> list[float | None]:
+    """Volume-weighted typical price over candles (t, h, l, c, v), reset at each UTC day boundary."""
+    out, day, pv, vol = [], None, 0.0, 0.0
+    for c in candles:
+        if c.t // DAY != day:
+            day, pv, vol = c.t // DAY, 0.0, 0.0
+        pv, vol = pv + (c.h + c.l + c.c) / 3 * c.v, vol + c.v
+        out.append(pv / vol if vol else None)
+    return out

crypto_terminal/widgets.py

@@ -0,0 +1,228 @@
+import math
+import time
+from collections import deque
+from datetime import datetime, timezone
+
+from rich.text import Text
+from textual.screen import ModalScreen
+from textual.widgets import DataTable, OptionList
+from textual.widgets.option_list import Option
+from textual_plotext import PlotextPlot
+
+from .feed import Tick
+from .history import Candle, Product, apply_tick
+from .indicators import ema, rsi, sma, vwap
+
+SPARK = "▁▂▃▄▅▆▇█"
+SPARK_LEN = 20
+SIG_FIGS = 5
+FLASH_SECONDS = 0.5
+UP, DOWN = "green", "red"
+REDRAW_EVERY = 0.5  # live candle redraws at most twice a second
+VOLUME_ROWS = 7
+RSI_ROWS = 8
+
+# name -> (legend, colour, series over all candles); RSI gets its own panel
+OVERLAYS = {
+    "sma20": ("SMA 20", "yellow", lambda candles: sma([c.c for c in candles], 20)),
+    "ema50": ("EMA 50", "cyan", lambda candles: ema([c.c for c in candles], 50)),
+    "vwap": ("VWAP", "magenta", vwap),
+}
+INDICATORS = (*OVERLAYS, "rsi")
+
+
+def fmt_price(value: float) -> str:
+    """2 decimals from 1,000 up, otherwise enough decimals for SIG_FIGS significant figures (0.0021300)."""
+    if value >= 1_000:
+        return f"{value:,.2f}"
+    decimals = max(2, SIG_FIGS - 1 - math.floor(math.log10(value))) if value > 0 else 2
+    return f"{value:.{decimals}f}"
+
+
+def visible(times: list[float], series: list[float | None]) -> tuple[list, list]:
+    """Tail of `series` lined up with `times`, minus the None warm-up."""
+    pts = [(t, v) for t, v in zip(times, series[-len(times):]) if v is not None]
+    return [t for t, _ in pts], [v for _, v in pts]
+
+
+def sparkline(values) -> str:
+    lo, hi = min(values), max(values)
+    if hi == lo:
+        return SPARK[0] * len(values)
+    return "".join(SPARK[round((v - lo) / (hi - lo) * (len(SPARK) - 1))] for v in values)
+
+
+class PriceTable(DataTable):
+    """Watchlist: one row per pair, price flashes green/red on each up/down tick."""
+
+    def on_mount(self):
+        self.cursor_type = "row"
+        for label, key, width in (("PAIR", "sym", 13), ("LAST", "last", 12), ("24H %", "chg", 10),
+                                  ("TICKS", "spark", SPARK_LEN)):
+            self.add_column(label, key=key, width=width)
+        self._last: dict[str, Tick] = {}
+        self._dir: dict[str, str] = {}
+        self._spark: dict[str, deque] = {}
+        self._flashing: set[str] = set()
+
+    def set_symbols(self, symbols: list[str]):
+        for sym in list(self._spark):
+            if sym not in symbols:
+                self.remove_row(sym)
+                for d in (self._last, self._dir, self._spark):
+                    d.pop(sym, None)
+        for sym in symbols:
+            if sym not in self._spark:
+                self._spark[sym] = deque(maxlen=SPARK_LEN)
+                self.add_row(Text(sym, style="bold"), "—", "—", "", key=sym)
+
+    def set_alerts(self, symbols: set[str]):
+        """Mark pairs that have an alert set."""
+        for sym in self._spark:
+            self.update_cell(sym, "sym", Text(f"{sym} 🔔" if sym in symbols else sym, style="bold"))
+
+    def last_price(self, sym: str) -> float | None:
+        return self._last[sym].price if sym in self._last else None
+
+    def update_tick(self, tick: Tick):
+        sym = tick.symbol
+        if sym not in self._spark:  # late tick for a pair just removed
+            return
+        prev = self._last.get(sym)
+        self._last[sym] = tick
+        self._spark[sym].append(tick.price)
+        if prev and tick.price != prev.price:
+            self._dir[sym] = UP if tick.price > prev.price else DOWN
+            if sym not in self._flashing:
+                self._flashing.add(sym)
+                self.set_timer(FLASH_SECONDS, lambda: self._unflash(sym))
+        pct = (tick.price - tick.open_24h) / tick.open_24h * 100
+        self.update_cell(sym, "chg", Text(f"{'▲' if pct >= 0 else '▼'} {pct:+.2f}%", style=UP if pct >= 0 else DOWN))
+        self.update_cell(sym, "spark", Text(sparkline(self._spark[sym]), style="dark_orange"))
+        self._render_price(sym)
+
+    def _unflash(self, sym: str):
+        self._flashing.discard(sym)
+        if sym in self._last:
+            self._render_price(sym)
+
+    def _render_price(self, sym: str):
+        color = self._dir.get(sym, "white")
+        style = f"bold black on {color}" if sym in self._flashing else f"bold {color}"
+        self.update_cell(sym, "last", Text(fmt_price(self._last[sym].price), style=style, justify="right"))
+
+
+class PairPicker(ModalScreen[str | None]):
+    """Search results for `add <coin>`: enter adds the highlighted pair, esc cancels."""
+
+    BINDINGS = [("escape", "dismiss", "Cancel")]
+    DEFAULT_CSS = """
+    PairPicker { align: center middle; }
+    PairPicker > OptionList { width: 50; height: auto; max-height: 20; background: black; border: solid #ffb000; }
+    """
+
+    def __init__(self, query: str, products: list[Product]):
+        super().__init__()
+        self.term, self.products = query, products
+
+    def compose(self):
+        # Text, not str: coin names are server data and must never be parsed as markup
+        picker = OptionList(*(Option(Text(f"{p.id:<14}{p.name}"), id=p.id) for p in self.products))
+        picker.border_title = f"add {self.term.lower()} · enter adds · esc cancels"
+        yield picker
+
+    def on_option_list_option_selected(self, event: OptionList.OptionSelected):
+        self.dismiss(event.option.id)
+
+
+class ChartPane(PlotextPlot):
+    """Candles for one pair; the last candle follows live ticks via `update_price`."""
+
+    def on_mount(self):
+        self.theme = "dark"
+        self.symbol, self.candles, self.indicators, self._dirty = None, [], set(), False
+        self.set_interval(REDRAW_EVERY, self._redraw_if_dirty)
+        self.show_message("select a pair")
+
+    def show_message(self, text: str):
+        self.candles = []  # stop live updates until the next `show`
+        self.plt.clear_figure()
+        self.plt.title(text)
+        self.refresh()
+
+    def show(self, symbol: str, label: str, granularity: int, candles: list[Candle]):
+        if not candles:
+            return self.show_message(f"{symbol} {label}: no data")
+        self.symbol, self.label, self.granularity, self.candles = symbol, label, granularity, candles
+        self._draw()
+
+    def set_indicators(self, names):
+        self.indicators = set(names)
+        self._dirty = bool(self.candles)
+
+    def update_price(self, symbol: str, price: float):
+        if self.candles and symbol == self.symbol:
+            apply_tick(self.candles, price, time.time(), self.granularity)
+            self._dirty = True
+
+    def on_resize(self):
+        self._dirty = bool(self.candles)  # visible candle count depends on width
+
+    def _redraw_if_dirty(self):
+        if self._dirty and self.candles:
+            self._draw()
+
+    def _draw(self):
+        self._dirty = False
+        # one terminal column per candle: draw the tail that fits; indicators see the full history
+        shown = self.candles[-max(10, self.size.width - 12):]
+        times = [c.t for c in shown]
+        lines = [(legend, color, visible(times, series(self.candles)))
+                 for name, (legend, color, series) in OVERLAYS.items() if name in self.indicators]
+        show_rsi = "rsi" in self.indicators
+        panels = 3 if show_rsi else 2
+        plt = self.plt
+        plt.clear_figure()
+        plt.subplots(panels, 1)
+
+        top = plt.subplot(1, 1)
+        top.candlestick(times, {"Open": [c.o for c in shown], "Close": [c.c for c in shown],
+                                "High": [c.h for c in shown], "Low": [c.l for c in shown]})
+        for legend, color, (xs, ys) in lines:
+            if xs:
+                top.plot(xs, ys, color=color, marker="braille", label=legend)
+        top.title(f"{self.symbol} · {self.label} · {fmt_price(shown[-1].c)} (UTC)")
+        # our own y labels, padded to one width, so every panel's x axis lines up under the candles
+        overlay_values = [y for _, _, (_, ys) in lines for y in ys]
+        lo, hi = min([c.l for c in shown] + overlay_values), max([c.h for c in shown] + overlay_values)
+        ys = [lo + (hi - lo) * i / 4 for i in range(5)]
+        width = max(len(fmt_price(y)) for y in ys)
+        top.yticks(ys, [fmt_price(y).rjust(width) for y in ys])
+
+        vol = plt.subplot(2, 1)
+        vol.plotsize(None, VOLUME_ROWS)
+        vmax = max(c.v for c in shown)
+        vol.bar(times, [c.v for c in shown], color="blue", width=0.5)
+        vol.yticks([0, vmax], ["0".rjust(width), fmt_price(vmax).rjust(width)])
+
+        if show_rsi:
+            panel = plt.subplot(3, 1)
+            panel.plotsize(None, RSI_ROWS)
+            xs, ys = visible(times, rsi([c.c for c in self.candles]))
+            if xs:
+                panel.plot(xs, ys, color="orange", marker="braille", label="RSI 14")
+            panel.hline(70, "gray")
+            panel.hline(30, "gray")
+            panel.ylim(0, 100)
+            panel.yticks([30, 70], ["30".rjust(width), "70".rjust(width)])
+
+        fmt = "%d/%m" if self.granularity >= 3600 else "%H:%M"
+        ticks = times[:: max(1, len(times) // 5)]
+        for row in range(1, panels + 1):
+            panel = plt.subplot(row, 1)
+            panel.xlim(times[0], times[-1])
+            if row < panels:
+                panel.xticks([])
+        # numeric x + our own tick labels: plotext's date parsing loses the day for "H:M" and wraps at midnight
+        panel.xticks(ticks, [datetime.fromtimestamp(t, timezone.utc).strftime(fmt) for t in ticks])
+        self.refresh()

crypto_terminal-2.0.0.dist-info/METADATA

@@ -0,0 +1,128 @@
+Metadata-Version: 2.5
+Name: crypto-terminal
+Version: 2.0.0
+Summary: A free, Bloomberg-style crypto terminal for your shell: live Coinbase prices, candles, indicators and alerts.
+Project-URL: Homepage, https://github.com/owen-alderson/crypto-terminal
+Author: Owen Alderson
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bitcoin,coinbase,crypto,terminal,textual,tui
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.10
+Requires-Dist: certifi
+Requires-Dist: httpx>=0.27
+Requires-Dist: textual-plotext>=1.0
+Requires-Dist: textual>=8.0
+Requires-Dist: websockets>=14.0
+Description-Content-Type: text/markdown
+
+# crypto-terminal
+
+A free, Bloomberg-style crypto terminal that runs in your shell. Live spot prices stream straight from the Coinbase Exchange public websocket: no API key, no account, no polling. Candlestick charts with a live last bar, indicators, price alerts, and search across every Coinbase pair.
+
+![Crypto terminal demo: live candles, indicators, coin search and a price alert](https://raw.githubusercontent.com/owen-alderson/crypto-terminal/main/docs/demo.gif)
+
+![Textual](https://img.shields.io/badge/built%20with-Textual-ffb000) ![Coinbase](https://img.shields.io/badge/data-Coinbase%20Exchange-0052FF)
+
+## Install
+
+Requires Python 3.10+.
+
+```bash
+pipx install crypto-terminal
+crypto-terminal
+```
+
+Or `pip install crypto-terminal` into any virtualenv.
+
+## Features
+
+- **Live watchlist**: last price, 24h change, and a sparkline of recent ticks. Prices flash green/red on every up/down tick.
+- **Candlestick chart** for the highlighted pair, with volume underneath. Six timeframes (1m to 1d candles). The last candle follows the live price and a new one opens at each candle boundary.
+- **Indicators**: SMA 20, EMA 50 and VWAP (resets at the UTC day) over the candles, RSI 14 in its own panel.
+- **Coin search**: `add solana` lists every online Solana pair (USD, USDC, USDT, EUR, GBP and BTC quotes first). Exact pairs like `add SOL-BTC` add directly. Sub-cent and BTC-quoted prices keep 5 significant figures.
+- **Price alerts**: on a level (`>` / `<`) or a percentage move. A firing alert rings the terminal bell, shows a toast, and sends a desktop notification (macOS, or Linux with `notify-send`). Pairs with an alert carry a 🔔.
+- **Status line**: connection state, time since the last tick, UTC clock. Shows `STALE` after 10s without data and reconnects automatically with exponential backoff.
+
+Default pairs: BTC-USD, ETH-USD, XRP-USD, SOL-USD, ADA-USD.
+
+## How live is it?
+
+Measured on the five default pairs over 60s:
+
+| | Quiet (Sunday) | Busy |
+|---|---|---|
+| Price updates | ~5.5 / s | ~12 / s |
+| Bandwidth | ~0.02 Mbps | ~0.04 Mbps |
+
+Coinbase pushes an update on every trade (bursts are batched); nothing is polled. A heartbeat arrives every second, so a dead connection is spotted and replaced within seconds. The chart redraws at most twice a second.
+
+## Keys
+
+| Key | Action |
+|---|---|
+| `↑` `↓` | Select pair (chart follows) |
+| `1` – `6` | Candles: 1m, 5m, 15m, 1h, 6h, 1d |
+| `/` or `:` | Open command bar (`esc` closes it) |
+| `ctrl+q` | Quit |
+
+## Commands
+
+| Command | Effect |
+|---|---|
+| `add SOL-USD` | Add a pair |
+| `add sol` / `add solana` | Search by symbol or name: pick with `↑` `↓`, `enter` adds, `esc` cancels |
+| `rm ADA-USD` | Remove a pair |
+| `ind sma20 ema50 vwap rsi` | Toggle indicators (any subset) |
+| `ind off` | Clear all indicators |
+| `alert BTC-USD > 90000` | Alert when the price reaches 90,000 or more (`<` for at or below) |
+| `alert BTC-USD move 5%` | Alert on a ±5% move from the current price |
+| `alerts` | List alerts with their numbers |
+| `unalert 2` | Remove alert 2 |
+| `quit` | Exit |
+
+Alerts fire once and are then removed. The watchlist, indicators and alerts are saved in `~/.config/crypto-terminal/` (or `$XDG_CONFIG_HOME/crypto-terminal/`).
+
+## From source
+
+```bash
+git clone https://github.com/owen-alderson/crypto-terminal.git
+cd crypto-terminal
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+python -m crypto_terminal
+```
+
+## Architecture
+
+```
+crypto_terminal/
+  feed.py        websocket client: subscribes to ticker + heartbeat, validates each message,
+                 reconnects with exponential backoff (1s → 30s); 30s of silence = dead socket
+  history.py     REST: candles, the product list for search, the live-candle update
+  indicators.py  SMA, EMA, RSI, VWAP as pure functions
+  alerts.py      alert rules, trigger check, desktop notification
+  widgets.py     PriceTable (watchlist), ChartPane (textual-plotext), PairPicker (search results)
+  app.py         Textual app: layout, command parsing, saved config, status line
+tests/           pytest: parsing, indicators against reference values, search, alerts, reconnect
+                 against a local websocket server, headless UI tests with Textual's Pilot (no internet)
+```
+
+The feed, the chart fetch and the product list run as Textual async workers. Changing the watchlist restarts the feed worker, and a new chart request cancels the previous one so a slow response can't draw the wrong pair.
+
+## Tests
+
+```bash
+pytest
+```
+
+## History
+
+This repo started as a Streamlit + CoinGecko portfolio dashboard that polled every 60s. That version is preserved at the `v1-streamlit` tag (`git checkout v1-streamlit`).
+
+## License
+
+MIT, see [LICENSE](LICENSE). Provided as is, with no warranty: this is a market-data viewer, not financial advice.

crypto_terminal-2.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+crypto_terminal/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+crypto_terminal/__main__.py,sha256=5S4_8qGX_RL0Tkm7RoUP6UCOGJfXmjGrjYEj4chKKvI,107
+crypto_terminal/alerts.py,sha256=6P80M6dadOfA_uBewoDPPFrG4wwIK66-Rt-iXv0YZEQ,2575
+crypto_terminal/app.py,sha256=kFYdDBE_mMO5uoH4GPyzwud-9uK3gHgj-TZX1o1VfCA,15323
+crypto_terminal/feed.py,sha256=OtFsS9fjVzBemVOnTYsF9VXWsLogvRF-0JkVOkloezM,3970
+crypto_terminal/history.py,sha256=nbru2pUhrIivdzGVJzaUNvpBvgNWonswd5ZFhW86WIs,4343
+crypto_terminal/indicators.py,sha256=yVqOi_3u0qCNlaIPLfGZ2he1V5FyHtreopeLsrtx5II,1723
+crypto_terminal/widgets.py,sha256=f6InTBNGy24HdhR3stdCknbkpDPmS1epAFWzkEQGvMw,9490
+crypto_terminal-2.0.0.dist-info/METADATA,sha256=7vLECWmNQIkKt2M59NEUIhSYRi3YwM52nO6HhTOyM7U,5562
+crypto_terminal-2.0.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+crypto_terminal-2.0.0.dist-info/entry_points.txt,sha256=9LeREDCHNMkHRIspVvAd5ZxXeXkjoeiOpt38AxMMjZI,66
+crypto_terminal-2.0.0.dist-info/licenses/LICENSE,sha256=NWajlPPoczBhh6BjoC0u7pKkymgP3ZCbpGv3dnCZ1L8,1070
+crypto_terminal-2.0.0.dist-info/RECORD,,

crypto_terminal-2.0.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

crypto_terminal-2.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+crypto-terminal = crypto_terminal.__main__:main

crypto_terminal-2.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Owen Alderson
+
+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.