Strategy Creation and Management Tools

Tools for running the optimizer, tracking jobs, saving strategies, and reviewing optimization history. All require the strategy hub to be opened first (call the strategy hub tool).

Workflow

create_strategy  -->  get_strategy_status  -->  save_strategy
                           |                        |
                           v                        v
                      (poll until complete)   get_saved_strategies
                                                    |
                                                    v
                                             find_iron_condors(saved_strategy_id)
                                                    |
                                                    v
                                             trade(action=propose_entry)
                                                    |
                                                    v
                                             trade(action=confirm)

create_strategy

Run the optimizer to find Pareto-optimal Iron Condor strategy configurations. Returns immediately with a job_id. The optimization runs in the background (1-5 minutes depending on tier and compute budget).

Parameters

Parameter Type Required Default Tier Description
ticker string Yes -- All Underlying symbol (e.g. "SPY", "QQQ", "IWM")
max_capital float Yes -- All Total portfolio budget in USD
dte_min int No preset Premium Minimum days-to-expiration (1-90)
dte_max int No preset Premium Maximum days-to-expiration (1-90)
top_k int No 5 All Number of top strategies to return
iv_rank_gate_mode string No "soft" Premium "soft" (warn) or "hard" (block if IV low)
iv_rank_threshold float No 0.20 Premium Minimum IV Rank (0.0-1.0)

Free tier: Only ticker, max_capital, and top_k are honored. Other parameters are locked to the preset values (lognormal PoP, yang_zhang vol, SVI surface, CRR pricing, bootstrap simulation, 1 OOS seed). Passing premium parameters returns a TIER_BLOCKED error.

Premium tier: Starts with preset defaults and applies any caller overrides. Additional overridable parameters include pop_model, vol_estimator, vol_surface_model, option_pricer, simulation_mode, garch_model, and delta ranges.

Response: StrategySubmitted

{
  "status": "pending",
  "job_id": "a1b2c3d4-...",
  "tier": "free",
  "message": "Strategy optimization submitted. Call get_strategy_status(job_id='a1b2c3d4-...') to check progress."
}

Quota

Free tier: limited daily calls (check with get_quota_remaining). Premium tier: higher or unlimited daily quota.

get_strategy_status

Check the status of a background optimization job.

Parameters

Parameter Type Required Description
job_id string Yes Job UUID from create_strategy

Response: StrategyStatusResult

When running:

{
  "job_id": "a1b2c3d4-...",
  "status": "running",
  "tier": "free",
  "progress": {
    "latest_stage": "trials_progress",
    "stages_completed": 3,
    "trials": {"completed": 120, "total": 200}
  }
}

When completed:

{
  "job_id": "a1b2c3d4-...",
  "status": "completed",
  "tier": "free",
  "duration_seconds": 142.5,
  "preset": "balanced",
  "n_pareto": 5,
  "result": {
    "summary": "5 Pareto-optimal strategies found using balanced preset",
    "top_strategies": [
      {
        "rank": 1,
        "cagr": 0.22,
        "win_rate": 0.81,
        "max_drawdown": 0.09,
        "p_ruin": 0.02,
        "capital_efficiency": 0.65,
        "n_lanes": 3,
        "entry_freq_days": 7,
        "avg_days_held": 32,
        "robustness": {
          "oos_cagr_median": 0.18,
          "overfit_gap": 0.04
        },
        "config": { "..." : "..." }
      }
    ],
    "audit": { "..." : "..." },
    "warnings": ["IV_RANK_LOW: Current IV rank (0.15) is below threshold (0.20)"],
    "next_actions": [
      {"tool": "save_strategy", "description": "Bookmark a strategy you like"},
      {"tool": "find_iron_condors", "description": "Scan for live tradeable candidates"}
    ]
  }
}

Pipeline stages

Stages progress in order: fetching_data -> data_ready -> trials_progress -> trials_complete -> pareto_extracted -> oos_validating -> oos_complete -> pipeline_complete.

save_strategy

Bookmark a strategy from optimizer results. Creates a saved reference with a saved_strategy_id that can be passed to find_iron_condors and propose_entry for audit trail continuity.

Parameters

Parameter Type Required Default Description
run_id string Yes -- Job ID from create_strategy / get_strategy_status
strategy_rank int Yes -- Rank of the strategy to save (1 = best)
notes string No null Optional reason for saving

Response: SavedStrategyResult

{
  "id": "e5f6g7h8-...",
  "run_id": "a1b2c3d4-...",
  "strategy_rank": 1,
  "notes": "Best risk-adjusted for SPY weekly entries",
  "created_at": "2026-05-12T14:30:00Z"
}

get_saved_strategies

List previously saved strategies with their search parameters and run metadata.

Parameters

Parameter Type Required Default Description
limit int No 20 Max strategies to return (1-50)

Response

[
  {
    "id": "e5f6g7h8-...",
    "run_id": "a1b2c3d4-...",
    "strategy_rank": 1,
    "strategy_json": {
      "cagr": 0.22,
      "win_rate": 0.81,
      "max_drawdown": 0.09,
      "config": { "..." : "..." }
    },
    "notes": "Best risk-adjusted for SPY weekly entries",
    "created_at": "2026-05-12T14:30:00Z",
    "run_preset": "balanced",
    "run_ticker": "SPY",
    "run_created_at": "2026-05-12T14:15:00Z"
  }
]

get_optimization_history

Return past optimizer runs for this user (summaries only, not full results).

Parameters

Parameter Type Required Default Description
limit int No 10 Max runs to return (1-50)

Response

[
  {
    "run_id": "a1b2c3d4-...",
    "preset": "balanced",
    "status": "completed",
    "n_pareto": 5,
    "n_trials": 200,
    "duration_seconds": 142.5,
    "created_at": "2026-05-12T14:15:00Z",
    "summary": "5 Pareto-optimal strategies found"
  }
]

To retrieve full results from a past run, call get_strategy_status(job_id=run_id).

The Audit Chain

The saved_strategy_id links every step from optimization through execution:

create_strategy (run_id)
    |
    v
save_strategy (run_id + rank -> saved_strategy_id)
    |
    v
find_iron_condors (saved_strategy_id -> auto-loads search params)
    |
    v
trade(propose_entry, saved_strategy_id -> stored on proposal)
    |
    v
trade(confirm -> order submitted with full provenance)

Every proposal, order, and position can be traced back to the optimizer run that produced the strategy, including all parameters and algorithms used.

Cross-references