# Research without a notebook (Python)

A small, reproducible study as a plain script: do hours with unusually large liquidations ("flushes") mark local
turning points? `research.py` joins the hourly liquidation series of a coin (`GET /liquidations/summary`) with its 1h
candles (`GET /candles/{coin}`), computes forward returns after 1, 4 and 24 hours and compares flush hours with all
hours. Standard library only (`csv`, `statistics`) plus the `blockmetric` SDK. It runs in a terminal, a cron job or
CI.

```bash
export BLOCKMETRIC_API_KEY=bm_live_...                  # create one on /account/api
export BLOCKMETRIC_BASE_URL=https://<domain>/api/v1
export PYTHONPATH=../../sdk/python                    # until the SDK is on PyPI

python research.py --coin BTC --days 30 --percentile 95
python research.py --coin ETH --days 14 --csv eth-liq-research.csv
```

Output (shape):

```
group                            hours  mean 1h   up 1h  mean 4h   up 4h mean 24h  up 24h
-----------------------------------------------------------------------------------------
all hours                          712   ...
long flush (>= $…)                  36   ...
short flush (>= $…)                 36   ...
```

The functions (`fetch`, `forward_returns`, `study`, `render`, `write_csv`) are importable, so the same code can feed a
notebook or a dashboard later. The window is capped by your plan's history (free key: 30 days; hours before
`coveredSince` are left out because not every venue was collected). Descriptive statistics over a short sample, not a
trading signal, not investment advice.