Export Hyperliquid OHLCV Candles to CSV

Build me a small script that exports Hyperliquid OHLCV candles from Dwellir into a CSV file.

Requirements:
- First check whether the `dwellir` CLI is installed.
- If it is not installed, recommend installing it with one of these options:
  - `brew tap dwellir-public/homebrew-tap && brew install dwellir`
  - `curl -fsSL https://raw.githubusercontent.com/dwellir-public/cli/main/scripts/install.sh | sh`
- After installation, ask me to authenticate it by running `dwellir auth login`.
- Check authentication with `dwellir auth status`.
- Get an enabled API key with `dwellir keys list --toon`. If there are multiple good candidates, ask me which key to use.
- Use the Dwellir Hyperliquid OHLCV REST endpoint.
- Export one market and one interval at a time.
- Treat the data as sparse: if a bucket returns 404, skip it rather than fabricating a candle.
- The OHLCV archive starts at `2025-07-27T08:00:00Z`.
- Iterate bucket-open timestamps between a start and end time.
- Support `1s`, `1m`, and `5m`.
- Write a CSV with columns: market, interval, bucket_start, open, high, low, close, volume, trades_count, vwap.
- Show me how to run the script for BTC 1m candles over a chosen date range.

pip install requests

dwellir auth login
dwellir keys list --toon

brew tap dwellir-public/homebrew-tap
brew install dwellir

GET https://api-hyperliquid-ohlcv.n.dwellir.com/YOUR_API_KEY/v1/candles

import csv
import sys
from datetime import datetime, timedelta, timezone

import requests


STEP_BY_INTERVAL = {
    "1s": timedelta(seconds=1),
    "1m": timedelta(minutes=1),
    "5m": timedelta(minutes=5),
}


def parse_utc(value: str) -> datetime:
    return datetime.fromisoformat(value.replace("Z", "+00:00")).astimezone(timezone.utc)


def format_utc(value: datetime) -> str:
    return value.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")


def iter_bucket_starts(start: datetime, end: datetime, step: timedelta):
    current = start
    while current <= end:
        yield current
        current += step


def fetch_candle(api_key: str, market: str, interval: str, bucket_start: datetime):
    response = requests.get(
        f"https://api-hyperliquid-ohlcv.n.dwellir.com/{api_key}/v1/candles",
        params={
            "market": market,
            "interval": interval,
            "time": format_utc(bucket_start),
        },
        timeout=30,
    )

    if response.status_code == 404:
        return None

    response.raise_for_status()
    return response.json()


def export_csv(api_key: str, market: str, interval: str, start: str, end: str, output_path: str):
    if interval not in STEP_BY_INTERVAL:
        raise ValueError(f"unsupported interval: {interval}")

    start_dt = parse_utc(start)
    end_dt = parse_utc(end)
    step = STEP_BY_INTERVAL[interval]

    with open(output_path, "w", newline="") as handle:
        writer = csv.DictWriter(
            handle,
            fieldnames=[
                "market",
                "interval",
                "bucket_start",
                "open",
                "high",
                "low",
                "close",
                "volume",
                "trades_count",
                "vwap",
            ],
        )
        writer.writeheader()

        for bucket_start in iter_bucket_starts(start_dt, end_dt, step):
            candle = fetch_candle(api_key, market, interval, bucket_start)
            if candle is None:
                continue
            writer.writerow(candle)


if __name__ == "__main__":
    if len(sys.argv) != 7:
        raise SystemExit(
            "usage: python export_ohlcv_csv.py <API_KEY> <MARKET> <INTERVAL> <START> <END> <OUT_CSV>"
        )

    _, api_key, market, interval, start, end, output_path = sys.argv
    export_csv(api_key, market, interval, start, end, output_path)

python export_ohlcv_csv.py \
  YOUR_API_KEY \
  BTC \
  1m \
  2026-03-30T00:00:00Z \
  2026-03-30T23:59:00Z \
  btc-1m-2026-03-30.csv

python export_ohlcv_csv.py \
  YOUR_API_KEY \
  ETH \
  5m \
  2026-03-01T00:00:00Z \
  2026-03-07T23:55:00Z \
  eth-5m-2026-03-01-to-2026-03-07.csv