managing-apps/README-API.md

API Features

User Management (UserController)

• JWT Authentication: Secure user authentication using Web3 signatures
• Profile Management: Update agent name, avatar URL, and Telegram channel
• Current User Information: Retrieve authenticated user details

Authentication Flow

1. Sign message with Web3 wallet
2. Submit signed message to receive JWT token
3. Use JWT token for all subsequent API calls

Endpoints

• POST /User - Create JWT token with Web3 signature
• GET /User - Get current user information
• PUT /User/agent-name - Update agent name
• PUT /User/avatar - Update avatar URL
• PUT /User/telegram-channel - Update Telegram channel

Account Management (AccountController)

• Account Creation: Create trading accounts linked to user profiles
• Account Retrieval: Get all accounts or specific account by name
• Balance Monitoring: Retrieve real-time account balances
• GMX Integration: Get claimable fees summary from GMX contracts
• Account Deletion: Remove accounts from user profile

Endpoints

• POST /Account - Create new account
• GET /Account/accounts - Get all user accounts
• GET /Account/balances - Get account balances
• GET /Account - Get specific account by name
• GET /Account/{name}/gmx-claimable-summary - Get GMX claimable fees
• DELETE /Account - Delete account by name

Money Management (MoneyManagementController)

• Strategy Creation: Define risk management parameters (StopLoss, TakeProfit, position sizing)
• Strategy Updates: Modify existing money management configurations
• Strategy Retrieval: Access all strategies or specific strategy by name
• Strategy Deletion: Remove unused money management configurations

Endpoints

• POST /MoneyManagement - Create or update money management strategy
• GET /MoneyManagement/moneymanagements - Get all money management strategies
• GET /MoneyManagement - Get specific money management by name
• DELETE /MoneyManagement - Delete money management strategy

Scenarios & Indicators (ScenarioController)

Scenarios

• Build Scenarios: Combine multiple indicators into trading strategies
• Update Scenarios: Modify existing scenario configurations
• Scenario Management: Create, retrieve, update, and delete scenarios
• Loopback Period: Configure historical data lookback for scenario evaluation

Indicators

• Indicator Creation: Build custom technical indicators with specific parameters
• Indicator Updates: Modify existing indicator configurations
• Comprehensive Parameters: Support for period, multiplier, fast/slow periods, signal periods, etc.
• Indicator Types: Support for various technical indicators (MACD, RSI, EMA, SuperTrend, etc.)

Scenario Endpoints

• GET /Scenario - Get all scenarios for user
• POST /Scenario - Create new scenario
• PUT /Scenario - Update existing scenario
• DELETE /Scenario - Delete scenario by name

Indicator Endpoints

• GET /Scenario/indicator - Get all indicators for user
• POST /Scenario/indicator - Create new indicator
• PUT /Scenario/indicator - Update existing indicator
• DELETE /Scenario/indicator - Delete indicator by name

Available Indicators

Indicator	Type	Description	Parameters
RsiDivergence	Signal	Detects RSI divergence patterns where price and RSI move in opposite directions	Period (recommended: 4-6)
RsiDivergenceConfirm	Signal	Enhanced RSI divergence that waits for confirmation before triggering signals	Period (recommended: 4-6)
MacdCross	Signal	Triggers signals when MACD histogram crosses zero line	FastPeriods: 12, SlowPeriods: 26, SignalPeriods: 9
EmaCross	Signal	Triggers signals when price crosses EMA line	Period (recommended: 200)
EmaTrend	Trend	Returns trend signals based on price position relative to EMA	Period (recommended: 200)
SuperTrend	Signal	Triggers signals when price crosses SuperTrend indicator	Period: 10, Multiplier: 3
ChandelierExit	Signal	Exit strategy based on highest/lowest values over a period with ATR multiplier	Period: 22, Multiplier: 3
StochRsiTrend	Trend	Trend signals based on Stochastic RSI levels (>80% = Short, <20% = Long)	Period (recommended: 22)
Stc	Signal	Schaff Trend Cycle - signals when crossing 75% (Short) or 25% (Long) levels	CyclePeriods, FastPeriods, SlowPeriods
ThreeWhiteSoldiers	Signal	Candlestick pattern recognition for bullish reversal signals	Lookback Period: 3
LaggingStc	Signal	Enhanced STC with lagging mechanism for reduced false signals	CyclePeriods, FastPeriods, SlowPeriods
SuperTrendCrossEma	Signal	Combined indicator using both SuperTrend and EMA crossovers	SuperTrend Period/Multiplier + EMA Period
DualEmaCross	Signal	Dual EMA crossover system using fast and slow EMAs	FastPeriods, SlowPeriods

Signal Types

• Signal: Generates entry/exit signals for specific trading actions
• Trend: Provides directional trend information for position bias
• Context: Offers additional market context for decision making

Parameter Guidelines

• Period: Number of candles for calculation (higher = smoother, lower = more responsive)
• Multiplier: ATR multiplier for volatility-based indicators (higher = wider bands)
• Fast/Slow Periods: For dual-line indicators, fast reacts quickly, slow provides stability
• Cycle Periods: For oscillators, defines the cycle length for calculations

Bot Management (BotController)

Core Bot Operations

• Start Bots: Deploy bots with comprehensive configuration
• Stop/Restart Bots: Individual or bulk bot control
• Delete Bots: Remove bots and their associated data
• Configuration Updates: Real-time bot parameter updates without restart

Advanced Bot Features

• Manual Trading: Open/close positions manually
• Watch Mode: Signal-only mode without actual trading
• User Ownership: Security validation ensuring users only control their own bots
• Real-time Updates: Live bot status and performance monitoring

Flexible Configuration Options

Scenario Configuration:

• Saved Scenarios: Use ScenarioName to reference scenarios saved in database
• Dynamic Scenarios: Pass complete Scenario object directly without saving to database
• Dynamic scenarios are useful for testing custom configurations or one-time strategies

Money Management Configuration:

• Saved Strategies: Use MoneyManagementName to reference saved money management strategies
• Dynamic Strategies: Pass complete MoneyManagement object directly without saving
• Allows for custom risk parameters without cluttering the saved strategies list

Endpoints

• POST /Bot/Start - Start a new bot
• GET /Bot/Stop - Stop specific bot
• GET /Bot/Restart - Restart specific bot
• DELETE /Bot/Delete - Delete bot
• POST /Bot/stop-all - Stop all user bots
• POST /Bot/restart-all - Restart all user bots
• GET /Bot/ToggleIsForWatching - Toggle watch mode
• GET /Bot - Get all active bots
• POST /Bot/OpenPosition - Manually open position
• POST /Bot/ClosePosition - Manually close position
• PUT /Bot/UpdateConfig - Update bot configuration

TradingBotConfig Documentation

The TradingBotConfig class defines all configuration parameters for trading bots. Below are the available properties:

Required Properties

Property	Type	Description
AccountName	string	Name of the trading account to use
MoneyManagement	MoneyManagement	Risk management strategy configuration
Ticker	Ticker	Trading pair symbol (e.g., BTCUSDT)
Timeframe	Timeframe	Candle timeframe for analysis
IsForWatchingOnly	bool	If true, bot only sends signals without trading
BotTradingBalance	decimal	Initial trading balance for the bot
BotType	BotType	Type of trading bot behavior
IsForBacktest	bool	Whether this config is for backtesting
CooldownPeriod	int	Number of candles to wait before opening new position in same direction
MaxLossStreak	int	Maximum consecutive losses before requiring opposite direction signal (0 = no limit)
FlipPosition	bool	Whether the bot can flip positions
Name	string	Unique identifier/name for the bot
FlipOnlyWhenInProfit	bool	Only flip positions when current position is profitable (default: true)

Optional Properties

Property	Type	Description	Default
Scenario	Scenario	Scenario object with strategies (takes precedence over ScenarioName)	null
ScenarioName	string	Name of scenario to load from database	null
MaxPositionTimeHours	decimal?	Maximum hours a position can stay open before auto-close	null
CloseEarlyWhenProfitable	bool	Close position early when profitable (requires MaxPositionTimeHours)	false
UseSynthApi	bool	Enable Synth API for probabilistic price forecasts	false
UseForPositionSizing	bool	Use Synth predictions for position sizing adjustments	true
UseForSignalFiltering	bool	Use Synth predictions for signal filtering	true
UseForDynamicStopLoss	bool	Use Synth predictions for dynamic stop-loss/take-profit	true

Advanced Configuration Details

Time-Based Position Management:

• When MaxPositionTimeHours is set, positions are automatically closed after the specified time
• Only closes when position is in profit or at breakeven (never closes at a loss due to time)
• CloseEarlyWhenProfitable allows immediate closure when profitable instead of waiting full duration

Profit-Controlled Flipping:

• FlipOnlyWhenInProfit ensures safer trading by only flipping profitable positions
• Helps prevent cascading losses in volatile markets

Synth API Integration:

• UseSynthApi enables probabilistic price forecasting and risk assessment
• Sub-properties control specific Synth features (position sizing, signal filtering, dynamic stops)
• Provides AI-enhanced trading decisions when enabled

Scenario Configuration:

• Either provide a Scenario object directly or use ScenarioName to load from database
• Direct Scenario objects are useful for testing custom configurations without saving
• ScenarioName is typically used for live trading with saved scenarios

Money Management Configuration:

• Either provide a MoneyManagement object directly or use MoneyManagementName in the request
• Direct objects allow for one-time custom risk parameters
• Saved strategies via name reference are ideal for reusable configurations

Bot Configuration Parameters

Parameter	Description	Default
MaxPositionTimeHours	Maximum time (in hours) a position can stay open. Closes only when in profit/breakeven. Null = disabled	null
FlipOnlyWhenInProfit	Only flip positions when current position is profitable	true
CooldownPeriod	Number of candles to wait before opening new position in same direction	10
MaxLossStreak	Maximum consecutive losses before requiring opposite direction signal. 0 = no limit	0
CloseEarlyWhenProfitable	Close positions early when profitable (requires MaxPositionTimeHours)	false
BotTradingBalance	Initial trading balance for the bot	Required

Bot Types

The BotType enum in TradingBotConfig defines the following trading bot behaviors:

Type	Description
SimpleBot	Basic bot implementation for simple trading strategies
ScalpingBot	Opens positions and waits for cooldown period before opening new ones in same direction
FlippingBot	Advanced bot that can flip positions when opposite signals are triggered

Flipping Mode Configuration

The flipping behavior is controlled by several TradingBotConfig properties:

• BotType: Set to FlippingBot to enable position flipping capabilities
• FlipPosition: Boolean flag that enables/disables position flipping (automatically set based on BotType)
• FlipOnlyWhenInProfit: Safety feature that only allows flipping when current position is profitable (default: true)

How Flipping Works

FlippingBot Behavior:

1. Opens initial position based on scenario signals
2. Monitors for opposite direction signals from the same scenario
3. When opposite signal occurs:
   • If FlipOnlyWhenInProfit is true: Only flips if current position is profitable
   • If FlipOnlyWhenInProfit is false: Flips regardless of profit status
4. Closes current position and immediately opens new position in opposite direction
5. Continues this cycle for the duration of the bot's operation

ScalpingBot vs FlippingBot:

• ScalpingBot: Opens position → Waits for exit signal → Closes → Cooldown → Opens new position
• FlippingBot: Opens position → Monitors for opposite signals → Flips immediately (no cooldown between flips)

This configuration allows for more aggressive trading strategies while maintaining risk management through the profit-controlled flipping mechanism.

Backtesting (BacktestController)

Backtest Operations

• Run Backtests: Execute historical strategy testing with comprehensive parameters
• Retrieve Results: Access backtest results with complete configuration details
• Delete Backtests: Remove old backtest data
• Save/Load: Optional saving of backtest results for future reference

Enhanced Backtest Features

• Complete Configuration: Backtests include full TradingBotConfig for easy bot deployment
• Advanced Parameters: Support for all bot configuration parameters in backtests
• Date Range Testing: Flexible start/end date selection
• Money Management Integration: Test with specific money management strategies
• Watch Mode: Run backtests without executing trades (signal analysis only)

Flexible Configuration Options

Scenario Configuration for Backtests:

• Saved Scenarios: Use ScenarioName to reference scenarios saved in database
• Dynamic Scenarios: Pass complete Scenario object directly in the backtest request
• Dynamic scenarios are perfect for testing custom indicator combinations without saving them
• Allows rapid experimentation with different strategy configurations

Money Management Configuration for Backtests:

• Saved Strategies: Use MoneyManagementName to reference saved money management strategies
• Dynamic Strategies: Pass complete MoneyManagement object directly in the request
• Enables testing various risk parameters without cluttering saved strategies
• Ideal for optimization testing with different stop-loss/take-profit configurations

Endpoints

• GET /Backtest - Get all backtests for user
• GET /Backtest/{id} - Get specific backtest by ID
• DELETE /Backtest - Delete backtest by ID
• POST /Backtest/Run - Run new backtest

Backtest Parameters

• Exchange: Target exchange for historical data
• Ticker: Trading pair symbol
• Timeframe: Candle timeframe (1m, 5m, 15m, 1h, 4h, 1d, etc.)
• Date Range: Historical period for testing
• Initial Balance: Starting capital for backtest
• Advanced Config: All bot parameters (time limits, profit control, etc.)

RunBacktestRequest Structure

The backtest request supports both saved and dynamic configurations:

{
  "Config": {
    "ScenarioName": "MySavedScenario",  // OR pass Scenario object directly
    "Scenario": { /* full scenario object */ },
    "AccountName": "TestAccount",
    "Ticker": "BTCUSDT",
    "Timeframe": "OneHour",
    // ... other TradingBotConfig properties
  },
  "MoneyManagementName": "Conservative", // OR pass MoneyManagement object
  "MoneyManagement": { /* full money management object */ },
  "StartDate": "2024-01-01T00:00:00Z",
  "EndDate": "2024-02-01T00:00:00Z",
  "Balance": 10000,
  "Save": true
}

This flexibility allows for comprehensive strategy testing without requiring database saves for experimental configurations.

Market Data & Analytics (DataController)

Market Data

• Ticker Information: Available trading pairs with logos and metadata
• Candle Data: Historical OHLCV data for any timeframe
• Real-time Updates: Live price feeds via SignalR

Platform Analytics

• Strategies Statistics: Platform-wide bot performance metrics
• Top Strategies: Best performing strategies by ROI
• User Analytics: Individual user strategy performance
• Platform Summary: Comprehensive platform statistics with time filters
• Agent Balances: Historical balance tracking for users
• Best Agents: Leaderboard of top performing users

Endpoints

• POST /Data/GetTickers - Get available trading pairs with metadata
• GET /Data/Spotlight - Get market spotlight overview
• GET /Data/GetCandles - Get historical candle data
• GET /Data/GetStrategiesStatistics - Get platform-wide strategy statistics
• GET /Data/GetTopStrategies - Get top performing strategies
• GET /Data/GetUserStrategies - Get user's strategy details
• GET /Data/GetUserStrategy - Get specific user strategy
• GET /Data/GetPlatformSummary - Get comprehensive platform summary
• GET /Data/GetAgentBalances - Get agent balance history
• GET /Data/GetBestAgents - Get best performing agents leaderboard

Analytics Features

• Time Filters: 24H, 3D, 1W, 1M, 1Y, Total
• Performance Metrics: ROI, PnL, win rates, volume traded
• Caching: Optimized response times with intelligent caching
• Real-time Updates: Live performance tracking

Spotlight Data

• Market Overview: Comprehensive market analysis
• Strategy Performance: Cross-strategy performance comparison
• Volume Analysis: Trading volume statistics