stock-analysis
Analyze stocks and cryptocurrencies using Yahoo Finance data. Supports portfolio management (create, add, remove assets), crypto analysis (T
Open source Repository Open in the app JSON README (API)
About
Analyze stocks and cryptocurrencies using Yahoo Finance data. Supports portfolio management (create, add, remove assets), crypto analysis (Top 20 by market cap), and periodic performance reports (daily/weekly/monthly/quarterly/yearly). 8 analysis dimensions for stocks, 3 for crypto. Use for stock analysis, portfolio tracking, earnings reactions, or crypto monitoring.
Details
- Kind
- Agent skills
- Topic
- Finance & crypto
- Publisher
- gracefullight
- Origin
- skillssh
- Category
- ferramentas
- Stars
- 44
- Forks
- 9
- Last push
- 2026-09-07T00:37:57Z
- Repository state
- ativo
- Language
- TypeScript
- Added
- 2026-08-30 15:21:15
- Updated
- 2026-09-11 01:03:08
- Origin id
gracefullight/stock-checker/stock-analysis
README
# Stock Checker
A bun-workspaces monorepo that screens US equities with an institutional-flow
signal engine, visualizes them in a web UI, and validates every strategy change
with a backtest.
| Package | What it is |
|---|---|
| `packages/core` | Signal engine, backtest, and CLI (`predict` / `learn` / `optimize` / `backtest`) |
| `apps/api` | Fastify API server (screener, ticker detail, OHLCV) — port 5101 |
| `apps/web` | Next.js 16 screener UI (candlestick + Gaussian Channel band charts, portfolio, light/dark) — port 5100 |
| Screener | Ticker detail (Gaussian Channel band) |
|---|---|
|  |  |
## Signal philosophy
The engine follows the principles in [docs/TRADING_PRINCIPLES.md](docs/TRADING_PRINCIPLES.md):
price, volume, VWAP, moving averages, liquidity, relative strength, and earnings
revisions over oscillator soup.
- **Trend regime** — Gaussian Channel (green = uptrend, red = downtrend) gates all buys.
- **Institutional flow score** — relative strength vs SPY and the sector ETF,
VWAP accumulation, breakout volume, dollar-volume liquidity, earnings revisions.
- **Strong-leader pullback entry (주도주 눌림목)** — BUY only when a name that
is STRONGLY outperforming both the market and its sector (`rs ≥ 0.7`) pulls
back below its 50-day SMA on a calm bar that closed in the bottom 20% of its
range (`ibs < 0.2`) with real participation. Backtested (8y incl. the 2020
crash and the 2022 bear, **546 tickers**, real pipeline, net of a 10bps
round-trip cost): **60.4% 5-day win rate / 1.28 reward-risk / N=225** vs the
51.3% / 1.05 ungated baseline (z≈2.6, p≈0.004), every entry year ≥ 50%.
- **SELL = exit discipline, not a downside prediction** — distribution-day
SELLs are suppressed inside intact uptrends and only fire when the trend
itself is broken.
- Classic indicators (RSI, Stochastic %K, Bollinger, Donchian, Williams %R,
MACD, ATR, volume ratio, Fear & Greed) are still computed and displayed, but
they season the score rather than drive it.
- Volatility-adjusted risk levels per signal: 1.5×ATR stop loss, 2× reward
take profit, trailing stop that activates after a 0.5×ATR move.
## Validated results
8-year window (entry years 2019–2026, incl. the 2020 COVID crash and the 2022
rate-hike bear), **546-ticker** diversified universe (large + mid + small cap,
all 11 sectors), fixed 5-day exit, evaluated through the real pipeline, **net
of a 10bps round-trip transaction cost** (a "win" = profitable after costs).
Full context and hard-won validation rules in
[docs/TRADING_PRINCIPLES.md](docs/TRADING_PRINCIPLES.md).
| Config | WR (5d) | R/R | N | Avg ret/trade |
|---|---|---|---|---|
| **Shipped gate** (`rs≥0.7` + `ibs<0.2` + `scr<400` + below-50d) | **60.4%** | **1.28** | 225 | 1.08% |
| Legacy V7 gate (`rs≥0.5`, `ibs<0.3`, `scr<380`) | 56.3% | 1.32 | 476 | 0.85% |
| + SPY kill-switch + 200d stage (NOT shipped — hurts at scale) | 55.7% | 1.29 | 230 | 0.79% |
| V5 institutional baseline (no quality gate) | 51.3% | 1.05 | 84,541 | 0.20% |
Shipped gate by entry year (WR / N): 2019 66%/41 · 2020 62%/21 · 2021 61%/33 ·
2022 55%/40 · 2023 52%/29 · 2024 55%/22 · 2025 65%/20 · 2026 74%/19 — every
year ≥ 50%, both bear regimes included. Train ≤2024: 58.6% / 1.19 (N=186) ·
holdout ≥2025: 69.2% / 2.35 (N=39). Significant vs baseline (z≈2.6, p≈0.004).
**Market-cap scope.** This is a **large-cap strategy**: ~90% of gate signals
fire on $10B+ names (the `atr%<3.5` calmness and `rs≥0.7` leadership profile
rarely matches smaller names). On mid caps the WR edge disappears (≈52% vs a
50.5% mid baseline, N=25 — winners run bigger but no hit-rate edge); the
ungated small-cap pullback baseline is outright negative (46% WR, −0.07%/trade).
Trade it on liquid large caps only.
**Falsification record.** On the original 122-ticker growth-heavy universe the
same family printed up to **71.7% WR / 1.75 R/R (N=46)** — expanding the
universe 4.5× collapsed it. The 70%+ readings were small-N universe artifacts,
not edge ("universe shapes conclusions"). The SPY-Gaussian market kill-switch
helped at 122 tickers and consistently *hurt* at scale, so it ships as an
optional gate param, off by default. Remaining caveats: as-of-today universe
and cap tiers (survivorship bias), no live forward track record.
## Usage
Tooling is managed by [mise](https://mise.jdx.dev); tasks wrap every common
operation (run `mise tasks` to see them all).
```bash
mise install # pin runtimes (node 24, bun)
bun install # install workspace deps + git pre-commit hook
mise run dev # API (5101) + Web (5100) dev servers in parallel
```
### Environment (optional)
| Variable | Effect |
|---|---|
| `TIINGO_API_KEY` | Enables the [Tiingo](https://www.tiingo.com) daily-OHLCV fallback when Yahoo is rate-limited or down (free tier: 1,000 req/day). Without it, OHLCV degrades to empty on Yahoo failure. |
| `SLACK_WEBHOOK_URL` | Slack notification for BUY/SELL opinions from `predict`. |
### CLI (packages/core)
```bash
# Daily prediction for a ticker list (default command)
mise run predict -- --ticker=TSLA,PLTR --sort=asc
# Slack notification for BUY/SELL opinions (either form)
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/XXX mise run predict -- --ticker=TSLA,PLTR
mise run predict -- --ticker=TSLA,PLTR --slack-webhook=https://hooks.slack.com/services/XXX
# Strategy validation & tuning
mise run backtest # version comparison, goal search, SELL validation
mise run backtest -- --cost-bps=20 # vary the round-trip cost (default 10bps)
mise run backtest -- --quick # stop after version comparison + gate tuning
mise run optimize # parameter optimizer (positional symbol, e.g. TSLA)
mise run learn # learn from prediction feedback
```
Each `predict` run appends rows to a monthly CSV in `packages/core/public/`
(e.g. `stock_data_202511.csv`), tickers in alphabetical order (`--sort=desc`
reverses).
### Quality gate
```bash
mise run ci # lint → typecheck → test → build
```
## Automation
- `.github/workflows/daily-data.yml` — runs `predict` after US market close and
auto-commits the monthly CSV.
- `.github/workflows/weekly-optimize.yml` — weekly parameter optimization,
results uploaded as a build artifact.