# 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