​
Execution API

The Execution API provides strategy evaluation against current market data. It supports stateful execution with position persistence, stop-loss/take-profit order management, and risk controls. Set persist=false for dry-run evaluation without affecting database state.

​
Base URL

https://api.mangrovedeveloper.ai/api/v1/execution

​
Endpoints

​
Evaluate Strategy by ID

POST /api/v1/execution/evaluate/{strategy_id} Evaluates a persisted strategy with current market data:
  1. Loads strategy with execution_config and execution_state
  2. Loads open positions and their orders from database
  3. Evaluates exit conditions (SL, TP, signals, time-based) for open positions
  4. Evaluates entry signals for new positions
  5. Returns order objects (existing SL/TP or new market orders)
ParameterTypeRequiredDescription
persistbooleanNoPersist orders and trades to database (default: true)
curl -X POST https://api.mangrovedeveloper.ai/api/v1/execution/evaluate/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"persist": true}'
Response: 
{
  "success": true,
  "strategy_id": "550e8400-e29b-41d4-a716-446655440000",
  "strategy_name": "BTC Momentum Strategy",
  "asset": "BTC-USD",
  "current_price": 77677.58,
  "timestamp": "2026-01-31T19:55:05.165935",
  "execution_state": {
    "cash_balance": 116338.79,
    "account_value": 116338.79,
    "total_trades": 1,
    "num_open_positions": 0
  },
  "new_orders": [
    {
      "id": "order-uuid",
      "asset": "BTC-USD",
      "side": "exit_long",
      "order_type": "take_profit",
      "status": "filled",
      "price": 77677.58,
      "position_size": 0.5,
      "position_id": "position-uuid"
    }
  ],
  "execution_time_seconds": 2.478
}

​
Evaluate Strategy by Object

POST /api/v1/execution/evaluate Evaluate a strategy using a JSON object instead of a persisted strategy ID. Useful for testing draft strategies or one-off evaluations. 
curl -X POST https://api.mangrovedeveloper.ai/api/v1/execution/evaluate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "strategy": {
      "name": "btc_rsi_test",
      "asset": "BTC",
      "rules": {
        "name": "btc_rsi_test",
        "asset": "BTC",
        "entry": [
          {"name": "rsi_oversold", "signal_type": "TRIGGER", "timeframe": "1h", "params": {"window": 14, "threshold": 30}},
          {"name": "macd_bullish_cross", "signal_type": "FILTER", "timeframe": "1h", "params": {"window_fast": 12, "window_slow": 26, "window_sign": 9}}
        ],
        "exit": []
      },
      "execution_config": {
        "max_risk_per_trade": 0.01,
        "reward_factor": 2,
        "stop_loss_calculation": "dynamic_atr",
        "atr_period": 14,
        "atr_volatility_factor": 2.0
      },
      "execution_state": {
        "cash_balance": 10000.0,
        "account_value": 10000.0,
        "total_trades": 0,
        "num_open_positions": 0
      }
    },
    "persist": false
  }'

​
Bulk Evaluate Strategies

POST /api/v1/execution/evaluate/bulk Evaluates multiple strategies in a single request. Market data is fetched once per unique (asset, timeframe) pair and shared across all strategies. 
curl -X POST https://api.mangrovedeveloper.ai/api/v1/execution/evaluate/bulk \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "strategy_ids": [
      "550e8400-e29b-41d4-a716-446655440000",
      "661f9511-f30c-52e5-b827-557766551111"
    ],
    "persist": false
  }'
Response includes per-strategy results: 
{
  "success": true,
  "results": [
    {
      "success": true,
      "strategy_id": "550e8400...",
      "strategy_name": "BTC Momentum",
      "asset": "BTC",
      "current_price": 77677.58,
      "new_orders": [...],
      "error": null
    }
  ],
  "data_fetches": 1,
  "total_execution_time_seconds": 2.1
}

​
Order Types

SideDescription
enter_longOpen a new long position
exit_longClose an existing long position
Order TypeDescription
marketExecute at current market price
stop_lossExit when price falls below threshold
take_profitExit when price rises above threshold

​
Use Cases

​
Real-Time Signal Monitoring

# Poll every 5 minutes for signals
while true; do
  curl -s -X POST https://api.mangrovedeveloper.ai/api/v1/execution/evaluate/$STRATEGY_ID \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"persist": true}' | jq '.new_orders'
  sleep 300
done

​
Dry-Run Validation

Test strategy signals without persisting changes: 
curl -s -X POST https://api.mangrovedeveloper.ai/api/v1/execution/evaluate/bulk \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"strategy_ids": ["$ID1", "$ID2"], "persist": false}' | jq '.'

​
Cooldown Configuration

The execution engine reads cooldown_config from the strategy’s execution_config to determine per-timeframe loss streak limits and cooldown durations. When a cooldown trips, new entries for that asset are blocked for a number of bars equal to the window that tripped. 
"cooldown_config": {
  "5m":  {"short_loss_limit": 4, "long_loss_limit": 6, "short_window_bars": 180, "long_window_bars": 480},
  "15m": {"short_loss_limit": 4, "long_loss_limit": 6, "short_window_bars": 120, "long_window_bars": 320},
  "1h":  {"short_loss_limit": 4, "long_loss_limit": 6, "short_window_bars": 48,  "long_window_bars": 144},
  "1d":  {"short_loss_limit": 4, "long_loss_limit": 6, "short_window_bars": 20,  "long_window_bars": 60}
}
KeyDescription
short_loss_limitLosses in short_window_bars that trip the short-tier cooldown
long_loss_limitLosses in long_window_bars that trip the long-tier cooldown
short_window_barsRolling lookback AND cooldown duration (bars) for the short tier
long_window_barsRolling lookback AND cooldown duration (bars) for the long tier
Max hold time is controlled by execution_config.time_based_exits.max_hold_bars, not by cooldown_config. The engine selects the entry keyed to the strategy’s primary timeframe. If cooldown_config is absent or the timeframe key is missing, it falls back to the legacy flat keys (cooldown_bars, daily_momentum_limit, weekly_momentum_limit) and emits a deprecation warning.
Deprecated keys: cooldown_bars, daily_momentum_limit, weekly_momentum_limit, and the top-level max_hold_time_hours are deprecated. They continue to work during the 90-day grace period. Migrate to cooldown_config before the next major version.
See the Risk Management guide for full tuning details.