Developers

API Reference

Comprehensive documentation for the rlx-search HTTP API. Manage datasets, compute pattern matches, run ANN searches, and train RL agents.

Market Regimes API

Endpoints for detecting and analyzing market regimes (e.g., Bull, Bear, High Volatility) to switch agent strategies.

Quick Access

For standard Grid Trading analysis (Regime + Volatility + Probabilities), use the Grid Analysis Endpoint (/api/patterns/grid). It automatically handles data fetching and returns a simplified regime classification.

GET/api/rl/regimes

Get Regimes Catalog

Returns the list of all defined market regimes available in the system.

Example Request

POST/api/rl/regimes

Detect Current Regime

Analyzes the provided market state (price vector) and returns a probability distribution of which regime it belongs to.

Example Request

Parameter: currentState OR timestamp

You can provide the market state in two ways:

  • currentState: An array of raw prices (e.g., `[42000, 42100, ...]`). Use this for live trading or custom data.
  • timestamp: A Unix timestamp (ms). The system will look up the historical price vector ending at this time from its database. Use this for backtesting or analysis.

Alternative Request (using timestamp):

Interpreting the Response
  • frequency (0.0 - 1.0)
    The probability or confidence. 0.65 means "65% of historically similar situations behaved like this". It's your "Weather Forecast" confidence.
  • avgReturn
    The expected price change. If it's -0.02, the market usually stayed flat or drifted slightly down in this regime.
  • id
    The category tag. Use this to switch your bot's logic (e.g., STABLE_TRENDING vs HIGH_VOLATILITY).
How to Act

GET/api/rl/regimes/latest

Get Latest Regime

Returns the most recent market regime detected by the system for a given symbol and interval, using the latest available data.

Example Request

Why use this?

This is a convenience endpoint for live trading. Instead of manually fetching the latest candles and sending them to the POST endpoint, you can simply ask: "What is the regime right now?"

The system automatically fetches the latest price data from its internal store and runs the classification model.

New: Risk Analysis Metrics

The response now includes a riskAnalysis object with quantitative risk metrics derived from the matched historical patterns:

  • volatilityForecast: Expected standard deviation of returns.
  • valueAtRisk95: 95% VaR (the loss threshold that is not expected to be exceeded with 95% confidence).
  • downsideProbability: Probability of a negative return.
  • crashProbability: Probability of a severe drop (>5%).
  • kellyFraction: Recommended position size (0.0 to 1.0) based on the Kelly Criterion.
New: Transition Matrix

The response now explicitly identifies the currentRegime (based on recent history) and provides the probabilities of transitioning to other regimes in the regimes list.

Example: "Current regime is STABLE_TRENDING (confidence 0.95), but there is a 30% probability of transitioning to HIGH_VOLATILITY in the next 24 hours."

Strategic Map: The Market Weather Report

Markets aren't static; they have "seasons" or "regimes" (e.g., Bull, Bear, Crab, High Volatility). This endpoint lists the distinct states of the world that the system has identified.

The "Squad" Approach

Instead of training one "Super Agent" to handle everything (which is hard), use this to train a Squad of Specialists:

  • • Agent A: Expert at trending_up.
  • • Agent B: Expert at high_volatility.
  • • Agent C: Expert at sideways_chop.
Automated Clustering

You don't need to label these yourself. The system automatically clusters historical data based on statistical properties (Volatility, Trend Strength, Volume) and assigns IDs to these regimes.

Meta-Learning Architecture

Step 1: Use a simple classifier to detect the current regime ID.
Step 2: Hot-swap to the RL agent trained on that specific regime ID.
This "Divide and Conquer" strategy often outperforms monolithic models.

Real-World Case Study: The "Switching" Bot

Imagine you are trading Bitcoin. It behaves very differently during a "Crypto Winter" (2022) vs. a "Halving Bull Run" (2024). A single agent usually fails to capture both dynamics. Here is how you solve it with Regimes: