trading-cli 0.3.0__py3-none-any.whl

fastbooks_cli/commands/apikey.py

@@ -0,0 +1,144 @@
+"""FastBooks platform API-key command group — fully self-service.
+
+These are the keys that authenticate the FastBooks PUBLIC API (/api/public/v1),
+NOT exchange credentials (see `fastbooks wallet add` for those).
+
+Everything here is self-service — no admin token, ever. Anyone can create a
+key; you manage (inspect/revoke) a key by presenting the key itself.
+"""
+
+from __future__ import annotations
+
+import click
+
+from ..client import FastBooksClient
+from ..output import emit, emit_error, format_table
+
+
+@click.group()
+def apikey():
+    """Create and manage FastBooks platform API keys (public API access).
+
+    Self-service: no admin token. Each key is free, read-only, and rate-limited
+    to 5 requests/second. Manage a key by presenting the key itself.
+    """
+    pass
+
+
+@apikey.command()
+@click.option("--label", "-l", required=True, help="Human-readable label for the key.")
+@click.option("--user-id", default=None, help="Optional owner id (defaults to an anonymous id).")
+@click.option("--email", default=None, help="Optional owner email.")
+@click.pass_context
+def create(ctx, label, user_id, email):
+    """Create a new FastBooks API key (self-service, no admin token).
+
+    Example:
+        fastbooks apikey create --label "my-bot"
+    """
+    client: FastBooksClient = ctx.obj
+    try:
+        data = client.create_fastbooks_api_key(label=label, user_id=user_id, email=email)
+        emit(ctx, data, lambda d: _format_created(d))
+    except Exception as e:
+        emit_error(ctx, str(e))
+        ctx.exit(1)
+
+
+def _format_created(d: dict) -> str:
+    key = d.get("apiKey") or d.get("key") or d.get("plaintextKey") or "?"
+    kid = d.get("id") or d.get("keyId") or "?"
+    rate = d.get("rateLimitPerSecond")
+    rate_line = f"\n  limit: {rate} req/sec" if rate else ""
+    return (
+        f"  FastBooks API key created.\n"
+        f"  id:  {kid}\n"
+        f"  key: {key}{rate_line}\n"
+        f"  (store it now — the plaintext key is not retrievable later)"
+    )
+
+
+@apikey.command("limits")
+@click.pass_context
+def limits(ctx):
+    """Show the default self-service key limits."""
+    client: FastBooksClient = ctx.obj
+    try:
+        data = client.fastbooks_api_key_limits()
+        emit(ctx, data, lambda d: f"  Plan: {d.get('plan')} · {d.get('rateLimitPerSecond')} req/sec · {d.get('scope')}")
+    except Exception as e:
+        emit_error(ctx, str(e))
+        ctx.exit(1)
+
+
+@apikey.command()
+@click.argument("api_key")
+@click.option("--category", default=None, help="Filter markets by category.")
+@click.pass_context
+def verify(ctx, api_key, category):
+    """Verify a FastBooks API key by fetching public market data with it.
+
+    Example:
+        fastbooks apikey verify fb_live_xxx --category crypto
+    """
+    client: FastBooksClient = ctx.obj
+    try:
+        data = client.public_markets(api_key, category=category)
+        emit(ctx, data, lambda d: _format_verify(d))
+    except Exception as e:
+        emit_error(ctx, str(e))
+        ctx.exit(1)
+
+
+def _format_verify(d: dict) -> str:
+    items = d.get("markets", d.get("data", [])) if isinstance(d, dict) else d
+    n = len(items) if isinstance(items, list) else d.get("total", "?")
+    return f"  Key valid — public API returned {n} markets."
+
+
+@apikey.command()
+@click.argument("api_key")
+@click.pass_context
+def info(ctx, api_key):
+    """Show a key's own details (plan, limits, scopes). Self-service.
+
+    Example:
+        fastbooks apikey info fb_live_xxx
+    """
+    client: FastBooksClient = ctx.obj
+    try:
+        data = client.fastbooks_api_key_info(api_key)
+        emit(ctx, data, lambda d: _format_info(d))
+    except Exception as e:
+        emit_error(ctx, str(e))
+        ctx.exit(1)
+
+
+def _format_info(d: dict) -> str:
+    return (
+        f"  id:    {d.get('id', '?')}\n"
+        f"  plan:  {d.get('plan', '?')}\n"
+        f"  limit: {d.get('rateLimitPerSecond', '?')} req/sec "
+        f"({d.get('rateLimitPerMinute', '?')}/min)"
+    )
+
+
+@apikey.command()
+@click.argument("api_key")
+@click.option("--confirm", is_flag=True, help="Skip the confirmation prompt.")
+@click.pass_context
+def revoke(ctx, api_key, confirm):
+    """Revoke a key by presenting it. Self-service — no admin token.
+
+    Example:
+        fastbooks apikey revoke fb_live_xxx
+    """
+    if not confirm and not click.confirm("Revoke this API key? This cannot be undone."):
+        ctx.exit(0)
+    client: FastBooksClient = ctx.obj
+    try:
+        data = client.revoke_fastbooks_api_key(api_key)
+        emit(ctx, data, lambda d: "  Key revoked." if d.get("revoked") else f"  {d}")
+    except Exception as e:
+        emit_error(ctx, str(e))
+        ctx.exit(1)

fastbooks_cli/commands/backtest.py

@@ -0,0 +1,450 @@
+"""Backtest command group — run and manage backtests across venues.
+
+Supports the full bot configuration from the investor dashboard frontend:
+sleeves, risk controls, trading options, and exchange-specific parameters.
+"""
+
+from __future__ import annotations
+
+import json
+
+import click
+
+from ..client import FastBooksClient
+from ..output import emit, emit_error, format_table
+
+VENUES = ["binance", "bybit", "hyperliquid", "alpaca", "ibkr", "okx"]
+BARS = ["1m", "5m", "15m", "1h", "4h", "1d"]
+REBALANCE_FREQ = ["daily", "weekly", "monthly"]
+CURRENCIES = ["USD", "CAD"]
+SLEEVE_TYPES = [
+    "dividend_stocks", "cash_reserve", "momentum",
+    "sector_focus", "hold_accumulate", "custom",
+]
+
+
+@click.group()
+def backtest():
+    """Backtesting: run historical simulations across any venue.
+
+    Supports real data backtests (Alpaca, Hyperliquid) and simulated
+    backtests with synthetic OHLCV for rapid prototyping.
+
+    The ``run`` command accepts the same full bot configuration as the
+    investor dashboard frontend (sleeves, risk controls, etc.).
+    """
+    pass
+
+
+# ══════════════════════════════════════════════════════════════════════════
+# run
+# ══════════════════════════════════════════════════════════════════════════
+
+@backtest.command()
+# ── data source ──────────────────────────────────────────────────────
+@click.option("--venue", "-v", type=click.Choice(VENUES, case_sensitive=False), required=True, help="Data/execution venue.")
+@click.option("--symbols", "-s", type=str, required=True, help="Comma-separated symbols (e.g. BTC/USDT,ETH/USDT or AAPL,MSFT).")
+@click.option("--start", required=True, help="Start date (YYYY-MM-DD).")
+@click.option("--end", required=True, help="End date (YYYY-MM-DD).")
+@click.option("--bar", "-b", type=click.Choice(BARS), default="1h", help="Bar/candle size.")
+# ── capital ──────────────────────────────────────────────────────────
+@click.option("--capital", "-c", type=float, default=50000.0, help="Total allocated capital.")
+@click.option("--currency", type=click.Choice(CURRENCIES, case_sensitive=False), default="USD", help="Quote currency.")
+# ── strategy sleeves ─────────────────────────────────────────────────
+@click.option(
+    "--sleeves", type=str, default=None,
+    help=(
+        "Sleeve allocations as JSON array. Each element: "
+        '{"sleeve_type":"momentum","name":"My Momentum","target_percent":30,'
+        '"drift_threshold":5,"min_trade_value":500,"config":{}}. '
+        "Target percents must total 100."
+    ),
+)
+@click.option(
+    "--sleeve", multiple=True,
+    help=(
+        "Quick sleeve shorthand (repeatable): TYPE:PERCENT[:NAME]. "
+        "e.g. --sleeve momentum:30 --sleeve dividend_stocks:40 "
+        "--sleeve cash_reserve:10 --sleeve hold_accumulate:20"
+    ),
+)
+# ── risk controls ────────────────────────────────────────────────────
+@click.option("--max-position-size", type=float, default=10.0, help="Max single position as %% of capital (default 10).")
+@click.option("--max-daily-loss", type=float, default=None, help="Max daily loss in $ before pausing (default 5%% of capital).")
+@click.option("--conviction-threshold", type=float, default=60.0, help="Minimum conviction score 0-100 (default 60).")
+# ── trading options ──────────────────────────────────────────────────
+@click.option("--paper/--live", "is_paper_trading", default=True, help="Paper or live trading mode (default: paper).")
+@click.option("--market-hours-only/--anytime", default=True, help="Only trade during market hours (default: yes).")
+@click.option("--auto-rebalance/--no-auto-rebalance", default=True, help="Auto-rebalance when drift exceeds threshold (default: yes).")
+# ── backtest-specific ────────────────────────────────────────────────
+@click.option("--rebalance", "-r", type=click.Choice(REBALANCE_FREQ), default="daily", help="Rebalance frequency.")
+@click.option("--topk", "-k", type=int, default=10, help="Top K symbols to hold per sleeve.")
+@click.option("--slippage", type=float, default=0.001, help="Slippage factor (0.001 = 0.1%%).")
+@click.option("--commission", type=float, default=0.001, help="Commission rate per trade.")
+# ── full config override ─────────────────────────────────────────────
+@click.option("--config-json", type=str, default=None, help="Full config as JSON (overrides all other options).")
+@click.option("--config-file", type=click.Path(exists=True), default=None, help="Load config from JSON file.")
+# ── bot name / description ───────────────────────────────────────────
+@click.option("--name", "-n", type=str, default=None, help="Backtest name (for saved results).")
+@click.option("--description", type=str, default=None, help="Backtest description.")
+@click.pass_context
+def run(
+    ctx, venue, symbols, start, end, bar,
+    capital, currency,
+    sleeves, sleeve,
+    max_position_size, max_daily_loss, conviction_threshold,
+    is_paper_trading, market_hours_only, auto_rebalance,
+    rebalance, topk, slippage, commission,
+    config_json, config_file,
+    name, description,
+):
+    """Run a backtest with historical data and full bot configuration.
+
+    Accepts the same parameters as the investor dashboard bot creation form:
+    capital allocation, strategy sleeves, risk controls, and trading options.
+
+    \b
+    SLEEVE SHORTHAND (--sleeve, repeatable):
+        --sleeve momentum:30 --sleeve dividend_stocks:40
+        --sleeve cash_reserve:10 --sleeve hold_accumulate:20
+
+    \b
+    SLEEVE JSON (--sleeves):
+        --sleeves '[{"sleeve_type":"momentum","target_percent":50,...}]'
+
+    \b
+    FULL CONFIG (--config-json or --config-file):
+        --config-json '{"allocated_capital":100000,"sleeves":[...]}'
+        --config-file my_bot_config.json
+
+    Examples:
+        # Quick: momentum + dividend on IBKR stocks
+        fastbooks backtest run --venue ibkr --symbols AAPL,MSFT,GOOGL \\
+            --start 2024-01-01 --end 2024-12-31 -c 50000 \\
+            --sleeve momentum:40 --sleeve dividend_stocks:40 \\
+            --sleeve cash_reserve:20 --conviction-threshold 65
+
+        # Crypto backtest with custom risk
+        fastbooks backtest run --venue hyperliquid --symbols ETH/USDC,BTC/USDC \\
+            --start 2025-01-01 --end 2025-03-01 -c 10000 \\
+            --max-position-size 20 --max-daily-loss 500
+
+        # From saved config file (same format as frontend export)
+        fastbooks backtest run --venue alpaca --symbols AAPL,TSLA \\
+            --start 2024-06-01 --end 2025-01-01 --config-file bot_config.json
+
+        # Simple (backward-compatible)
+        fastbooks backtest run --venue binance --symbols BTC/USDT \\
+            --start 2025-01-01 --end 2025-02-01 -b 1d -c 10000
+    """
+    client: FastBooksClient = ctx.obj
+
+    # Start with full override if provided
+    if config_json:
+        try:
+            config = json.loads(config_json)
+        except json.JSONDecodeError as e:
+            emit_error(ctx, f"Invalid JSON: {e}")
+            ctx.exit(1)
+            return
+    elif config_file:
+        try:
+            with open(config_file) as f:
+                config = json.load(f)
+        except (json.JSONDecodeError, OSError) as e:
+            emit_error(ctx, f"Config file error: {e}")
+            ctx.exit(1)
+            return
+    else:
+        config = {}
+
+    # Build sleeves from --sleeve shorthand or --sleeves JSON
+    built_sleeves = config.get("sleeves")
+    if sleeves and not built_sleeves:
+        try:
+            built_sleeves = json.loads(sleeves)
+        except json.JSONDecodeError as e:
+            emit_error(ctx, f"Invalid --sleeves JSON: {e}")
+            ctx.exit(1)
+            return
+    elif sleeve and not built_sleeves:
+        built_sleeves = _parse_sleeve_shorthand(sleeve)
+        if isinstance(built_sleeves, str):  # error message
+            emit_error(ctx, built_sleeves)
+            ctx.exit(1)
+            return
+
+    # Validate sleeve totals
+    if built_sleeves:
+        total = sum(s.get("target_percent", 0) for s in built_sleeves)
+        if abs(total - 100) > 0.01:
+            emit_error(ctx, f"Sleeve target_percent must total 100 (got {total:.1f}).")
+            ctx.exit(1)
+            return
+
+    # Merge everything — CLI flags fill in what config doesn't have
+    symbols_list = [s.strip() for s in symbols.split(",")]
+
+    if max_daily_loss is None:
+        max_daily_loss = capital * 0.05  # Default: 5% of capital
+
+    final = {
+        # Data source
+        "venue": config.get("venue", venue),
+        "symbols": config.get("symbols", symbols_list),
+        "start": config.get("start", start),
+        "end": config.get("end", end),
+        "bar": config.get("bar", bar),
+        # Capital (matches frontend BotConfig)
+        "allocated_capital": config.get("allocated_capital", capital),
+        "currency": config.get("currency", currency),
+        # Sleeves (matches frontend SleeveConfig[])
+        "sleeves": built_sleeves or config.get("sleeves", _default_sleeves()),
+        # Risk controls (matches frontend BotConfig)
+        "max_position_size": config.get("max_position_size", max_position_size),
+        "max_daily_loss": config.get("max_daily_loss", max_daily_loss),
+        "conviction_threshold": config.get("conviction_threshold", conviction_threshold),
+        # Trading options (matches frontend BotConfig)
+        "is_paper_trading": config.get("is_paper_trading", is_paper_trading),
+        "market_hours_only": config.get("market_hours_only", market_hours_only),
+        "auto_rebalance": config.get("auto_rebalance", auto_rebalance),
+        # Backtest-specific
+        "rebalance": config.get("rebalance", rebalance),
+        "topk": config.get("topk", topk),
+        "slippage": config.get("slippage", slippage),
+        "commission": config.get("commission", commission),
+        # Backward compat alias
+        "cash": config.get("cash", capital),
+    }
+
+    if name:
+        final["name"] = name
+    elif config.get("name"):
+        final["name"] = config["name"]
+
+    if description:
+        final["description"] = description
+    elif config.get("description"):
+        final["description"] = config["description"]
+
+    try:
+        data = client.run_backtest(final)
+        emit(ctx, data, lambda d: _format_backtest_result(d))
+    except Exception as e:
+        emit_error(ctx, str(e))
+        ctx.exit(1)
+
+
+# ── sleeve helpers ───────────────────────────────────────────────────────
+
+def _parse_sleeve_shorthand(items: tuple) -> list | str:
+    """Parse --sleeve TYPE:PERCENT[:NAME] tuples into SleeveConfig dicts."""
+    result = []
+    for item in items:
+        parts = item.split(":", 2)
+        if len(parts) < 2:
+            return f"Invalid sleeve format: '{item}'. Use TYPE:PERCENT[:NAME]."
+
+        sleeve_type = parts[0].strip()
+        if sleeve_type not in SLEEVE_TYPES:
+            return (
+                f"Unknown sleeve type: '{sleeve_type}'. "
+                f"Valid: {', '.join(SLEEVE_TYPES)}"
+            )
+
+        try:
+            pct = float(parts[1])
+        except ValueError:
+            return f"Invalid percent in sleeve '{item}': '{parts[1]}'."
+
+        name = parts[2].strip() if len(parts) > 2 else _sleeve_display_name(sleeve_type)
+
+        result.append({
+            "sleeve_type": sleeve_type,
+            "name": name,
+            "target_percent": pct,
+            "drift_threshold": 5,
+            "min_trade_value": 0 if sleeve_type == "cash_reserve" else 500,
+            "config": {},
+        })
+    return result
+
+
+def _sleeve_display_name(sleeve_type: str) -> str:
+    return {
+        "dividend_stocks": "Dividend Stocks",
+        "cash_reserve": "Cash Reserve",
+        "momentum": "Momentum",
+        "sector_focus": "Sector Focus",
+        "hold_accumulate": "Hold & Accumulate",
+        "custom": "Custom",
+    }.get(sleeve_type, sleeve_type)
+
+
+def _default_sleeves() -> list:
+    """Match the frontend's default sleeve allocation."""
+    return [
+        {"sleeve_type": "dividend_stocks", "name": "Dividend Stocks", "target_percent": 30, "drift_threshold": 5, "min_trade_value": 500, "config": {}},
+        {"sleeve_type": "cash_reserve", "name": "Cash Reserve", "target_percent": 10, "drift_threshold": 5, "min_trade_value": 0, "config": {}},
+        {"sleeve_type": "momentum", "name": "Momentum", "target_percent": 20, "drift_threshold": 5, "min_trade_value": 500, "config": {}},
+        {"sleeve_type": "sector_focus", "name": "Sector Focus", "target_percent": 20, "drift_threshold": 5, "min_trade_value": 500, "config": {}},
+        {"sleeve_type": "hold_accumulate", "name": "Hold & Accumulate", "target_percent": 20, "drift_threshold": 5, "min_trade_value": 500, "config": {}},
+    ]
+
+
+# ── formatters ───────────────────────────────────────────────────────────
+
+def _format_backtest_result(data: dict) -> str:
+    lines = ["", "  Backtest Results", "  ================"]
+    metrics = data.get("metrics", data)
+    if isinstance(metrics, dict):
+        for key in [
+            "total_return", "sharpe_ratio", "max_drawdown", "win_rate",
+            "total_trades", "final_equity", "allocated_capital",
+            "conviction_threshold", "sleeves_count",
+        ]:
+            if key in metrics:
+                label = key.replace("_", " ").title()
+                lines.append(f"  {label}: {metrics[key]}")
+
+    # Sleeve breakdown if available
+    sleeve_results = data.get("sleeve_results", [])
+    if sleeve_results:
+        lines.append("")
+        lines.append("  Per-Sleeve Breakdown")
+        lines.append("  --------------------")
+        for sr in sleeve_results:
+            name = sr.get("name", sr.get("sleeve_type", "?"))
+            ret = sr.get("return", sr.get("total_return", "?"))
+            alloc = sr.get("target_percent", "?")
+            lines.append(f"  {name} ({alloc}%): {ret}")
+
+    if not isinstance(metrics, dict) and not sleeve_results:
+        lines.append(f"  {data}")
+    return "\n".join(lines)
+
+
+# ══════════════════════════════════════════════════════════════════════════
+# forward test
+# ══════════════════════════════════════════════════════════════════════════
+
+@backtest.command("forward-test")
+@click.option("--venue", "-v", type=click.Choice(VENUES, case_sensitive=False), required=True)
+@click.option("--asset-type", type=click.Choice(["stock", "crypto"]), default="stock")
+@click.option("--capital", "-c", type=float, default=50000.0, help="Cash allocation.")
+@click.option("--currency", type=click.Choice(CURRENCIES, case_sensitive=False), default="USD")
+@click.option("--max-symbols", type=int, default=20, help="Max symbols in universe.")
+@click.option("--topk", "-k", type=int, default=10, help="Top K to hold.")
+# ── same bot config params ───────────────────────────────────────────
+@click.option("--sleeve", multiple=True, help="Sleeve shorthand (repeatable): TYPE:PERCENT[:NAME].")
+@click.option("--max-position-size", type=float, default=10.0, help="Max position as %% of capital.")
+@click.option("--max-daily-loss", type=float, default=None, help="Max daily loss in $.")
+@click.option("--conviction-threshold", type=float, default=60.0, help="Min conviction score 0-100.")
+@click.option("--paper/--live", "is_paper_trading", default=True, help="Paper or live mode.")
+@click.option("--market-hours-only/--anytime", default=True)
+@click.option("--auto-rebalance/--no-auto-rebalance", default=True)
+@click.pass_context
+def forward_test(
+    ctx, venue, asset_type, capital, currency, max_symbols, topk,
+    sleeve, max_position_size, max_daily_loss, conviction_threshold,
+    is_paper_trading, market_hours_only, auto_rebalance,
+):
+    """Run a single-cycle forward test (no historical data needed).
+
+    Executes one rebalance cycle with live market data to validate strategy.
+    Accepts the same bot configuration params as ``backtest run``.
+
+    Examples:
+        fastbooks backtest forward-test --venue alpaca --capital 50000 \\
+            --sleeve momentum:40 --sleeve dividend_stocks:40 --sleeve cash_reserve:20
+
+        fastbooks backtest forward-test --venue hyperliquid --asset-type crypto \\
+            --currency USD --conviction-threshold 70
+    """
+    client: FastBooksClient = ctx.obj
+
+    # Parse sleeves
+    built_sleeves = None
+    if sleeve:
+        built_sleeves = _parse_sleeve_shorthand(sleeve)
+        if isinstance(built_sleeves, str):
+            emit_error(ctx, built_sleeves)
+            ctx.exit(1)
+            return
+
+    if max_daily_loss is None:
+        max_daily_loss = capital * 0.05
+
+    config = {
+        "venue": venue,
+        "asset_type": asset_type,
+        "allocated_capital": capital,
+        "currency": currency,
+        "cash": capital,
+        "quote": currency,
+        "max_symbols": max_symbols,
+        "topk": topk,
+        "sleeves": built_sleeves or _default_sleeves(),
+        "max_position_size": max_position_size,
+        "max_daily_loss": max_daily_loss,
+        "conviction_threshold": conviction_threshold,
+        "is_paper_trading": is_paper_trading,
+        "market_hours_only": market_hours_only,
+        "auto_rebalance": auto_rebalance,
+    }
+    try:
+        data = client.forward_test(config)
+        emit(ctx, data)
+    except Exception as e:
+        emit_error(ctx, str(e))
+        ctx.exit(1)
+
+
+# ══════════════════════════════════════════════════════════════════════════
+# list / delete
+# ══════════════════════════════════════════════════════════════════════════
+
+@backtest.command("list")
+@click.pass_context
+def list_backtests(ctx):
+    """List saved backtest results.
+
+    Example: fastbooks backtest list
+    """
+    client: FastBooksClient = ctx.obj
+    try:
+        data = client.list_backtests()
+        emit(ctx, data, lambda d: _format_backtest_list(d))
+    except Exception as e:
+        emit_error(ctx, str(e))
+        ctx.exit(1)
+
+
+def _format_backtest_list(data) -> str:
+    items = data if isinstance(data, list) else data.get("backtests", data.get("data", []))
+    if not isinstance(items, list):
+        return str(data)
+    if not items:
+        return "  No backtests found."
+    return format_table(
+        items,
+        ["id", "venue", "start", "end", "total_return", "sharpe_ratio", "status"],
+        ["ID", "Venue", "Start", "End", "Return", "Sharpe", "Status"],
+    )
+
+
+@backtest.command("delete")
+@click.argument("backtest_id")
+@click.pass_context
+def delete_backtest(ctx, backtest_id):
+    """Delete a saved backtest.
+
+    Example: fastbooks backtest delete bt-abc123
+    """
+    client: FastBooksClient = ctx.obj
+    try:
+        data = client.delete_backtest(backtest_id)
+        emit(ctx, data, lambda d: f"  Backtest {backtest_id} deleted.")
+    except Exception as e:
+        emit_error(ctx, str(e))
+        ctx.exit(1)