Skip to content

Core Concepts

Symbol format

HypQuant uses canonical symbols in the form BASE-QUOTE:

Exchange Exchange format HypQuant symbol Notes
Hyperliquid BTC BTC-USDC Perp, quote asset is USDC
Hyperliquid ETH ETH-USDC Perp
Hyperliquid kPEPE kPEPE-USDC Fractional perp — 1 contract = 1000 PEPE
Binance BTCUSDT BTC-USDT Spot, quote asset is USDT
Binance ETHUSDT ETH-USDT Spot

See Symbols for the full list.

Timestamps

All timestamps in HypQuant are UTC, open-time of the candle.

  • A 1h candle with time = 2024-01-15T14:00:00Z represents the period [14:00, 15:00).
  • The close time is implicit: time + timeframe_duration.
  • The API accepts start/end as ISO8601 strings or Unix milliseconds (as string).
# These are equivalent:
md.ohlcv("BTC-USDC", exchange="hyperliquid", timeframe="1h", start="2024-01-01T00:00:00Z")
md.ohlcv("BTC-USDC", exchange="hyperliquid", timeframe="1h", start="1704067200000")

# Datetime objects also work:
from datetime import datetime, timezone
md.ohlcv("BTC-USDC", exchange="hyperliquid", timeframe="1h",
         start=datetime(2024, 1, 1, tzinfo=timezone.utc))

Numeric precision

All numeric fields (prices, volumes, features, scores) are returned as strings in the JSON response — not floats. This preserves the full decimal precision stored in the database (NUMERIC with up to 8 decimal places).

The Python SDK automatically casts to Float64 when building the polars DataFrame:

df = md.ohlcv("BTC-USDC", exchange="hyperliquid", timeframe="1h", start="2024-01-01")
print(df.dtypes)
# [Datetime(time_unit='us', time_zone='UTC'), Float64, Float64, Float64, Float64, Float64]

If you call the HTTP API directly, cast the strings yourself:

import polars as pl
df = pl.DataFrame(response["data"]).with_columns(pl.col("close").cast(pl.Float64))

Data Quality Score (DQS)

Every asset/timeframe combination has a DQS in [0.0, 1.0]:

DQS = 0.30 × gap_rate_score
    + 0.25 × anomaly_score
    + 0.25 × consistency_score
    + 0.20 × freshness_score
Component Measures
gap_rate_score Fraction of expected candles that are present
anomaly_score Fraction of candles without outlier prices (|z| > 4σ)
consistency_score How close the spot/perp basis is to zero (< 0.5% = efficient)
freshness_score How recent the latest candle is vs. the SLA for that timeframe

A DQS ≥ 0.95 is suitable for production strategies. Values below 0.80 indicate data quality issues that may affect backtest results.

Gap policy

When the exchange returns missing candles, HypQuant applies one of two policies:

Gap size Policy
1–2 missing candles Forward-fill the previous close
≥ 3 missing candles Leave as absent; record in data_gaps table

The gap_rate_score reflects how many candles were expected vs. actually received (after fill). See Data Cleaning Decisions for the full policy with real examples.

Features

Features are pre-computed and stored per (exchange, symbol, timeframe). They are computed in Rust using polars and validated against pandas-ta as reference.

  • Technical features (RSI, MACD, BBands, ATR, VWAP) use OHLCV timeframes.
  • Funding features (funding_norm, funding_cumulative_*, premium_pct) use the special timeframe = "funding" — one row per hour, keyed to the funding event timestamp.

See the full Features Catalogue.