trading-cli 0.3.0__py3-none-any.whl

fastbooks_cli/direct.py

@@ -0,0 +1,209 @@
+"""Standalone (backend-free) exchange access via ccxt.
+
+This module lets the CLI — and the MCP server — read public market data and place
+orders on 100+ exchanges DIRECTLY, with NO FastBooks backend running. Public data
+(tickers / ohlcv / order book / markets) needs NO API key. Trading reads per-exchange
+credentials from explicit args or the environment:
+
+    CCXT_<EXCHANGE>_API_KEY / _SECRET / _PASSWORD     (preferred)
+    <EXCHANGE>_API_KEY / _SECRET / _PASSWORD          (fallback)
+
+e.g. CCXT_BINANCE_API_KEY, CCXT_BINANCE_SECRET.
+
+ccxt is an OPTIONAL dependency — install standalone support with:
+    pip install "trading-cli[standalone]"     (or simply: pip install ccxt)
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+
+class CcxtNotInstalled(RuntimeError):
+    """Raised when a direct/standalone feature is used but ccxt isn't installed."""
+
+
+def _ccxt():
+    try:
+        import ccxt  # type: ignore
+    except ImportError as e:  # pragma: no cover - exercised only without the extra
+        raise CcxtNotInstalled(
+            "ccxt is not installed — standalone mode is unavailable. Install it with: "
+            "pip install 'trading-cli[standalone]'  (or: pip install ccxt)"
+        ) from e
+    return ccxt
+
+
+def list_exchanges() -> list[str]:
+    """Every exchange id ccxt supports (100+)."""
+    return list(_ccxt().exchanges)
+
+
+def _load_keys(
+    exchange: str,
+    api_key: str | None = None,
+    secret: str | None = None,
+    password: str | None = None,
+) -> dict[str, Any]:
+    ex = exchange.upper()
+
+    def env(*names: str) -> str | None:
+        for n in names:
+            v = os.environ.get(n)
+            if v:
+                return v
+        return None
+
+    # Precedence: explicit args > env (CCXT_<EX>_*) > the persisted config store (fastbooks init).
+    stored: dict = {}
+    try:
+        from . import config_store
+        stored = config_store.get_credentials(exchange)
+    except Exception:
+        stored = {}
+
+    api_key = api_key or env(f"CCXT_{ex}_API_KEY", f"{ex}_API_KEY") or stored.get("apiKey")
+    secret = secret or env(f"CCXT_{ex}_SECRET", f"{ex}_SECRET", f"{ex}_API_SECRET") or stored.get("secret")
+    password = password or env(f"CCXT_{ex}_PASSWORD", f"{ex}_PASSWORD", f"{ex}_PASSPHRASE") or stored.get("password")
+    cfg: dict[str, Any] = {"enableRateLimit": True}
+    if api_key:
+        cfg["apiKey"] = api_key
+    if secret:
+        cfg["secret"] = secret
+    if password:
+        cfg["password"] = password
+    return cfg
+
+
+def get_exchange(
+    exchange: str,
+    api_key: str | None = None,
+    secret: str | None = None,
+    password: str | None = None,
+    sandbox: bool = False,
+):
+    """Instantiate a ccxt exchange (keyless unless creds are supplied/in env)."""
+    ccxt = _ccxt()
+    name = exchange.lower()
+    if not hasattr(ccxt, name):
+        raise ValueError(f"Unknown exchange '{exchange}'. Run `fastbooks direct exchanges` to list.")
+    inst = getattr(ccxt, name)(_load_keys(name, api_key, secret, password))
+    if sandbox:
+        try:
+            inst.set_sandbox_mode(True)
+        except Exception:
+            pass
+    return inst
+
+
+def _has_creds(ex) -> bool:
+    return bool(getattr(ex, "apiKey", None) and getattr(ex, "secret", None))
+
+
+def _needs_key(exchange: str) -> PermissionError:
+    ex = exchange.upper()
+    return PermissionError(
+        f"No API credentials for '{exchange}'. Set CCXT_{ex}_API_KEY and CCXT_{ex}_SECRET "
+        f"(and CCXT_{ex}_PASSWORD if the exchange requires a passphrase)."
+    )
+
+
+# ── public market data (keyless) ──────────────────────────────────────────
+
+def ticker(exchange: str, symbol: str) -> dict:
+    t = get_exchange(exchange).fetch_ticker(symbol)
+    return {
+        "exchange": exchange,
+        "symbol": symbol,
+        "last": t.get("last"),
+        "bid": t.get("bid"),
+        "ask": t.get("ask"),
+        "high": t.get("high"),
+        "low": t.get("low"),
+        "baseVolume": t.get("baseVolume"),
+        "quoteVolume": t.get("quoteVolume"),
+        "changePct": t.get("percentage"),
+        "timestamp": t.get("timestamp"),
+    }
+
+
+def ohlcv(exchange: str, symbol: str, timeframe: str = "1h", limit: int = 100) -> dict:
+    ex = get_exchange(exchange)
+    if not ex.has.get("fetchOHLCV"):
+        raise ValueError(f"{exchange} does not provide OHLCV via ccxt.")
+    rows = ex.fetch_ohlcv(symbol, timeframe=timeframe, limit=limit)
+    return {
+        "exchange": exchange,
+        "symbol": symbol,
+        "timeframe": timeframe,
+        "candles": [
+            {"ts": c[0], "open": c[1], "high": c[2], "low": c[3], "close": c[4], "volume": c[5]}
+            for c in rows
+        ],
+    }
+
+
+def orderbook(exchange: str, symbol: str, depth: int = 10) -> dict:
+    ob = get_exchange(exchange).fetch_order_book(symbol, limit=depth)
+    return {
+        "exchange": exchange,
+        "symbol": symbol,
+        "bids": ob.get("bids", [])[:depth],
+        "asks": ob.get("asks", [])[:depth],
+        "timestamp": ob.get("timestamp"),
+    }
+
+
+def markets(exchange: str, quote: str | None = None, limit: int = 200) -> dict:
+    syms = list(get_exchange(exchange).load_markets().keys())
+    if quote:
+        q = quote.upper()
+        syms = [s for s in syms if s.upper().endswith(f"/{q}")]
+    return {"exchange": exchange, "count": len(syms), "symbols": sorted(syms)[:limit]}
+
+
+# ── trading (needs credentials) ───────────────────────────────────────────
+
+def balance(exchange: str, **keys) -> dict:
+    ex = get_exchange(exchange, **keys)
+    if not _has_creds(ex):
+        raise _needs_key(exchange)
+    total = {k: v for k, v in (ex.fetch_balance().get("total") or {}).items() if v}
+    return {"exchange": exchange, "balances": total}
+
+
+def positions(exchange: str, **keys) -> dict:
+    ex = get_exchange(exchange, **keys)
+    if not _has_creds(ex):
+        raise _needs_key(exchange)
+    if not ex.has.get("fetchPositions"):
+        raise ValueError(f"{exchange} does not support positions via ccxt.")
+    return {"exchange": exchange, "positions": ex.fetch_positions()}
+
+
+def place_order(
+    exchange: str,
+    symbol: str,
+    side: str,
+    order_type: str = "market",
+    amount: float = 0.0,
+    price: float | None = None,
+    sandbox: bool = False,
+    **keys,
+) -> dict:
+    ex = get_exchange(exchange, sandbox=sandbox, **keys)
+    if not _has_creds(ex):
+        raise _needs_key(exchange)
+    o = ex.create_order(symbol, order_type.lower(), side.lower(), amount, price)
+    return {
+        "exchange": exchange,
+        "id": o.get("id"),
+        "symbol": o.get("symbol"),
+        "side": o.get("side"),
+        "type": o.get("type"),
+        "amount": o.get("amount"),
+        "price": o.get("price"),
+        "status": o.get("status"),
+        "filled": o.get("filled"),
+    }

fastbooks_cli/main.py

@@ -0,0 +1,88 @@
+"""FastBooks CLI — agent-native trading interface.
+
+Following CLI-Anything methodology: structured, self-describing commands
+with dual output (JSON for agents, tables for humans).
+
+Usage:
+    fastbooks [--json] [--url URL] COMMAND [ARGS...]
+
+Examples:
+    fastbooks markets orderbook binance BTC/USDT
+    fastbooks execute order binance BTC/USDT buy market 0.01
+    fastbooks bots list
+    fastbooks backtest run --venue hyperliquid --symbols ETH/USDC --start 2025-01-01 --end 2025-03-01
+    fastbooks --json execute balance binance
+"""
+
+from __future__ import annotations
+
+import click
+
+from . import __version__
+from .client import FastBooksClient
+from .commands.markets import markets
+from .commands.execution import execute
+from .commands.bots import bots
+from .commands.backtest import backtest
+from .commands.wallet import wallet
+from .commands.config import config
+from .commands.swap import swap
+from .commands.dex import dex
+from .commands.repl import repl
+from .commands.polymarket import polymarket
+from .commands.strategy import strategy
+from .commands.apikey import apikey
+from .commands.direct import direct
+from .commands.mcp_cmd import mcp_cmd
+from .commands.onchain import onchain
+from .commands.init_cmd import init_cmd
+
+pass_client = click.make_pass_decorator(FastBooksClient)
+
+
+@click.group()
+@click.version_option(__version__, prog_name="fastbooks")
+@click.option("--json", "json_output", is_flag=True, help="Output JSON (for agents).")
+@click.option("--url", "routing_url", envvar="FASTBOOKS_ROUTING_URL", default=None, help="Routing API URL.")
+@click.option("--bots-url", envvar="FASTBOOKS_BOTS_URL", default=None, help="Bots API URL.")
+@click.option("--token", envvar="FASTBOOKS_API_TOKEN", default=None, help="JWT for authenticated routes (api-keys, saved backtests, onchain).")
+@click.option("--api-key", "api_key", envvar="FASTBOOKS_API_KEY", default=None, help="FastBooks public-API key (fb_live_...). Sent as x-api-key so your bot is metered/throttled. Mint one: `fastbooks apikey create`.")
+@click.option("--timeout", type=int, default=30, help="Request timeout in seconds.")
+@click.pass_context
+def cli(ctx: click.Context, json_output: bool, routing_url: str | None, bots_url: str | None, token: str | None, api_key: str | None, timeout: int):
+    """FastBooks CLI — trade any exchange from the command line.
+
+    Supports CEX (Binance, Bybit, OKX, Kraken, Coinbase, KuCoin),
+    perpetuals (Hyperliquid), traditional brokers (IBKR, Alpaca),
+    DEX (Jupiter, Uniswap), and prediction markets (Polymarket, Limitless).
+
+    Use --json for machine-readable output suitable for AI agents.
+    """
+    ctx.ensure_object(dict)
+    ctx.obj = FastBooksClient(routing_url=routing_url, bots_url=bots_url, timeout=timeout, token=token, api_key=api_key)
+
+
+cli.add_command(markets)
+cli.add_command(execute)
+cli.add_command(bots)
+cli.add_command(backtest)
+cli.add_command(wallet)
+cli.add_command(config)
+cli.add_command(swap)
+cli.add_command(dex)
+cli.add_command(repl)
+cli.add_command(polymarket)
+cli.add_command(strategy)
+cli.add_command(apikey)
+cli.add_command(init_cmd)
+cli.add_command(direct)
+cli.add_command(mcp_cmd)
+cli.add_command(onchain)
+
+
+def main():
+    cli()
+
+
+if __name__ == "__main__":
+    main()

fastbooks_cli/mcp_server.py

@@ -0,0 +1,171 @@
+"""FastBooks MCP server — exposes the CLI's capabilities as agent-callable tools.
+
+Two tiers of tools:
+  • STANDALONE (ccxt): market data + trading on 100+ exchanges with NO backend.
+    Public data is keyless; trading reads CCXT_<EXCHANGE>_API_KEY/_SECRET/_PASSWORD from env.
+  • PLATFORM (FastBooks backend): aggregated multi-asset data, the 15-venue execution
+    layer (stocks/forex/prediction/perps), and managed bots — used when a backend is reachable
+    (FASTBOOKS_ROUTING_URL / FASTBOOKS_BOTS_URL, default localhost:3002/8003). These degrade to
+    a structured {"error": ...} when the backend is down, so the server never crashes.
+
+Run:  fastbooks-mcp   (or:  fastbooks mcp)   — speaks MCP over stdio.
+Requires:  pip install "trading-cli[mcp]"   (and [standalone] for the ccxt tools).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from . import direct as d
+from .client import FastBooksClient
+
+
+def _safe(fn):
+    """Wrap a tool body so backend/network errors return structured JSON, not a crash."""
+    try:
+        return fn()
+    except Exception as e:  # noqa: BLE001
+        return {"error": str(e), "type": e.__class__.__name__}
+
+
+def build_server():
+    try:
+        from mcp.server.fastmcp import FastMCP
+    except ImportError as e:  # pragma: no cover
+        raise RuntimeError(
+            "MCP SDK not installed. Install with: pip install 'trading-cli[mcp]'"
+        ) from e
+
+    mcp = FastMCP("fastbooks")
+
+    # ── STANDALONE (ccxt) — no backend needed ────────────────────────────
+
+    @mcp.tool()
+    def list_exchanges(search: str = "") -> dict:
+        """List the 100+ exchanges available for standalone (backend-free) data & trading. Optional substring filter."""
+        return _safe(lambda: (lambda xs: {"count": len(xs), "exchanges": xs})(
+            [x for x in d.list_exchanges() if not search or search.lower() in x.lower()]
+        ))
+
+    @mcp.tool()
+    def get_ticker(exchange: str, symbol: str) -> dict:
+        """Live ticker for a symbol on any ccxt exchange (keyless). e.g. exchange='binance', symbol='BTC/USDT'."""
+        return _safe(lambda: d.ticker(exchange, symbol))
+
+    @mcp.tool()
+    def get_ohlcv(exchange: str, symbol: str, timeframe: str = "1h", limit: int = 100) -> dict:
+        """OHLCV candles for a symbol (keyless). timeframe e.g. 1m,5m,15m,1h,4h,1d."""
+        return _safe(lambda: d.ohlcv(exchange, symbol, timeframe, limit))
+
+    @mcp.tool()
+    def get_orderbook(exchange: str, symbol: str, depth: int = 10) -> dict:
+        """Order book (bids/asks) for a symbol on any exchange (keyless)."""
+        return _safe(lambda: d.orderbook(exchange, symbol, depth))
+
+    @mcp.tool()
+    def get_markets(exchange: str, quote: str = "", limit: int = 200) -> dict:
+        """List tradable symbols on an exchange (keyless). Optional quote-asset filter (e.g. 'USDT')."""
+        return _safe(lambda: d.markets(exchange, quote or None, limit))
+
+    @mcp.tool()
+    def get_balance(exchange: str) -> dict:
+        """Account balance on an exchange. Needs CCXT_<EXCHANGE>_API_KEY/_SECRET in the server's env."""
+        return _safe(lambda: d.balance(exchange))
+
+    @mcp.tool()
+    def place_order(exchange: str, symbol: str, side: str, order_type: str = "market",
+                    amount: float = 0.0, price: float | None = None, sandbox: bool = False) -> dict:
+        """Place an order DIRECTLY on an exchange via ccxt (needs CCXT_<EXCHANGE>_* creds). side=buy|sell, order_type=market|limit. sandbox=true uses testnet where supported."""
+        return _safe(lambda: d.place_order(exchange, symbol, side, order_type, amount, price, sandbox=sandbox))
+
+    # ── PLATFORM (FastBooks backend) — richer venues/assets when reachable ─
+
+    def _client() -> FastBooksClient:
+        return FastBooksClient()
+
+    @mcp.tool()
+    def platform_venues() -> Any:
+        """FastBooks execution venues (Hyperliquid perps, Alpaca/IBKR stocks, OANDA/Saxo forex, Polymarket prediction, CEXs, paper). Requires the FastBooks backend."""
+        return _safe(lambda: _client().venues())
+
+    @mcp.tool()
+    def platform_tickers(limit: int = 50, category: str = "", search: str = "") -> Any:
+        """FastBooks aggregated tickers across ALL asset classes (crypto, stocks, forex, index, commodities, dex, prediction). Requires the backend. category e.g. crypto|stock|forex|prediction."""
+        return _safe(lambda: _client().tickers(limit=limit, category=category or None, search=search or None))
+
+    @mcp.tool()
+    def platform_place_order(venue: str, symbol: str, side: str, order_type: str = "market",
+                             amount: float = 0.0, price: float | None = None) -> Any:
+        """Place an order via the FastBooks execution layer (stocks/forex/prediction/perps across 15 venues). Requires the backend + configured keys. Use venue='paper' for KEYLESS simulation."""
+        return _safe(lambda: _client().place_order(venue, symbol, side, order_type, amount, price))
+
+    @mcp.tool()
+    def platform_balance(venue: str) -> Any:
+        """Balance on a FastBooks venue. Requires the backend."""
+        return _safe(lambda: _client().balance(venue))
+
+    @mcp.tool()
+    def platform_positions(venue: str) -> Any:
+        """Open positions on a FastBooks venue. Requires the backend."""
+        return _safe(lambda: _client().positions(venue))
+
+    @mcp.tool()
+    def platform_paper_init(balance: float = 10000.0) -> Any:
+        """Initialize a KEYLESS paper-trading account on the FastBooks backend (no exchange keys needed)."""
+        return _safe(lambda: _client().paper_init(balance=balance))
+
+    @mcp.tool()
+    def list_bots() -> Any:
+        """List FastBooks managed trading bots. Requires the bots service (:8003)."""
+        return _safe(lambda: _client().list_bots())
+
+    @mcp.tool()
+    def create_public_api_key(label: str = "mcp-agent") -> Any:
+        """Self-service mint a free read-only FastBooks public-API key (fb_live_...). Set it as FASTBOOKS_API_KEY so this agent is metered/throttled per key on platform data. Requires the backend."""
+        return _safe(lambda: _client().create_fastbooks_api_key(label))
+
+    # ── FastBots ON-CHAIN (Solana/EVM engine via /api/onchain) ──────────
+    # Needs FASTBOOKS_API_TOKEN (a JWT on the engine's email allowlist) in the server env.
+
+    @mcp.tool()
+    def onchain_status() -> Any:
+        """Live status of on-chain (Solana/EVM) bots — which are running. Requires backend + JWT."""
+        return _safe(lambda: _client().onchain_live_status())
+
+    @mcp.tool()
+    def onchain_stats(by_bot: bool = False) -> Any:
+        """Realized PnL / win-rate for on-chain bots (per-bot if by_bot=true). Requires backend + JWT."""
+        return _safe(lambda: _client().onchain_stats(by_bot=by_bot))
+
+    @mcp.tool()
+    def onchain_strategies() -> Any:
+        """List deployable on-chain strategies + params. Requires backend + JWT."""
+        return _safe(lambda: _client().onchain_strategies())
+
+    @mcp.tool()
+    def onchain_start(strategy_id: str, alloc_sol: float | None = None,
+                      slippage_bps: int | None = None, max_safety_risk: int | None = None) -> Any:
+        """Start a LIVE on-chain bot (REAL funds) on the Solana/EVM engine. Requires backend + JWT. alloc_sol=maxAllocationSol; max_safety_risk=40 allows the caution band."""
+        opts: dict = {}
+        if alloc_sol is not None:
+            opts["maxAllocationSol"] = alloc_sol
+        if slippage_bps is not None:
+            opts["realSlippageBps"] = slippage_bps
+        if max_safety_risk is not None:
+            opts["maxSafetyRisk"] = max_safety_risk
+        return _safe(lambda: _client().onchain_live_start(strategy_id, opts))
+
+    @mcp.tool()
+    def onchain_stop(strategy_id: str) -> Any:
+        """Stop a live on-chain bot. Requires backend + JWT."""
+        return _safe(lambda: _client().onchain_live_stop(strategy_id))
+
+    return mcp
+
+
+def main():
+    build_server().run()
+
+
+if __name__ == "__main__":
+    main()

fastbooks_cli/output.py

@@ -0,0 +1,86 @@
+"""Dual output formatter — JSON for agents, rich tables for humans."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from typing import Any
+
+import click
+
+
+def require_experimental(ctx: click.Context, group: str) -> None:
+    """Gate an experimental command group behind FASTBOOKS_EXPERIMENTAL=1.
+
+    These groups call backend routers that are NOT enabled on standard FastBooks
+    deployments, so by default we refuse with a clear message instead of emitting
+    a confusing connection/404 error. Showing `--help` (no subcommand) is allowed.
+    """
+    if ctx.invoked_subcommand is None:
+        return  # `fastbooks <group>` / `--help` — let Click show help
+    if os.environ.get("FASTBOOKS_EXPERIMENTAL", "").lower() in ("1", "true", "yes"):
+        return
+    emit_error(
+        ctx,
+        f"`{group}` is experimental and disabled. It requires the {group} backend "
+        f"router, which is not enabled on standard FastBooks deployments. "
+        f"Set FASTBOOKS_EXPERIMENTAL=1 to enable it anyway.",
+    )
+    ctx.exit(2)
+
+
+def _is_json_mode(ctx: click.Context) -> bool:
+    """Check if --json flag was passed at the root level."""
+    root = ctx.find_root()
+    return root.params.get("json_output", False)
+
+
+def emit(ctx: click.Context, data: Any, human_formatter=None) -> None:
+    """Emit data in JSON or human-readable format.
+
+    Args:
+        ctx: Click context (used to check --json flag).
+        data: The data payload (dict, list, or primitive).
+        human_formatter: Optional callable(data) -> str for human output.
+            If None, falls back to pretty-printed JSON.
+    """
+    if _is_json_mode(ctx):
+        click.echo(json.dumps(data, indent=2, default=str))
+    elif human_formatter:
+        click.echo(human_formatter(data))
+    else:
+        click.echo(json.dumps(data, indent=2, default=str))
+
+
+def emit_error(ctx: click.Context, message: str, details: Any = None) -> None:
+    """Emit an error in JSON or human format."""
+    if _is_json_mode(ctx):
+        err = {"error": message}
+        if details:
+            err["details"] = details
+        click.echo(json.dumps(err, indent=2, default=str), err=True)
+    else:
+        click.secho(f"Error: {message}", fg="red", err=True)
+        if details:
+            click.echo(str(details), err=True)
+
+
+def format_table(rows: list[dict], columns: list[str], headers: list[str] | None = None) -> str:
+    """Format a list of dicts as an aligned text table."""
+    if not rows:
+        return "(no data)"
+    hdrs = headers or columns
+    col_widths = [len(h) for h in hdrs]
+    str_rows = []
+    for row in rows:
+        vals = [str(row.get(c, "")) for c in columns]
+        str_rows.append(vals)
+        for i, v in enumerate(vals):
+            col_widths[i] = max(col_widths[i], len(v))
+
+    fmt = "  ".join(f"{{:<{w}}}" for w in col_widths)
+    lines = [fmt.format(*hdrs), fmt.format(*("-" * w for w in col_widths))]
+    for vals in str_rows:
+        lines.append(fmt.format(*vals))
+    return "\n".join(lines)

fastbooks_cli/strategies/__init__.py

@@ -0,0 +1,87 @@
+"""Local trading strategy registry (loader only — no strategies bundled here).
+
+Strategies are shipped as SEPARATE, optionally-installed packages so the
+open-source CLI contains the runner but not the trading logic. A strategy
+provider exposes:
+
+    STRATEGIES = [ { module, name, slug, description, venue,
+                     required_keys, optional_keys }, ... ]
+
+and each referenced ``module`` exposes ``run(cfg)`` (async) plus
+``NAME``/``DESCRIPTION``/``VENUE``/``REQUIRED_KEYS``/``OPTIONAL_KEYS``.
+
+Discovery order:
+  1. `fastbooks_cli.strategies` entry points (installed plugins) — zero config.
+  2. Fallback: a top-level ``clistrategies`` package on the path.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, fields
+from typing import Dict, List
+
+
+@dataclass
+class StrategyMeta:
+    """Lightweight descriptor — no heavy imports."""
+    module: str          # e.g. "clistrategies.hl_momentum_hunter"
+    name: str            # human name
+    slug: str            # CLI identifier (lowercase, hyphens)
+    description: str
+    venue: str
+    required_keys: List[str]
+    optional_keys: List[str]
+
+
+REGISTRY: Dict[str, StrategyMeta] = {}
+
+_META_FIELDS = {f.name for f in fields(StrategyMeta)}
+
+
+def _register(meta: StrategyMeta) -> None:
+    REGISTRY[meta.slug] = meta
+
+
+def _register_from_dicts(items) -> None:
+    for d in items or []:
+        try:
+            meta = StrategyMeta(**{k: v for k, v in d.items() if k in _META_FIELDS})
+        except TypeError:
+            continue  # skip malformed descriptors rather than crash the CLI
+        _register(meta)
+
+
+def _discover() -> None:
+    """Populate REGISTRY from installed strategy plugins. Best-effort, never raises."""
+    found = False
+
+    # 1. Entry points advertised by installed plugin packages.
+    try:
+        from importlib.metadata import entry_points
+
+        eps = entry_points()
+        group = (
+            eps.select(group="fastbooks_cli.strategies")
+            if hasattr(eps, "select")
+            else eps.get("fastbooks_cli.strategies", [])  # py3.9 shim
+        )
+        for ep in group:
+            try:
+                provider = ep.load()
+            except Exception:
+                continue
+            _register_from_dicts(getattr(provider, "STRATEGIES", None))
+            found = True
+    except Exception:
+        pass
+
+    # 2. Fallback: a top-level `clistrategies` package on PYTHONPATH.
+    if not found and not REGISTRY:
+        try:
+            import clistrategies  # type: ignore
+            _register_from_dicts(getattr(clistrategies, "STRATEGIES", None))
+        except Exception:
+            pass
+
+
+_discover()