managing-apps/SYNTH_API_INTEGRATION.md

Synth API Integration - Technical Documentation

Overview

The Synth API integration provides probabilistic price forecasting capabilities for trading signal validation using AI-powered predictions from Mode Network's Synth Subnet. The system employs a sophisticated probability-weighted confidence calculation that prioritizes actual trading probabilities over theoretical position sizing metrics.

Implementation Architecture

Service Overview

The Synth API integration is implemented through the SynthPredictionService class, which serves as the central orchestrator for all probabilistic forecasting operations. The service provides MongoDB-backed caching, comprehensive signal validation, and real-time risk assessment capabilities.

Key Dependencies

• ISynthApiClient: Handles communication with Mode Network's Synth Subnet API
• ISynthRepository: Manages MongoDB persistence for prediction caching and leaderboard data
• ILogger: Provides detailed logging for debugging and monitoring

Supported Assets

Currently supports BTC and ETH with extensible architecture for additional cryptocurrencies.

Timeframe-Specific Configuration

The system automatically optimizes API calls based on trading timeframes due to Synth API limitations (only supports 5-minute and 24-hour increments):

Short timeframes (1m, 5m, 15m, 30m):

• Uses 5-minute time increments with 4-hour prediction horizons
• Updates cache every 2 minutes for rapid market changes

Medium timeframes (1h):

• Uses 5-minute time increments with 12-hour prediction horizons
• Updates cache every 5 minutes for balanced responsiveness

Long timeframes (4h, 1d):

• Uses 24-hour time increments with 48-hour prediction horizons
• Updates cache every 15 minutes for stability

Caching Strategy

Two-Tier MongoDB Caching System

1. Leaderboard Caching

• Caches top miner rankings to avoid repeated API calls
• Separate caching for live vs backtest scenarios
• Uses structured cache keys incorporating asset, time increment, and scenario type

2. Individual Prediction Caching

• Stores detailed price path predictions per miner
• Enables partial cache hits (fetch only missing miners)
• Automatic cache invalidation based on timeframe-specific durations

Intelligent Cache Management

The system optimizes performance by identifying which miner predictions are already cached and fetching only the missing data, then combining cached and fresh predictions for complete analysis.

Signal Validation Workflow

Primary Validation Method: ValidateSignalAsync

Input Processing:

1. Extracts money management settings (SL/TP percentages)
2. Calculates dynamic price thresholds based on position direction
3. Determines appropriate time horizon (24 hours for signal validation)

Price Threshold Calculation: For LONG positions, the system calculates stop loss prices below current price and take profit prices above. For SHORT positions, this is reversed - stop loss prices above current price and take profit prices below.

Probability Analysis:

• Retrieves cached or fresh predictions from top 10 miners
• Calculates probability of reaching each price threshold
• Analyzes directional movement based on position type

Comprehensive Scoring:

• Calculates Expected Monetary Value (EMV)
• Applies Kelly Criterion analysis
• Computes Expected Utility Theory metrics
• Generates confidence score using multi-factor algorithm

Multi-Factor Confidence Scoring

Three-Component Scoring System

1. Configuration-Aware Scoring (50% weight)

• Adverse probability pressure analysis
• Kelly fraction alignment with risk tolerance
• Risk aversion compatibility assessment
• Configuration consistency bonuses

2. Threshold Alignment Scoring (30% weight)

• Kelly minimum/maximum threshold compliance
• Favorable probability threshold achievement
• Kelly multiplier philosophy alignment

3. Probability Scoring (20% weight)

• Take Profit probability assessment
• Stop Loss risk evaluation
• TP/SL ratio analysis
• Win/Loss ratio consideration
• Probability dominance bonuses

Conditional Pass-Through System

For signals exceeding adverse probability thresholds, the system evaluates 8 redeeming qualities:

1. Significant Kelly edge (>2x minimum threshold AND >5%)
2. Meaningful Expected Monetary Value (>$100)
3. Excellent TP/SL ratio (≥2.0)
4. Positive Expected Utility (>1.0)
5. TP probability dominance (TP > SL × 1.5)
6. Moderate threshold breach (SL/Threshold ≤ 1.25)
7. Strong Kelly assessment indicators
8. Favorable Win/Loss ratio (≥2.0)

Pass-through requires 75% of factors to be positive, resulting in constrained LOW confidence.

Risk Assessment Implementation

Position Risk Assessment: AssessPositionRiskAsync

Pre-Position Risk Check:

• Estimates liquidation price based on money management
• Calculates 24-hour liquidation probability
• Blocks positions exceeding MaxLiquidationProbability (default 10%)

Ongoing Position Monitoring: MonitorPositionRiskAsync

Real-time Risk Monitoring:

• 6-hour liquidation probability assessment
• Warning threshold at 20% risk
• Auto-close threshold at 50% risk (if dynamic SL enabled)
• Generates actionable risk notifications

Backtest vs Live Trading Support

Historical Data Integration

For backtesting scenarios, the system retrieves historical leaderboard data from 30 minutes before the signal date and fetches corresponding historical predictions. This ensures accurate simulation of what information would have been available at the time of the original signal.

Cache Separation

• Separate cache keys for backtest vs live scenarios
• Historical leaderboard and prediction storage
• Automatic fallback to current data if historical unavailable

Probability Calculation Engine

Path Aggregation Algorithm

The probability calculation engine aggregates simulation paths from all selected miners and analyzes each path for target price crossings within the specified time horizon. The system performs directional analysis based on position type (LONG/SHORT) and calculates the final probability as the percentage of paths that cross the target price.

Process:

1. Aggregates simulation paths from all selected miners
2. Analyzes each path for target price crossings within time horizon
3. Directional analysis based on position type (LONG/SHORT)
4. Calculates probability as: (Paths Crossing Target) / (Total Paths)

Performance Optimization Features

Intelligent API Usage

• Partial cache hits reduce API calls by up to 90%
• Timeframe-specific configurations minimize unnecessary data
• Batch processing for multiple threshold calculations

Memory Management

• MongoDB persistence prevents RAM saturation
• Automatic cleanup of expired cache data
• Efficient data structures for large prediction datasets

Error Handling & Resilience

• Graceful degradation on API failures
• Fallback confidence scoring when predictions unavailable
• Comprehensive error logging with context preservation

Core Calculation Methodology

Confidence Score Calculation

The system uses a weighted composite scoring approach:

Standard Signals (within adverse threshold):

Confidence Score = (ConfigurationScore × 50%) + (ThresholdAlignmentScore × 30%) + (ProbabilityScore × 20%)

Over-Threshold Signals (conditional pass-through):

Constrained Score = (KellyScore × 25%) + (TpSlScore × 25%) + (EMVScore × 20%) + (UtilityScore × 15%) + (RiskPenalty × 15%)
Final Score = min(Constrained Score × 0.75, LowThreshold + 0.05)

Sigmoid Scoring Functions

All scoring components use continuous sigmoid functions for smooth transitions:

MapToScore (higher is better):

Score = 1 / (1 + e^(-steepness × (value - midpoint)))

MapToInverseScore (lower is better):

Score = 1 / (1 + e^(steepness × (value - midpoint)))

Risk Management Parameters

Core Signal Filtering Parameters

Parameter	Range	Default	Purpose
AdverseProbabilityThreshold	5% - 50%	20%	Maximum acceptable Stop Loss probability
FavorableProbabilityThreshold	10% - 70%	30%	Minimum required Take Profit probability
SignalValidationTimeHorizonHours	1 - 168	24	Time horizon for probability calculations

Expected Utility Theory Parameters

Parameter	Range	Default	Purpose
RiskAversion	0.1 - 5.0	1.0	Portfolio utility risk aversion coefficient
UseExpectedUtility	boolean	true	Enable Expected Utility calculations

Kelly Criterion Parameters

Parameter	Range	Default	Purpose
KellyMinimumThreshold	0.5% - 10%	1%	Minimum Kelly fraction for favorable signals
KellyMaximumCap	5% - 50%	25%	Maximum Kelly fraction (safety cap)
KellyFractionalMultiplier	10% - 100%	100%	Kelly sizing multiplier (fractional Kelly)
UseKellyCriterion	boolean	true	Enable Kelly position sizing recommendations

Position Management Parameters

Parameter	Range	Default	Purpose
MaxLiquidationProbability	5% - 30%	10%	Maximum acceptable liquidation risk
PositionMonitoringTimeHorizonHours	1 - 48	6	Monitoring frequency for open positions
PositionWarningThreshold	10% - 40%	20%	Risk level for position warnings
PositionAutoCloseThreshold	30% - 80%	50%	Risk level for automatic position closure

Risk Tolerance Profiles

Conservative Profile

AdverseProbabilityThreshold = 15%     // Stricter blocking threshold
FavorableProbabilityThreshold = 40%   // Higher TP requirements
RiskAversion = 2.0                    // More risk-averse utility calculation
KellyMinimumThreshold = 2%            // Higher Kelly minimum
KellyMaximumCap = 15%                 // Lower Kelly maximum
KellyFractionalMultiplier = 50%       // Half-Kelly sizing
MaxLiquidationProbability = 8%        // Stricter position risk
PositionWarningThreshold = 15%        // Earlier warnings
PositionAutoCloseThreshold = 35%      // Earlier auto-close

Confidence Thresholds: High ≥80%, Medium ≥60%, Low ≥40%

Moderate Profile (Default)

AdverseProbabilityThreshold = 20%     // Balanced blocking threshold
FavorableProbabilityThreshold = 30%   // Reasonable TP requirements
RiskAversion = 1.0                    // Neutral utility calculation
KellyMinimumThreshold = 1%            // Standard Kelly minimum
KellyMaximumCap = 25%                 // Standard Kelly maximum
KellyFractionalMultiplier = 100%      // Full Kelly sizing
MaxLiquidationProbability = 10%       // Standard position risk
PositionWarningThreshold = 20%        // Standard warnings
PositionAutoCloseThreshold = 50%      // Standard auto-close

Confidence Thresholds: High ≥75%, Medium ≥55%, Low ≥35%

Aggressive Profile

AdverseProbabilityThreshold = 30%     // Permissive blocking threshold
FavorableProbabilityThreshold = 25%   // Lower TP requirements
RiskAversion = 0.5                    // Risk-seeking utility calculation
KellyMinimumThreshold = 0.5%          // Lower Kelly minimum
KellyMaximumCap = 40%                 // Higher Kelly maximum
KellyFractionalMultiplier = 100%      // Full Kelly sizing
MaxLiquidationProbability = 15%       // Higher position risk tolerance
PositionWarningThreshold = 30%        // Later warnings
PositionAutoCloseThreshold = 70%      // Later auto-close

Confidence Thresholds: High ≥70%, Medium ≥45%, Low ≥25%

Detailed Scoring Algorithms

1. Configuration-Aware Scoring (50% Weight)

Adverse Probability Pressure (30% of ConfigScore):

• Conservative: Penalizes at 40% of threshold, steepness 6.0
• Moderate: Penalizes at 60% of threshold, steepness 4.0
• Aggressive: Penalizes at 80% of threshold, steepness 3.0

Kelly Alignment Scoring (25% of ConfigScore):

• Conservative: Smooth curves for Kelly 2%-8%, gradual penalty >15%
• Moderate: Broad scoring range, penalty for <1% or >15%
• Aggressive: Rewards higher Kelly, less penalty for extremes

Risk Aversion Alignment (25% of ConfigScore):

• Conservative: Lenient utility requirements (midpoint -0.2, steepness 3.0)
• Moderate: Balanced utility assessment (midpoint 0.0, steepness 5.0)
• Aggressive: Higher utility demands (midpoint 0.2, steepness 8.0)

Configuration Consistency Bonus (20% of ConfigScore):

• Conservative: Bonus for SL <12%, Kelly <6%, TP/SL >1.5
• Moderate: Bonus for SL <16%, Kelly >3%, TP/SL >1.5
• Aggressive: Bonus for Kelly >8%, TP/SL >2.0, positive EMV

2. Threshold Alignment Scoring (30% Weight)

Kelly Threshold Compliance (50% of ThresholdScore):

• Kelly Minimum Score: Sigmoid scoring if below minimum threshold
• Kelly Maximum Score: Inverse sigmoid penalty if above maximum cap

Favorable Probability Threshold (30% of ThresholdScore):

• Direct comparison to FavorableProbabilityThreshold
• Sigmoid scoring for partial compliance

Kelly Multiplier Philosophy Alignment (20% of ThresholdScore):

• Fractional Kelly (<100%): Rewards lower SL probability (midpoint 15%, steepness 8.0)
• Full Kelly (≥100%): Rewards higher TP/SL ratio (midpoint 1.8, steepness 5.0)

3. Probability Scoring (20% Weight)

Take Profit Probability (30% of ProbScore):

• Midpoint: 60% TP probability
• Steepness: 4.0 for sensitivity around realistic ranges

Stop Loss Risk Assessment (30% of ProbScore):

• Uses 75% of adverse threshold as reference point
• Inverse scoring (lower SL probability = higher score)
• Steepness: 8.0 for sharp penalty above threshold

TP/SL Ratio Assessment (25% of ProbScore):

• Midpoint: 1.5 (realistic good ratio)
• Steepness: 3.0 for balanced sensitivity

Win/Loss Ratio (10% of ProbScore):

• Midpoint: 1.5 (favorable ratio)
• Steepness: 3.0

Probability Dominance Bonus (5% of ProbScore):

• TP/SL ratio scaled by factor of 2
• Binary scoring for extreme cases

Conditional Pass-Through System

Redeeming Qualities Assessment (8 Factors)

Signals exceeding the adverse probability threshold can still receive LOW confidence if meeting 75% of these criteria:

1. Significant Kelly Edge: Kelly > (2 × KellyMinimumThreshold) AND Kelly > 5%
2. Meaningful Expected Value: EMV > $100
3. Excellent TP/SL Ratio: TP/SL ≥ 2.0
4. Positive Expected Utility: ExpectedUtility > 1.0
5. TP Probability Dominance: TP > (SL × 1.5)
6. Moderate Threshold Breach: SL/Threshold ≤ 1.25
7. Strong Kelly Assessment: Contains "Strong", "Exceptional", or "Extraordinary"
8. Favorable Win/Loss Ratio: Win/Loss ≥ 2.0

Constrained Scoring for Pass-Through

Component Weights:

• Kelly Score: 25% (capped at 0.8)
• TP/SL Score: 25% (capped at 0.7)
• EMV Score: 20% (binary: >0 = 0.6, ≤0 = 0.2)
• Utility Score: 15% (binary: >0 = 0.5, ≤0 = 0.2)
• Risk Penalty: 15% (inverse sigmoid on threshold overage)

Final Score Calculation:

Constrained Score × 0.75 penalty, capped at (LowThreshold + 0.05)

API Time Horizon Configuration

Timeframe-Based Settings

Short Timeframes (1m, 5m, 15m, 30m):

• Time Increment: 300 seconds (5 minutes)
• Default Horizon: 14,400 seconds (4 hours)
• Cache Duration: 2 minutes

Medium Timeframes (1h):

• Time Increment: 300 seconds (5 minutes)
• Default Horizon: 43,200 seconds (12 hours)
• Cache Duration: 5 minutes

Long Timeframes (4h, 1d):

• Time Increment: 86,400 seconds (24 hours)
• Default Horizon: 172,800 seconds (48 hours)
• Cache Duration: 15 minutes

Price Threshold Calculations

LONG Positions:

Stop Loss Price = Current Price × (1 - StopLossPercentage)
Take Profit Price = Current Price × (1 + TakeProfitPercentage)

SHORT Positions:

Stop Loss Price = Current Price × (1 + StopLossPercentage)
Take Profit Price = Current Price × (1 - TakeProfitPercentage)

Probability Calculation Method

The system aggregates simulation paths from top-performing miners and calculates the percentage of paths that cross the target price within the specified time horizon:

Probability = (Paths Crossing Target) / (Total Simulation Paths)

Path Analysis:

• Uses top 10 miners by default (configurable)
• Aggregates all simulation paths from selected miners
• Directional analysis based on position type (LONG/SHORT)
• Time-bounded evaluation within specified horizon

Parameter Optimization Guidelines

For Different Market Conditions

High Volatility Markets:

• Increase AdverseProbabilityThreshold (25-35%)
• Decrease FavorableProbabilityThreshold (20-25%)
• Lower KellyMaximumCap (15-20%)
• Shorter SignalValidationTimeHorizonHours (12-18)

Low Volatility Markets:

• Decrease AdverseProbabilityThreshold (15-20%)
• Increase FavorableProbabilityThreshold (35-45%)
• Higher KellyMaximumCap (25-35%)
• Longer SignalValidationTimeHorizonHours (24-48)

Trending Markets:

• Use Aggressive profile
• Lower RiskAversion (0.5-0.8)
• Higher KellyFractionalMultiplier (85-100%)

Ranging Markets:

• Use Conservative profile
• Higher RiskAversion (1.5-2.5)
• Lower KellyFractionalMultiplier (50-75%)

Money Management Integration Impact

Tight SL/TP Ranges (< 2%):

• Use Aggressive thresholds (30-35% adverse)
• Higher probability granularity
• More frequent MEDIUM/LOW confidence levels

Standard SL/TP Ranges (2-5%):

• Use Moderate thresholds (20-25% adverse)
• Balanced confidence distribution
• Optimal for most trading strategies

Wide SL/TP Ranges (> 5%):

• Use Conservative thresholds (15-20% adverse)
• Lower probability values
• More reliable confidence signals

Performance Monitoring

Key Metrics to Track

Confidence Distribution:

• Target: 30% High, 40% Medium, 25% Low, 5% None
• Monitor for uniform distribution (indicates poor calibration)

Kelly Capping Frequency:

• Track percentage of signals with capped Kelly fractions
• High capping (>50%) may indicate overly aggressive signals

Expected Utility Trends:

• Monitor portfolio-level utility accumulation
• Negative trends indicate poor risk management

Pass-Through Analysis:

• Track conditional pass-through frequency
• Monitor success rate of LOW confidence signals

Calibration Validation

Probability Accuracy:

• Compare predicted vs. actual outcome frequencies
• Calibrate thresholds based on historical performance

Confidence Effectiveness:

• Track win rates by confidence level
• Validate that High > Medium > Low > None in performance

Risk Assessment Accuracy:

• Monitor false positive/negative rates for liquidation predictions
• Adjust MaxLiquidationProbability based on actual risk events