API Reference
Comprehensive documentation for the rlx-search HTTP API. Manage datasets, compute pattern matches, run ANN searches, and train RL agents.
Pattern Search & Analytics
GET/api/patterns
Basic Pattern Search
Returns query window data, per-match telemetry, and percentile forecasts.
Example Request
Core Engine: The "Time Machine"
This is the flagship endpoint. It answers the question: "When has the market looked exactly like this before?"
The Payload
- Query Series: The last
qcandles of the current price action. - Matches: An array of historical episodes (OHLCV) that are mathematically similar to the query.
- Cross-Asset Discovery: If
crossAsset=true, the engine searches across all indexed symbols (e.g., finding BTC patterns in ETH or SPY history). - Forecast: The weighted average path of what happened next in those historical episodes.
Visualization Guide
This data is designed to be plotted directly:
> Plot query as the main line.
> Overlay matches as faint "ghost lines".
> Plot forecast as a projection.
Pro Tip: The "Limit" Parameter
Use limit=5 for a clean chart with just the "Top 5" most identical scenarios. Use limit=100 if you want to calculate robust statistics (like probability cones) yourself on the client side.
GET/api/patterns/metrics
Pattern Metrics
Produces a full statistical digest for the current query window. Reuses the same analogue cohort as /api/patterns but skips raw series data.
Example Request
Analyst's Guide: The Executive Summary
Think of this endpoint as the "Executive Summary" of the market. While the main /api/patterns endpoint gives you the full story (including every single historical candle for charting), this endpoint gives you just the conclusion.
Why use it?
Bandwidth & Speed. If you are building a dashboard with 50 tickers, you don't want to download megabytes of chart data. You just want to know: "Is it Bullish or Bearish?"
What's inside?
- • Forecast: The aggregated future path (p50).
- • Probabilities: % chance of price going Up vs Down.
- • Volatility: Expected range for the next N bars.
- • Smart Exit Levels: Probabilistic SL/TP targets derived from history.
Integration Tip
Use this for Watchlist Widgets or Screeners. It performs the exact same heavy calculation as the main search (finding similar patterns) but returns a lightweight JSON response (~1KB) instead of a heavy one.
GET/api/patterns/signals
Live Signals
Returns the latest high-probability signals discovered by the background scanner.
Example Request
Background Scanner: The "Signal Hunter"
The server runs a background process that continuously monitors all active symbols and intervals. It looks for patterns that historically resulted in a strong directional move.
How it works
- • Scan Cycle: Every 5 minutes, it checks the latest price action for all indexed assets.
- • Probability Threshold: Signal generated only if
up_probis > 70% (Long) or < 30% (Short). - • Persistence: Signals are saved to the database and can be retrieved via this endpoint.
Integration
Use this endpoint to power Push Notifications, Telegram Alerts, or a "Live Signals" dashboard widget.
GET/api/patterns-recalc
Historical Pattern Replay
Allows 'Time Travel' by re-calculating pattern matches for a specific historical offset without re-downloading the dataset.
Example Request
Interactive Exploration: "Time Travel"
This endpoint powers the interactive chart exploration. It lets you click on any candle in the past and ask: "What did the AI see at THIS exact moment?"
Key Parameters
- start: The integer offset (index) of the candle to analyze.
- windowStartTs: (Optional) Restrict search to a specific time range.
Use Cases
• Manual Backtesting: Visually verify past signals.
• Debugging: Understand why a forecast was made.
• Data Collection: Find examples of specific setups.
GET/api/patterns/grid
Grid Trading Stats
Provides grid-trading guidance (sigma levels, terminal percentiles, price zone, recommendation, and confidence score).
Example Request
Trader's Guide: How to use this data
This endpoint is built specifically for Grid Bots and Mean Reversion strategies. Instead of guessing support and resistance, it uses the behavior of similar historical patterns to calculate the statistical "playing field" for the next N candles.
1. The Range (Sigma Levels)
- 1σ (68%): The "Noise Zone". Prices mostly fluctuate here. Good for tight scalping grids.
- 2σ (95%): The "Reversal Zone". If price hits these bands, it is statistically overextended. Ideal for setting Grid Low/High limits.
2. The Targets (Percentiles)
- p50 (Median): The "Fair Value". Prices tend to revert to this level over time.
- p10 / p90: The Extremes. Only 10% of similar historical scenarios went beyond these points.
Strategy Tip
If recommendation is LONG, the current price is near the bottom of the historical range. Consider setting your Grid Low at sigma_2_lower and your Take Profit near p50.
POST/api/patterns/batch
Batch Search
Run multiple searches in a single request.
Example Request
Developer's Guide: High-Frequency & Multi-Asset
This endpoint is critical for production trading systems. Instead of opening 10 separate HTTP connections to check 10 different assets (which adds latency), you send a single "manifest" of requests.
Multi-Timeframe Confluence
A strong signal often appears across multiple timeframes simultaneously. Use batching to query BTCUSDT on 15m, 1h, and 4h intervals in one go. If all three return bullish forecasts, confidence increases significantly.
Portfolio Scanning
Monitor your entire watchlist (e.g., Top 20 coins) in a single heartbeat. The server processes these in parallel, returning a synchronized snapshot of the entire market state.
Performance Tip
Keep batch sizes under 50 requests for optimal latency. The results are returned in the same order as the request array, making it easy to map responses back to your internal tickers.