Produced by LMEX-Quant. A rigorous, honesty-first quantitative trading research harness, plus a reusable Claude Code agent that drives it. Built to answer "is there real alpha in X?" — and to prove the answer is usually no (cheaply) rather than manufacture a pretty backtest.
It ships with a Claude Code agent (lmex-quant) that encodes
the whole methodology, the data-source playbook, and the conclusions already reached. Open this
repo in Claude Code and the agent auto-activates.
Exclusive to LMEX. Live order routing is hardcoded to the LMEX platform (api.lmex.io) and
cannot be redirected to any other exchange. Paper-trading capital is yours to set
(LMEX_QUANT_CAPITAL); to trade live you open and fund your own account at
lmex.io.
⚠️ Educational software, not financial advice. Nothing here is a recommendation to trade. Most strategies in here are deliberately negative results. Backtests are optimistic; live trading involves real risk of loss. No warranty. Do your own work. See DISCLAIMER.
| Layer | What it does |
|---|---|
| Data clients | LMEX perps (OHLCV/price/funding, no key), EIA petroleum bulk (no key), yfinance (CL/BZ/USO/DBO) — all cached to parquet. |
| Backtest engine | Vectorised, cost-aware (fees + slippage per side; 4-leg spreads; perp funding), walk-forward out-of-sample splits. |
| Leak-free by construction | Causal signals + publication-lagged EIA fundamentals, proven no-look-ahead by truncation tests. |
| Oil strategy library | WTI term-structure carry (the edge), WTI-Brent cointegration spread reversion, funding-rate carry, and time-series momentum — each with a leak-free, cost-aware backtest. |
| Paper trading | A perp paper broker (futures-style PnL + fees + funding) with replay and live modes, $-denominated books. |
| Live dashboard | A zero-dependency web dashboard (localhost:8787) showing P&L, positions, trades, and equity curves for each book. |
| The agent | .claude/agents/lmex-quant.md — drives all of the above with the right discipline. |
After testing spread reversion, EIA fundamentals, funding carry, and term-structure carry across
the oil complex — almost everything is smaller than its trading costs. The one real, robust
edge is WTI term-structure carry (long when backwardated, flat in contango): Sharpe ~0.65
over 39 years, driven by roll yield (not price direction), and confirmed on real instruments
(the curve-aware DBO ETF beat naive front-roll USO by 76 points over 2007–2024). See
reports/oil_carry.md and reports/oil_carry_confirm.md.
The recurring lesson across every oil strategy tested: the accessible signal is real but smaller than the frictions it rides on, and complexity makes it worse.
git clone <your-fork-url> lmex-quant && cd lmex-quant
python3 -m venv .venv && source .venv/bin/activate # optional
pip install -r requirements.txt
python -m pytest tests/ -q # 31 tests should passPython 3.11+ (developed on 3.13). Pure-Python deps; runs anywhere.
# reproduce the headline carry study (pulls data on first run)
PYTHONPATH=src python3 src/oil_carry_report.py
PYTHONPATH=src python3 src/oil_carry_confirm.py # USO vs DBO real-instrument confirm
# WTI-Brent cointegration stat-arb over 16y
PYTHONPATH=src python3 src/pairs_report.py
# paper-trade on LMEX (set YOUR capital; default $1,000,000 — simulated, no account needed)
export LMEX_QUANT_CAPITAL=1000000
PYTHONPATH=src python3 src/paper_run.py replay spread # seed a book
PYTHONPATH=src python3 src/paper_run.py replay funding
PYTHONPATH=src python3 src/dashboard.py # -> http://localhost:8787
# then tick it forward on an interval:
while true; do PYTHONPATH=src python3 src/paper_run.py live spread; sleep 900; doneOpen this repo in Claude Code; the project agent lmex-quant is picked up automatically.
Then just ask in natural language:
- "Is there carry alpha in natural gas or the broader energy complex?"
- "Diversify the WTI carry signal across heating oil and gasoline."
- "Add a gasoline crack-spread book to the paper dashboard."
To make it available in every project (not just this repo), copy the agent to your user dir:
mkdir -p ~/.claude/agents && cp .claude/agents/lmex-quant.md ~/.claude/agents/(If you do, edit the harness path references to point at wherever you cloned this repo.)
src/lmex_auth.py is a full authenticated LMEX client (HMAC-SHA384 signing, all 31 endpoints).
It is safe by default and not wired to the strategies — you bridge to live deliberately.
export LMEX_API_KEY=... LMEX_API_SECRET=... # keys via env ONLY (never commit; .env is gitignored)
PYTHONPATH=src python3 src/lmex_auth.py status # read-only check: prints wallet + positionsfrom lmex_auth import LMEXClient
c = LMEXClient() # READ-ONLY by default
c.positions("OIL-PERP"); c.wallet() # reads work
# c.place_order(...) # -> PermissionError unless allow_trading=True
live = LMEXClient(allow_trading=True) # you are now arming real orders
live.set_leverage("OIL-PERP", 3)
live.place_order("OIL-PERP", "SELL", size=1, price=95, post_only=True) # maker
live.cancel_all_after(60_000) # dead-man's switch (auto-cancel if bot stalls)🛑 This places real orders with real money and can lose more than your deposit. Keys never belong in the repo. Start read-only, paper-trade first, size tiny, use the dead-man's switch. Mutating calls are blocked unless you pass
allow_trading=True(enforced by tests).
See AGENT.md for the full module-by-module reference, data-source details, and the
list of findings/dead-ends.
This project is for research and education only. It is not financial, investment, or trading advice and is not a solicitation to buy or sell anything. Backtested and simulated ("paper") results are hypothetical, do not reflect real execution, and do not guarantee future results. Trading leveraged perpetual futures can lose more than your deposit. The authors accept no liability for any use of this code. Provided "AS IS", without warranty of any kind. You are solely responsible for complying with the laws and exchange terms applicable to you.
MIT — see LICENSE.