Export Hyperliquid OHLCV Candles to Parquet

Build me a small script that exports Hyperliquid OHLCV candles from Dwellir into a Parquet 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 Parquet file 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 pyarrow

dwellir auth login
dwellir keys list --toon

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

import sys
from datetime import datetime, timedelta, timezone

import pyarrow as pa
import pyarrow.parquet as pq
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_parquet(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]

    rows = []
    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
        rows.append(candle)

    table = pa.Table.from_pylist(rows, schema=pa.schema([
        ("market", pa.string()),
        ("interval", pa.string()),
        ("bucket_start", pa.string()),
        ("open", pa.string()),
        ("high", pa.string()),
        ("low", pa.string()),
        ("close", pa.string()),
        ("volume", pa.string()),
        ("trades_count", pa.int64()),
        ("vwap", pa.string()),
    ]))

    pq.write_table(table, output_path)


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

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

python export_ohlcv_parquet.py \
  YOUR_API_KEY \
  BTC \
  1m \
  2026-03-01T00:00:00Z \
  2026-03-30T23:59:00Z \
  btc-1m-march-2026.parquet

python export_ohlcv_parquet.py \
  YOUR_API_KEY \
  SOL \
  1s \
  2026-03-30T12:00:00Z \
  2026-03-30T12:59:59Z \
  sol-1s-2026-03-30T12.parquet

import pyarrow.parquet as pq

table = pq.read_table("btc-1m-march-2026.parquet")
print(table.schema)
print(table.slice(0, 5).to_pydict())

SELECT *
FROM 'btc-1m-march-2026.parquet'
ORDER BY bucket_start
LIMIT 5;