feat: add backtest CLI for historical price simulation

Cargo.toml

@@ -35,6 +35,10 @@ path = "src/bin/polymarket.rs"
 name = "okx"
 path = "src/bin/okx.rs"
 
+[[bin]]
+name = "backtest"
+path = "src/bin/backtest.rs"
+
 [dependencies]
 clap = { version = "4", features = ["derive"] }
 reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"] }

examples/backtest/covid_crash_hedge.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+#
+# COVID-19 Crash — Flight-to-Safety Hedge
+# ========================================
+#
+# Date: February 21, 2020 (Friday before the crash accelerated)
+#
+# Thesis: By late February 2020, COVID-19 had spread to Italy and South
+# Korea. The S&P 500 hit its all-time high on Feb 19. A pandemic-driven
+# selloff was imminent. The classic hedge: go long gold (safe haven) and
+# short equities. This is a dollar-neutral pair: ~$5,000 each side.
+#
+# Legs:
+#   1. Long GOLD  — 3 oz at ~$1,645/oz  ($4,934 notional)
+#   2. Short SP500 — 1.5 units at ~$3,337 ($5,006 notional)
+#
+# What happened: The S&P 500 fell ~12% over the next 7 trading days
+# (the fastest correction from ATH in history). Gold initially held
+# steady, then pulled back as margin calls hit.
+#
+# Result: The short equity leg dominates — this hedge captured the
+# crash while the gold leg acts as a stabilizer.
+#
+# Usage: ./examples/backtest/covid_crash_hedge.sh
+#
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+BT="${BACKTEST:-$SCRIPT_DIR/../../target/release/backtest}"
+
+echo ""
+echo "══════════════════════════════════════════════════════════════"
+echo " COVID-19 Crash Hedge — February 21, 2020"
+echo " Long GOLD + Short S&P 500 (dollar-neutral pair)"
+echo "══════════════════════════════════════════════════════════════"
+echo ""
+
+# ── Reset portfolio ────────────────────────────────────────────────
+$BT --at 2020-02-21 reset 2>/dev/null
+
+# ── Scout: get prices on Feb 21, 2020 ─────────────────────────────
+echo "── Scouting prices on 2020-02-21 ──"
+echo ""
+
+GOLD_PRICE=$($BT --at 2020-02-21 --json '{"command":"quote","symbol":"GOLD"}' 2>/dev/null | jq -r '.price')
+SP_PRICE=$($BT --at 2020-02-21 --json '{"command":"quote","symbol":"SP500"}' 2>/dev/null | jq -r '.price')
+
+echo "  GOLD:  \$$GOLD_PRICE / oz"
+echo "  SP500: \$$SP_PRICE"
+echo ""
+
+# ── Leg 1: Long gold — safe-haven bid ─────────────────────────────
+echo "── Leg 1: Long GOLD (flight to safety) ──"
+$BT --at 2020-02-21 buy GOLD --amount 3 --price "$GOLD_PRICE"
+
+# ── Leg 2: Short S&P 500 — pandemic selloff ───────────────────────
+echo "── Leg 2: Short S&P 500 (equity crash) ──"
+$BT --at 2020-02-21 sell SP500 --amount 1.5 --price "$SP_PRICE"
+
+# ── Portfolio snapshot ─────────────────────────────────────────────
+echo "══════════════════════════════════════════════════════════════"
+echo " Portfolio Summary"
+echo "══════════════════════════════════════════════════════════════"
+$BT --at 2020-02-21 balance
+$BT --at 2020-02-21 positions
+
+# ── Cleanup ────────────────────────────────────────────────────────
+$BT --at 2020-02-21 reset > /dev/null 2>&1

examples/backtest/ftx_crypto_contagion.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+#
+# FTX Collapse — Crypto Contagion Hedge
+# ========================================
+#
+# Date: November 8, 2022 (Binance announced it would sell its FTT holdings)
+#
+# Thesis: On Nov 6, CoinDesk reported Alameda's balance sheet was full
+# of FTT tokens. On Nov 8, Binance announced it would liquidate its
+# ~$530M in FTT, triggering a bank run on FTX. Crypto was about to
+# enter a contagion spiral — but it wasn't clear how far traditional
+# markets would follow. The trade: short crypto (BTC + ETH) and go
+# long gold as a safe-haven hedge in case the contagion spread.
+#
+# Legs:
+#   1. Short BTC  — 0.15 BTC at ~$18,500  ($2,775 notional)
+#   2. Short ETH  — 2.0 ETH at ~$1,340    ($2,680 notional)
+#   3. Long GOLD  — 3 oz at ~$1,712/oz    ($5,136 notional)
+#
+# Gold is the anchor — roughly sized to match the combined crypto short.
+# If crypto crashes and gold holds or rises, both sides win. If crypto
+# recovers, the gold leg limits the damage.
+#
+# What happened: BTC dropped from $18.5k to $15.7k (-15%) in 7 days.
+# ETH fell from $1,340 to $1,100 (-18%). Gold was roughly flat,
+# providing stability. The crypto short was the main profit driver.
+#
+# Usage: ./examples/backtest/ftx_crypto_contagion.sh
+#
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+BT="${BACKTEST:-$SCRIPT_DIR/../../target/release/backtest}"
+
+echo ""
+echo "══════════════════════════════════════════════════════════════"
+echo " FTX Collapse — November 8, 2022"
+echo " Short BTC + Short ETH + Long GOLD (contagion hedge)"
+echo "══════════════════════════════════════════════════════════════"
+echo ""
+
+# ── Reset portfolio ────────────────────────────────────────────────
+$BT --at 2022-11-08 reset 2>/dev/null
+
+# ── Scout: get prices on Nov 8, 2022 ──────────────────────────────
+echo "── Scouting prices on 2022-11-08 ──"
+echo ""
+
+BTC_PRICE=$($BT --at 2022-11-08 --json '{"command":"quote","symbol":"BTC"}' 2>/dev/null | jq -r '.price')
+ETH_PRICE=$($BT --at 2022-11-08 --json '{"command":"quote","symbol":"ETH"}' 2>/dev/null | jq -r '.price')
+GOLD_PRICE=$($BT --at 2022-11-08 --json '{"command":"quote","symbol":"GOLD"}' 2>/dev/null | jq -r '.price')
+
+echo "  BTC:   \$$BTC_PRICE"
+echo "  ETH:   \$$ETH_PRICE"
+echo "  GOLD:  \$$GOLD_PRICE"
+echo ""
+
+# ── Leg 1: Short BTC — exchange contagion ─────────────────────────
+echo "── Leg 1: Short BTC (FTX contagion, forced selling) ──"
+$BT --at 2022-11-08 sell BTC --amount 0.15 --price "$BTC_PRICE"
+
+# ── Leg 2: Short ETH — crypto-wide selloff ────────────────────────
+echo "── Leg 2: Short ETH (correlated crypto drawdown) ──"
+$BT --at 2022-11-08 sell ETH --amount 2.0 --price "$ETH_PRICE"
+
+# ── Leg 3: Long gold — safe-haven anchor ──────────────────────────
+echo "── Leg 3: Long GOLD (safe haven, hedge against reversal) ──"
+$BT --at 2022-11-08 buy GOLD --amount 3 --price "$GOLD_PRICE"
+
+# ── Portfolio snapshot ─────────────────────────────────────────────
+echo "══════════════════════════════════════════════════════════════"
+echo " Portfolio Summary"
+echo "══════════════════════════════════════════════════════════════"
+$BT --at 2022-11-08 balance
+$BT --at 2022-11-08 positions
+
+# ── Cleanup ────────────────────────────────────────────────────────
+$BT --at 2022-11-08 reset > /dev/null 2>&1

examples/backtest/nvda_earnings_alpha.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+#
+# NVIDIA Earnings Blowout — AI Sector Alpha
+# ============================================
+#
+# Date: May 25, 2023 (day after NVDA's historic Q1 FY24 earnings)
+#
+# Thesis: On May 24, 2023, NVIDIA reported revenue of $7.19B (vs
+# $6.52B expected) and guided Q2 to $11B — 50% above consensus.
+# The stock surged 25% after hours. This was the moment the market
+# realized AI infrastructure demand was real. The play: capture
+# NVDA's alpha while hedging broad market risk.
+#
+# Legs:
+#   1. Long NVDA  — 13 shares at ~$379/share ($4,930 notional)
+#   2. Short SP500 — 1.2 units at ~$4,151     ($4,981 notional)
+#
+# This is a classic long/short equity pair: long the winner, short
+# the index. If the market rallies, NVDA should rally more. If the
+# market drops, NVDA's AI tailwind should cushion the loss.
+#
+# What happened: NVDA continued climbing from $379 to $400+ over
+# the next week as analysts rushed to upgrade. The S&P 500 was
+# roughly flat. Pure alpha.
+#
+# Usage: ./examples/backtest/nvda_earnings_alpha.sh
+#
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+BT="${BACKTEST:-$SCRIPT_DIR/../../target/release/backtest}"
+
+echo ""
+echo "══════════════════════════════════════════════════════════════"
+echo " NVIDIA AI Earnings — May 25, 2023"
+echo " Long NVDA + Short S&P 500 (sector alpha pair)"
+echo "══════════════════════════════════════════════════════════════"
+echo ""
+
+# ── Reset portfolio ────────────────────────────────────────────────
+$BT --at 2023-05-25 reset 2>/dev/null
+
+# ── Scout: get prices on May 25, 2023 ─────────────────────────────
+echo "── Scouting prices on 2023-05-25 ──"
+echo ""
+
+NVDA_PRICE=$($BT --at 2023-05-25 --json '{"command":"quote","symbol":"NVDA"}' 2>/dev/null | jq -r '.price')
+SP_PRICE=$($BT --at 2023-05-25 --json '{"command":"quote","symbol":"SP500"}' 2>/dev/null | jq -r '.price')
+
+echo "  NVDA:  \$$NVDA_PRICE"
+echo "  SP500: \$$SP_PRICE"
+echo ""
+
+# ── Leg 1: Long NVDA — AI momentum ───────────────────────────────
+echo "── Leg 1: Long NVDA (AI infrastructure demand) ──"
+$BT --at 2023-05-25 buy NVDA --amount 13 --price "$NVDA_PRICE"
+
+# ── Leg 2: Short S&P 500 — market-neutral hedge ──────────────────
+echo "── Leg 2: Short S&P 500 (hedge broad market risk) ──"
+$BT --at 2023-05-25 sell SP500 --amount 1.2 --price "$SP_PRICE"
+
+# ── Portfolio snapshot ─────────────────────────────────────────────
+echo "══════════════════════════════════════════════════════════════"
+echo " Portfolio Summary"
+echo "══════════════════════════════════════════════════════════════"
+$BT --at 2023-05-25 balance
+$BT --at 2023-05-25 positions
+
+# ── Cleanup ────────────────────────────────────────────────────────
+$BT --at 2023-05-25 reset > /dev/null 2>&1

examples/backtest/ukraine_oil_shock.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+#
+# Russia-Ukraine Invasion — Commodity Supply Shock
+# ==================================================
+#
+# Date: February 24, 2022 (the day Russia invaded Ukraine)
+#
+# Thesis: Russia is a top-3 global oil producer. A full-scale invasion
+# means sanctions, supply disruption, and an energy price spike. At the
+# same time, risk assets sell off on geopolitical uncertainty. This is
+# a classic macro shock trade: long commodities, short equities.
+#
+# Legs:
+#   1. Long OIL  — 35 bbl at ~$92/bbl  ($3,220 notional)
+#   2. Long GOLD — 2 oz at ~$1,909/oz  ($3,818 notional) — war safe haven
+#   3. Short SP500 — 1.5 units at ~$4,225 ($6,338 notional)
+#
+# The short leg is sized larger to roughly balance the two long legs.
+# Oil is the directional bet; gold is the defensive anchor.
+#
+# What happened: Oil surged to $115+ within 2 weeks (eventually $130
+# in March). Gold rallied to $2,050. The S&P 500 dropped ~3% in the
+# first week before stabilizing.
+#
+# Result: Both commodity legs profit on the supply shock, while the
+# equity short captures the initial risk-off move.
+#
+# Usage: ./examples/backtest/ukraine_oil_shock.sh
+#
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+BT="${BACKTEST:-$SCRIPT_DIR/../../target/release/backtest}"
+
+echo ""
+echo "══════════════════════════════════════════════════════════════"
+echo " Russia-Ukraine Invasion — February 24, 2022"
+echo " Long OIL + Long GOLD + Short S&P 500"
+echo "══════════════════════════════════════════════════════════════"
+echo ""
+
+# ── Reset portfolio ────────────────────────────────────────────────
+$BT --at 2022-02-24 reset 2>/dev/null
+
+# ── Scout: get prices on Feb 24, 2022 ─────────────────────────────
+echo "── Scouting prices on 2022-02-24 ──"
+echo ""
+
+OIL_PRICE=$($BT --at 2022-02-24 --json '{"command":"quote","symbol":"OIL"}' 2>/dev/null | jq -r '.price')
+GOLD_PRICE=$($BT --at 2022-02-24 --json '{"command":"quote","symbol":"GOLD"}' 2>/dev/null | jq -r '.price')
+SP_PRICE=$($BT --at 2022-02-24 --json '{"command":"quote","symbol":"SP500"}' 2>/dev/null | jq -r '.price')
+
+echo "  OIL:   \$$OIL_PRICE / bbl"
+echo "  GOLD:  \$$GOLD_PRICE / oz"
+echo "  SP500: \$$SP_PRICE"
+echo ""
+
+# ── Leg 1: Long crude oil — supply disruption ─────────────────────
+echo "── Leg 1: Long OIL (supply shock from sanctions) ──"
+$BT --at 2022-02-24 buy OIL --amount 35 --price "$OIL_PRICE"
+
+# ── Leg 2: Long gold — geopolitical safe haven ────────────────────
+echo "── Leg 2: Long GOLD (war premium + safe haven) ──"
+$BT --at 2022-02-24 buy GOLD --amount 2 --price "$GOLD_PRICE"
+
+# ── Leg 3: Short S&P 500 — risk-off selloff ──────────────────────
+echo "── Leg 3: Short S&P 500 (risk-off) ──"
+$BT --at 2022-02-24 sell SP500 --amount 1.5 --price "$SP_PRICE"
+
+# ── Portfolio snapshot ─────────────────────────────────────────────
+echo "══════════════════════════════════════════════════════════════"
+echo " Portfolio Summary"
+echo "══════════════════════════════════════════════════════════════"
+$BT --at 2022-02-24 balance
+$BT --at 2022-02-24 positions
+
+# ── Cleanup ────────────────────────────────────────────────────────
+$BT --at 2022-02-24 reset > /dev/null 2>&1