Blame for README.md

---
title: Updraft
emoji: 🪁
colorFrom: red
colorTo: yellow
sdk: docker
app_port: 7860
pinned: false
short_description: Rides the strongest quality stocks; 3 names, monthly
---

# 🪁 Updraft

*The Quality-Trend 3 strategy, running on its own.*

Three large US stocks with strong **quality and capital discipline** and the strongest **price trends**, held on an
Alpaca **paper** account and rebalanced automatically once a month. The page shows the live portfolio, growth vs the
S&P 500 since the first trade, the trade log and this month's ranking.

**Rule** (backtested in the RS-VCP / Quant Model research, `scripts/finalize_qt3_managed.py`):
1. Universe — the 1,000 largest US companies by market cap; price ≥ $5; ≥ $5M a day traded; US-dollar statements.
2. Quality pool — top 30% of a capital-discipline composite: basic-diluted gap, quality score (ROE, ROA, gross margin,
   FCF conversion), −equity financing, FCF yield, ROE, buyback yield, net share reduction.
3. Trend — the pool ranked by 0.5 · pct(MA50/MA200) + 0.5 · pct(6-1-month return).
4. Monthly — keep holdings still ranked in the top 6, sell the rest, buy from the top until 3 are held, re-split
   equally (1% kept in cash). Sells first, waited for, then buys sized to the cash actually available (no margin).

Backtest 1999-08 → 2026-09, after 10 bps per side, point-in-time lists incl. delisted names: **+30.9%/yr** (S&P +8.5%),
worst fall −34%, any 12 months median +24% (in profit 87% of the time). Backtests flatter; expect less.

## How it runs without a PC
- **Data** — each day the Space builds the ranking itself from the Sharadar API (Nasdaq Data Link, ~40 requests,
  ~70 s). It reproduces the research snapshot exactly (verified 2026-10-13: same top 10, same 250-name pool).
- **Trading** — `POST /api/rebalance?dry=0` with `X-Rebalance-Token`. It trades only when **all** hold: market open;
  one of the first 5 trading days of the month (or the very first run); not already rebalanced this month; ranking
  data ≤ 5 days old. Every other call is a harmless no-op. Orders carry `client_order_id = qt3-YYYYMMDD-SYM-side`,
  so a retried call cannot duplicate them.
- **Schedule (built in)** — the Space runs its own timer (`qt3/scheduler.py`): every 15 minutes it rebuilds the
  ranking if it is older than 20 hours, and on weekdays 10:00–15:30 New York time it attempts the guarded rebalance
  above — so it trades on the first trading day of each month and does nothing otherwise. No GitHub needed.
  Set `AUTO_REBALANCE=0` to switch it off. The GitHub workflows in `.github/workflows/` remain an optional backup.
- **Keep-awake** — a free Space sleeps after 48 h without visitors, and a sleeping Space's timer stops. A Hugging Face
  **Scheduled Job** (`updraft-keepalive`, id `6acdd86bb0ad3e9da5ea6936`, cron `0 */12 * * *`, cpu-basic) visits
  `/api/health` every 12 hours — a few seconds of compute, well under $0.10 a month; pause or delete it under the
  account's Jobs. Alternatives: a free uptime monitor (UptimeRobot / cron-job.org) or paid hardware with sleep off.
- **State** — all in Alpaca (positions, orders, portfolio history). A restart only rebuilds the ranking cache.

## Settings (Space → Settings → Variables and secrets)
| Secret | Purpose |
|---|---|
| `NASDAQ_DATA_LINK_API_KEY` | Sharadar data for the ranking |
| `ALPACA_API_KEY_ID`, `ALPACA_API_SECRET_KEY` | the **paper** account this Space manages (use a dedicated account) |
| `REBALANCE_TOKEN` | a long random string; the same value goes into the GitHub secret `UPDRAFT_REBALANCE_TOKEN` |

Optional variables: `ALPACA_DATA_FEED` (default `iex`), `CASH_BUFFER` (0.01), `QT3_INCEPTION` (YYYY-MM-DD for the
public stats). **Live trading** is off unless both `ALPACA_PAPER=false` and `ALPACA_ALLOW_LIVE=yes` are set.

## API
Public: `GET /` page · `/api/health` · `/api/status` · `/api/portfolio` · `/api/performance` · `/api/orders` ·
`/api/ranking` · `/api/plan` (dry-run of what a rebalance would do now). Private (token): `POST /api/rebalance?dry=0`
(`force=1` overrides only the window / once-a-month guards) · `POST /api/refresh` (rebuild the ranking now).

## Notes
Educational paper-trading demonstration — not investment advice. The page shows derived rankings only, not raw
Sharadar data. Each stock is a third of the money: one stock halving costs ~17%. Taxes and slippage beyond 10 bps
are not modelled.