QuantCandle API: Real-Time Stationary ML Features

Target Asset: Bitcoin (BTC/USDT)

Update Frequency: 1-Minute Candles (Real-Time)

Endpoint: /candles/

This API serves data generated by the quantcandle-engine.

Overview

The QuantCandle API provides a live, pre-processed feature set designed specifically for machine learning models (LSTMs, Transformers, XGBoost). Unlike standard exchange APIs that return raw price data, QuantCandle delivers scale-invariant, stationary, and homoscedastic features.

This removes the need for complex client-side preprocessing, preventing model bias toward specific price levels and ensuring your bot is ready to infer the moment a candle closes.

Built With

This project is part of a decoupled system designed for high-frequency data processing:

• API Layer (This Repository):

  • FastAPI: Provides the high-performance endpoint for data retrieval.
  • SQLAlchemy (Async): Manages non-blocking database sessions to serve processed candles.
  • Uv: Used for lightning-fast dependency management and environment isolation.

• Data Engine (External Backend):

  • A dedicated Websocket Client that consumes raw exchange feeds.
  • Uses Pandas and NumPy for real-time feature engineering (calculating PPO, Parkinson Volatility, etc.).
  • Writes processed, ML-ready features to the shared database every minute.

---

API Tier Limits

Plan	Max Candles per Request	Target Use Case
FREE	100	Prototyping & Live Testing
PREMIUM	1,000	Deep Backtesting & Heavy Inference

---

Feature Dictionary

All financial features are Robust Scaled (Median=0, IQR=1) or Arcsinh-transformed to ensure stationarity across different market regimes.

1. Targets & Volatility

• log_returns: Continuous compounded returns, standardized.
• parkinson_volatility: High-efficiency volatility estimator using the High-Low range.
• bbands: Relative width of Bollinger Bands (measures volatility expansion/contraction).

2. Market Geometry

• log_upper/lower_wick: Scale-invariant wick length using log-price differentials.
• ibs (Internal Bar Strength): Position of the Close relative to the High-Low range [Bounded 0, 1].
• imbalance: Measures market aggressiveness via Taker Buy/Sell volume ratio.

3. Momentum & Trend (Naturally Stationary)

• ppo_line/signal/hist: Percentage Price Oscillator. A normalized version of MACD that remains stationary regardless of BTC price level.

4. Liquidity Flow

• relative_volume: Current volume normalized by a 200-period rolling mean.
• relative_taker_buy_volume: Taker buy volume relative to recent average activity.

5. Temporal & Cyclical Encoding

To preserve continuity (ensuring 23:59 is recognized as "close" to 00:00), time is decomposed into sine/cosine pairs:

• Cyclical Time: minute, hour, and day sin/cos pairs.
• Bitcoin Cycle: halving sin/cos representing the ~4-year supply shock cycle.

---

Quick Start (Python)

While the API logic and data are hosted on a high-performance Oracle Cloud VPS, the service is proxied through RapidAPI for secure key management and subscription handling. Your user tier is automatically detected by the server via the X-RapidAPI-Subscription header injected by the RapidAPI proxy.

import requests

url = "https://quantcandle-data.p.rapidapi.com/candles/"

params = {"n_candles": 100}

headers = {
    "X-RapidAPI-Key": "PERSONAL KEY",
    "X-RapidAPI-Host": "quantcandle-data.p.rapidapi.com"
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

---

Integration Note

While financial markets are inherently non-stationary, these features have been rigorously transformed to exhibit a stable mean and bounded range. This effectively removes price-level bias while retaining the structural variance changes required for high-frequency algorithmic trading.