trading-hypothesis-workflow

Agentic workflow for turning crypto trading hypotheses into data-backed verdicts.

---

Clone once per hypothesis. The pipeline converts a raw idea into a final verdict (pursue, iterate, or discard): structured specification → implementation → full backtest validation. Most hypotheses will fail — the goal is to fail fast, fail cheaply, and move on.

Philosophy

• Hypotheses are disposable. The workflow produces a clear go/no-go signal with minimal attachment to any individual idea, which is crucial for objective analysis when developing a trading strategy.
• Validate 20 ideas in the time it would take to manually validate 1. The edge is in throughput and process quality, not in any single strategy.
• Overfitting is the default outcome. Rigorous backtesting with objective analysis (standard backtesting, Walk-Forward Optimization, Probability of Backtest Overfitting, context-dependent tests)
• Validated for real trading, not optimal parameters. Transaction costs are real. No simulation means anything without realistic slippage, fees, gas costs, and funding rate modeling.

Quick Start

# 1. Copy the template for your hypothesis
cp -r trading-hypothesis-workflow/ 001-funding-rate-arb/
cd 001-funding-rate-arb/

# 2. Install dependencies
pip install -r requirements.txt

# 3. Configure
cp .env.example .env   # add your API keys
# Edit config.toml with strategy params, pairs, timeframe, etc.

Requirements: Python 3.10+

Workflow

Built for Claude Code. Also works in Codex.

Three stages, each producing artifacts for the next. Run them via slash commands in your agentic coding environment:

Stage 1 — Define the hypothesis

/create-prompt <your hypothesis>

Runs an interactive Q&A based on prompts/meta-prompt.md. Outputs prompts/implementation-prompt.md — the master spec that drives everything downstream.

Stage 2 — Generate PRDs

/create-prds

Produces two detailed specs from the implementation prompt:

• prompts/prd-algorithm.md — signal logic, entry/exit rules, position sizing, execution
• prompts/prd-backtest.md — data requirements, test methodology, output format, evaluation criteria

Stage 3 — Build and Backtest

/run-workflow

Implements the full system (data pipeline, strategy module, backtest harness) and runs the complete validation suite. Outputs:

• results/report.html — interactive Plotly dashboard with equity curves, drawdown analysis, and metrics
• results/verdict.md — 60-second summary with ratings: PURSUE / ITERATE / DISCARD

Run Everything at Once

/run-all

Chains all three stages sequentially.

Configuration

config.toml has four sections:

Section	Purpose
[strategy]	Name, trading pairs, timeframe, hypothesis-specific [strategy.params]
[backtest]	Date range, initial capital, fees, slippage, WFO/MC/PBO settings
[position_sizing]	Method (fixed fractional), risk per trade, max exposure, Kelly multiplier
[data]	Provider (default: Binance), cache directory

.env holds API keys. Which ones you need depends entirely on the strategy being tested — a pure Binance momentum strategy needs nothing beyond BINANCE_VISION_BASE, while a Solana DEX flow strategy might need Helius, Birdeye, Bitquery, and Flipside. None are required upfront. The full list with documentation links is in .env.example.

Service	Used For	Cost
Helius	Solana RPC, priority fees, enhanced APIs	Paid
Jupiter	Solana DEX quotes, price impact curves	Free tier
Birdeye	Token prices, OHLCV, DEX trade history	Paid
Bitquery	On-chain GraphQL — Jupiter swaps, DEX flow	Paid
Flipside Crypto	Historical Solana SQL queries (via MCP)	Free tier
Dune Analytics	Community queries, CSV export	Free tier
Tavily	Web search during research phase	Free tier
Firecrawl	Web scraping during research phase	Free tier
Alpaca	Paper trading execution	Free
Binance Data Vision	Historical OHLCV bulk download, funding rates	Free

Backtesting Methodology

Every backtest enforces the following, in full:

• Transaction costs baked into every simulation — exchange fees, estimated slippage, funding rates, and gas costs where applicable.
• Three-way data split into in-sample (50–60%), out-of-sample (30–40%), and a holdout set (10%) that is run exactly once as a final confirmation — never for tuning. Good article on holdout sets.
• Walk-forward optimization with rolling windows to validate that parameter choices generalize across time, not just within a fitted period.
• Probability of Backtest Overfitting (PBO) computed via Combinatorially Symmetric Cross-Validation (CSCV) with S=16 sub-samples, as described in Bailey, Borwein, López de Prado & Zhu (2017). A PBO above 0.15 is a disqualifying result.
• Monte Carlo simulation across 10,000 runs using three variants — return shuffling, trade resampling, and parameter perturbation — to stress-test robustness beyond what the historical path shows. Has to be coupled with WFO/PBO to control for overfitting.
• Regime analysis segments all results by bull/bear market and high/low volatility to surface whether the strategy is a genuine alpha source or just a beta exposure in disguise.

See docs/BACKTESTING.md for full implementation details and minimum passing thresholds.

Dependencies

Package	Purpose
numpy, pandas, polars	Data manipulation
ccxt	Exchange connectivity
scipy, statsmodels, scikit-learn	Statistical analysis
plotly, jinja2	Visualization and report generation
pyarrow	Parquet storage
loguru	Structured logging
python-dotenv, tomli	Config management