# When2Buy — Options Data Standard (v1.0 draft)

Static, dependency-free site describing When2Buy's historical U.S. options
data requirements, prepared for external handoff discussion with Bitget.
Its public canonical URL is https://options-data.when2buy.ai/.

**All example data in this repository is synthetic and illustrative.** No
row here is real market data, a real quote, a real trade, or investment
advice. Values were hand-designed to be internally consistent (bid ≤ ask,
put/call delta parity, referential integrity across files) around one
fictional example: a SPY 0DTE iron condor on 2026-07-29.

## Viewing the site

Open `index.html` directly in a browser, or serve it locally:

```bash
python3 -m http.server 8000
# then visit http://localhost:8000/
```

No build step, no external JS/CSS dependencies, no network calls at runtime.

## Layout

```
index.html            Site content (bilingual, Chinese-first / English labels)
css/styles.css         Styling: responsive layout, sticky nav, print styles
js/app.js              Interactive visualizations + nav/copy/print behavior
js/data.js             Auto-generated JS mirror of the sample dataset (used by charts)
data/
  sample_contracts.csv         Contract master/reference (20 rows: 10 strikes x C/P)
  sample_quotes.csv            NBBO quote events for the 4 iron-condor legs (20 rows)
  sample_trades.csv            Entry + exit trade prints for the 4 legs (8 rows)
  sample_chain_snapshot.csv    Full chain snapshot at 09:35 America/New_York (20 rows)
  sample_greeks.csv            Greeks/IV for the full chain at the same snapshot (20 rows)
  sample_underlying_bars.csv   SPY 1-minute OHLCV bars, 09:30-09:39 ET (10 rows)
  sample_manifest.json         Immutable manifest: dataset_version, schema_version, SHA-256 per file
  data-spec.json               Machine-readable data dictionary for all 8 data products
scripts/generate_data.py       Regenerates every data/ CSV/JSON + js/data.js deterministically
```

## Regenerating the sample data

```bash
python3 scripts/generate_data.py
```

This rewrites all six CSVs, `js/data.js`, and `sample_manifest.json` (including
fresh SHA-256 checksums) from the single source-of-truth tables at the top of
the script. After regenerating, re-append the `data-spec.json` checksum into
the manifest if that file also changed:

```bash
python3 -c "
import json, hashlib
m = json.load(open('data/sample_manifest.json'))
h = hashlib.sha256(open('data/data-spec.json','rb').read()).hexdigest()
m['files'] = [f for f in m['files'] if f['name'] != 'data-spec.json'] + [
    {'name': 'data-spec.json', 'product': 'machine_readable_schema', 'row_count': None, 'sha256': h}
]
json.dump(m, open('data/sample_manifest.json','w'), indent=2)
"
```

## Scope of this draft

This is a **requirements and standard proposal**, not a data delivery. It
exists to align with Bitget on: coverage (P0/P1/P2), exact schemas, delivery
format, quality SLAs, and open questions — see `index.html` sections 9–10.