Assistatron MCP — Agent Guide

You are connected to the Assistatron MCP server — an Iron Condor options trading platform.

CRITICAL: Always run the optimizer before trading

Do NOT call find_iron_condors without running create_strategy first. The optimizer analyses volatility regimes, compares probability-of-profit models, and scores candidates across multiple dimensions. Without it, you are using default parameters and the risk is significantly higher.

The correct workflow is always: create_strategy → get_strategy_status → save_strategy → find_iron_condors → trade.

Tool Discovery

After login and onboarding, you see 5 tools at root:

Tool Type What it does
account Hub Call to reveal profile, broker, billing, quota tools
strategy Hub Call to reveal optimizer, presets, saved strategies, chain scan
market_data Hub Call to reveal the volatility, pricing, and scoring sub-hubs
trade Action Propose entry/roll/exit, confirm, cancel, cancel_order, list proposals
positions Action List positions, orders, risk, performance analytics

Hubs must be called first. Calling account, strategy, or market_data reveals their sub-tools for the rest of the session. trade and positions are always available.

The Workflow

1. strategy()                          → reveals strategy tools
2. create_strategy(ticker, max_capital) → returns job_id (runs in background)
3. get_strategy_status(job_id)          → poll until completed, get top_strategies
4. save_strategy(run_id, rank)          → bookmark a strategy, get saved_strategy_id
5. find_iron_condors(saved_strategy_id) → auto-loads search params, returns candidates
6. trade(action="propose_entry", ticker, candidate, qty, saved_strategy_id)
                                        → proposal (TTL by mode: demo 300s / paper 60s / live 30s), returns proposal id
7. trade(action="confirm", proposal_id) → submits order to broker

saved_strategy_id links the entire chain for audit. Pass it to both find_iron_condors and trade(propose_entry).

trade(action, ...)

Action Required params
propose_entry ticker, candidate (from find_iron_condors), qty. Optional: saved_strategy_id
propose_roll position_id, intent (full_roll or spread_roll)
propose_exit position_id
confirm proposal_id
cancel proposal_id
cancel_order order_id — cancel a live order on the broker
list Optional: status (pending/confirmed/expired/cancelled), limit

positions(action, ...)

Action Required params
list — (all open positions)
detail position_id
summary — (aggregate portfolio stats)
orders Optional: include_terminal
performance Optional: position_id (omit for aggregate)
assignment_risk position_id
autoroll_alerts Optional: limit, since
suggest_autoroll position_id

Account Hub Tools

Call account() first, then:

  • whoami — profile, tier, mode, active broker
  • get_accounts — broker accounts with balances
  • set_active_account(account_id) — switch active broker
  • connect_broker(broker, mode, ...) — add a new broker
  • set_risk_profile(...) — change risk tolerance
  • get_quota_remaining(tool_name) — check daily quota before calling
  • submit_feedback(message) — report bugs or request features
  • billing(action) — get_fees, get_subscription, or cancel_subscription

Error Handling

Errors return structured JSON:

{
  "error": "STRATEGY_NOT_CANDIDATE",
  "message": "You passed a strategy config, not a tradeable candidate.",
  "suggestion": "Call find_iron_condors first.",
  "see_tool": "find_iron_condors"
}
  • Parse error to decide what to do
  • Follow suggestion to self-correct
  • Call see_tool if provided
  • tier_upgrade_hint: true means the user needs premium

Common errors: ONBOARDING_REQUIRED, BROKER_NOT_CONNECTED, QUOTA_EXCEEDED, TIER_BLOCKED, STRATEGY_NOT_CANDIDATE.

market_data() → volatility / pricing / scoring sub-hubs

Call market_data to reveal three sub-hubs: volatility, pricing, scoring. Then call volatility to unlock the volatility analysis tools below (it returns a summary with spot + IV rank):

Tool What it returns
vol_realised Yang-Zhang HV (30d/60d/252d window)
vol_implied Latest IV from history (HV proxy if no chain data)
vol_ratio RV/IV ratio + signal: iv_rich, iv_cheap, neutral
iv_rank IV rank (0.0–1.0, 252-day lookback)
iv_percentile IV percentile (fraction of days below current)
iv_zscore Z-score of current IV vs historical distribution
ewma_vol EWMA vol (lambda=0.94, annualised)
vol_regime Regime label: low (<0.3), mid (0.3–0.7), high (>0.7) based on IV rank
garch_forecast GJR-GARCH(1,1) forecast at 5/10/20d horizons — premium only
mean_reversion OU half-life of IV mean reversion — premium only

All tools take ticker as required parameter. Use vol_regime or iv_rank to decide if conditions are right for selling premium (high IV rank = good for Iron Condors).

Tier System

Free: lognormal PoP, Yang-Zhang/Parkinson vol, SVI surface, CRR pricer, bootstrap sim. 300 trials, 1,000 paths, 5 years, 3 OOS seeds. 10 create_strategy/day, 500 find_iron_condors/day. All vol tools except GARCH and mean-reversion.

Premium: all algorithms (Cornish-Fisher/Johnson-SU/EVT PoP, SSVI/Vanna-Volga/SABR surfaces, Crank-Nicolson (QuantLib)/Heston/SABR pricers, Sharpe/Sortino scorers, GARCH sim with 8 variants) + GPU effort levels. 100 create_strategy/day, 5,000 find_iron_condors/day. Full vol suite including GARCH forecasts and mean-reversion analytics. Premium can also override the algorithms per run via create_strategy params: pop_model, vol_estimator, vol_surface_model, option_pricer, garch_model, entry_scorer (free users passing these get TIER_BLOCKED). Pass effort to create_strategy:

Effort Trials Paths Years OOS Time Mode
low 200 3k 3 3 ~40s GARCH GPU
medium 500 5k 5 10 ~2 min GARCH GPU
high 1k 10k 10 20 ~8 min GARCH GPU
ultra 1k 10k 10 50 ~12 min GARCH GPU

Demo mode: call activate_demo_mode during onboarding to skip broker connection entirely. Uses $100k virtual capital for exploration — no Alpaca keys required.

Rules

  1. Always run the optimizer first. Call create_strategy before find_iron_condors. Skipping it means trading with default parameters and no volatility analysis.
  2. Never pass strategy results to propose_entry. Call find_iron_condors first.
  3. Proposals expire by mode: demo 300s, paper 60s, live 30s. Confirm or cancel promptly.
  4. Check quota before searching. Use get_quota_remaining.
  5. create_strategy is async. Returns job_id — poll with get_strategy_status.
  6. Use saved_strategy_id everywhere. Links the full audit trail.
  7. Read legal docs before onboarding steps. Call get_legal_document and give the user a link before accept_eua, acknowledge_risk, or set_broker_keys.
  8. Never call external APIs directly. All actions go through MCP tools. Do not use curl, fetch, or HTTP requests to assistatron.com or api.assistatron.com.
  9. Never expose tokens or credentials. Do not print, log, or show access tokens, refresh tokens, API keys, or secrets to the user.