Stonks & Texts

A paper-trading app where each asset texts you about its own price movement, and you reply with one of three buttons. The question underneath the joke is a real one:

Does reacting to the texts beat just buying and holding?

Over the seeded window the answer is yes, by 13.8 points — but the interesting part is the controls that make that number mean something. See Methodology.

---

Quick start

npm install
npm run dev            # http://localhost:3000

That works from a fresh clone with no database. The two years of price data are committed to data/, and the app falls back to a file-backed data source when Supabase credentials are absent. Add credentials (below) and it switches automatically.

npm run demo           # auto-play a year so the Portfolio and Data tabs are populated
npm run demo -- --clear   # wipe trades and rewind the clock

---

How it fits together

scripts/fetch_prices.py     Yahoo Finance -> data/prices/*.csv        (Python, yfinance)
        |
        v
src/lib/messages/rules.ts   prices -> messages          THE RULES ENGINE
        |
        +--> scripts/seed.ts     writes assets/prices/messages into Supabase
        +--> src/lib/data/       app reads them back (Supabase or local files)
        |
        v
src/lib/portfolio.ts        trades + prices -> equity curve, positions, P&L
src/lib/strategies.ts       messages -> reference strategies for comparison

The rules engine has exactly one implementation. The seed script imports the same module the app does, so the messages in the database and the messages the app would generate can never disagree.

Commands

Command	What it does
npm run dev	Dev server
npm run fetch	Re-pull 2 years of OHLCV from Yahoo into data/
npm run seed	Load data/ into Supabase (add -- --reset to clear trades)
npm run test:rules	Run the rules engine over the real data, print the message mix
npm run backtest	Run the full backtest, write data/backtest.json
npm run demo	Auto-play the sim so there's something to look at

---

The data

Twelve tickers, chosen to span volatility profiles so the rules engine produces a varied mix rather than one tone: mega-cap steady (AAPL, MSFT, GOOGL, AMZN, META), high-beta tech (NVDA, AMD, TSLA), meme/crypto-adjacent (COIN, GME), and true 7-day crypto (BTC-USD, ETH-USD).

• ~2 years of daily OHLCV per asset, split- and dividend-adjusted. Unadjusted data turns a stock split into a fake -50% crash, which would trip the "big drop" rule for entirely the wrong reason.
• The most recent date in the dataset is "today" throughout the app.
• The most recent 12 months are playable; the 12 months before that exist only as lookback, so 52-week highs/lows and volume averages are already well-defined on the first playable day.
• No runtime API calls. The CSVs are committed. A deploy is reproducible forever.

The calendar problem

Crypto prints a bar 7 days a week; stocks print 5. A naive join treats a Saturday as a day AAPL was worth $0. Every price lookup forward-fills from the last known close, and isTradeable() reports whether an asset genuinely printed a bar that day — so the UI disables its buttons instead of filling a trade at a stale price.

---

The rules engine

src/lib/messages/rules.ts — eight rules, evaluated in priority order, first match wins. Nothing calls Math.random() or Date.now(): same prices in, byte-identical messages out, every run.

Priority	Rule	Fires when	Tone
5	new_52w_high	Close is the highest in 52 weeks	euphoric
5	new_52w_low	Close is the lowest in 52 weeks	despondent
4	big_gain	Up more than 5% on the day	manic
4	big_drop	Down more than 5% on the day	anxious
3	losing_streak	4+ consecutive down days	desperate (escalates)
3	winning_streak	4+ consecutive up days	smug
2	volume_spike	Volume ≥ 2× the 20-day average	attention
1	mundane	Nothing notable; throttled to one per 7 quiet days	casual

Every threshold is a named constant in THRESHOLDS — one place to tune.

Where variety comes from. So threads don't read like form letters, each rule has several phrasings and one is picked with an FNV-1a hash of (ticker, date, rule). That's a pure function of the input: varied and reproducible. It is not random flavour text — every message is a claim about what the price actually did, and each bubble in the UI shows the receipt (the day's move, the volume multiple, the rule that fired).

Two throttles that matter. Both were added after measuring the output, not guessed:

• 52-week extremes fire on the breakout day only. In an uptrend every session sets a new high, so the unthrottled rule fired 38 times for GOOGL and "I've never been worth more" became meaningless. Requiring that yesterday was not also a high turns a 30-day run into one message: the day the record was reclaimed.
• Streaks fire on qualifying, then every other day. Firing daily made streaks 53.6% of all messages and buried everything else. After the fix they're 26.2%.

Run npm run test:rules to see the full distribution.

---

Methodology

This is the part worth reading.

Execution lag

A message is produced by a day's closing price. Filling that same close assumes you knew where the day would finish before it did. Orders therefore fill at the next session the asset actually trades. The optimistic assumption is available via npm run backtest -- --same-close for comparison — it adds about 1.5 points to the headline, which is exactly why it isn't the default.

The baselines

Strategy	What it does	Return
Reactive	Buys hype, sells panic — the emotional reply to every text	+28.8%
Buy & hold	Splits $10,000 evenly across all 12 on day one, never trades again	+15.0%
Coin flip	Trades on the same days but ignores what the text said	+1.9%
Contrarian	The same texts read backwards	+7.9%

Why the coin flip exists. Beating buy-and-hold could just mean "you traded a lot in a rising market." The coin flip runs the same message stream, on the same days, under the same cash constraint, and picks its action without reading the message. Reactive clears it by 26.9 points, which is the comparison that actually supports the claim.

Position sizing

The reply bar lets you trade $250, $500, $1,000, or your whole balance / position. The reference strategies always bet a fixed $500, and deliberately so: Reactive, Contrarian and Coin flip are only comparable to each other because every one of them stakes the same amount on every signal. Letting the benchmarks size variably would turn a strategy comparison into a position-sizing comparison, which is a different experiment.

Your own curve is derived from your ledger, so variable sizing is handled correctly — but it does mean a big edge over the benchmark can come from sizing rather than from timing. Worth saying out loud if you quote your own number rather than the Reactive one.

A control that didn't work, and what it taught us

The first fairness control was "make the same buys on the same days, but never sell" — to separate good timing from simply being more exposed. It's degenerate: under a fixed $10,000 budget it fills only 20 of ~300 buy orders before running out of cash and then sits frozen for a year. It isn't "never sells", it's "bought 20 things in week one."

That failure is itself the finding: selling is what funds the strategy. Sells recycle capital, which is why Reactive fills 207 orders where the buys-only variant fills 20.

Portfolio valuation

The equity curve is derived from the trade ledger, not stored as snapshots. You can trade at any point in the sim window, and any new trade invalidates every snapshot after its date — a stale row would silently corrupt the headline number. Deriving it means the chart cannot disagree with the trades that produced it. A daily_positions SQL view exposes the same data for inspection.

Cost basis uses weighted average. Sharpe assumes a 0% risk-free rate; volatility and Sharpe annualise with the conventional 252-session factor.

Honest limits

• One historical window, one asset universe. A 13.8-point edge over 12 months is not evidence the strategy generalises — a different year could easily invert it.
• No transaction costs, no slippage, no bid-ask spread. Reactive places 207 trades and buy-and-hold places 12, so costs would hurt it far more.
• Fractional shares are assumed available.

---

The recommendation engine (ML service)

A second deliverable in ml/: a fitted scikit-learn Pipeline served over FastAPI, deployed to Modal, and called from the browser by the Messages tab.

• API: https://parinthaokar--stonks-recommendation-engine-fastapi-app.modal.run (docs)
• Pipeline: MarketContextFeatures (custom) → StandardScaler → LogisticRegression
• Learned state: scaler means/stds and regression coefficients across three classes
• Label: the best action over t+1 → t+6, so a signal from today's close is only ever acted on tomorrow

It does not beat a majority-class baseline — 34.5% against 36.9% on a temporal split with a 10-day embargo. That is the expected result, it is stated next to every recommendation in the UI, and the model appears as a fourth line on the Data tab chart so the claim is checkable rather than asserted.

Three framings were tested before this one — direction, volatility magnitude, and nearest-neighbour analogy — and none beat their baselines. The most telling result came from the analogue model: filtering to days where its neighbours agreed made it less accurate (41.7% when 80% agreed, versus 49.3% when 60% agreed), so confidence was inversely related to correctness. That is why the UI keeps the recommendation collapsed by default and prints the model's real track record beside it.

See ml/SUBMISSION.md for URLs, the write-up and rebuild steps.

Supabase

Create a project, then run supabase/schema.sql in the SQL editor. Put credentials in .env.local:

NEXT_PUBLIC_SUPABASE_URL=https://xxxxx.supabase.co
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=sb_publishable_...
SUPABASE_SECRET_KEY=sb_secret_...

Supabase is migrating from legacy JWT keys to a new format. Both are accepted — the legacy names NEXT_PUBLIC_SUPABASE_ANON_KEY and SUPABASE_SERVICE_ROLE_KEY work as fallbacks (src/lib/data/env.ts).

Then npm run seed. The app switches to Supabase automatically.

Schema: assets, price_history, messages, trades, sim_state, plus a daily_positions view. There is no auth — this is a single-demo-user app, so RLS is on everywhere with policies that grant anon read on the seeded market data, insert/delete on trades, and update on sim_state, and nothing else. The seeded market data cannot be rewritten through the public key. Real users would need auth and per-user rows.

The secret key is used only by the seed script, which needs it because RLS deliberately makes the seeded tables read-only for the publishable key. It must never be added to Vercel.

---

Deploying

Vercel needs NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY. Without them the deploy still works — it serves the committed dataset read-only, but trades won't persist, because a serverless filesystem is ephemeral.

Stack

Next.js 16 (App Router) · shadcn/ui + Tailwind v4 · Supabase (Postgres) · Recharts · Python + yfinance for the fetch step only.