Full Trading Workflow

Complete workflow for the Assistatron trading platform, from authentication through ongoing position management. Includes all branches, error handling, and the saved_strategy_id audit chain.

Workflow Diagram

                      AUTHENTICATION
                      ==============
                           |
                        login()
                           |
                           v
                    [User approves in browser]
                           |
                        check_login(device_code)
                           |
              +------------+------------+
              |            |            |
          "complete"   "pending"    "error"
              |          (wait)     (retry)
              v
        [Tokens issued]
              |
              v
                       ONBOARDING
                       ==========
                           |
              get_onboarding_status()
                           |
                           v
                     accept_eua()
                           |
                     acknowledge_risk()
                           |
                     set_risk_profile()
                           |
                     set_account_mode()
                           |
                     set_broker_keys()
                           |
                           v
                 [Trading tools unlocked]
                           |
              +============+============+
              |                         |
              v                         v
       ACCOUNT HUB               STRATEGY HUB
       ===========               ============
              |                         |
         account()                 strategy()
              |                         |
              v                         v
      +-------+-------+        +-------+-------+
      |       |       |        |               |
   whoami  billing  ...   create_strategy   find_iron_condors
                               |               |
                               v               v
                        [Background job]   [Direct scan]
                               |
                               v
                     get_strategy_status()
                               |
                  +------------+
                  |            |
             "running"   "completed"
              (poll)          |
                              v
                       save_strategy()
                              |
                              v
                    saved_strategy_id
                              |
              +===============+===============+
              |                               |
              v                               v
       find_iron_condors             find_iron_condors
       (saved_strategy_id)           (explicit ticker)
              |                               |
              +===============+===============+
                              |
                              v
                       [candidates]
                              |
                              v
                          TRADING
                          =======
                              |
                trade(action=propose_entry,
                      candidate, qty,
                      saved_strategy_id)
                              |
                              v
                       [proposal_id]
                              |
              +-------+-------+-------+
              |               |       |
         confirm(id)    cancel(id)  [60s TTL]
              |               |       |
              v               v       v
         [Order placed]  [Cancelled] [Expired]
              |
              v
                    POSITION MANAGEMENT
                    ===================
                              |
              +-------+-------+-------+-------+
              |       |       |       |       |
            list   detail  summary  orders  performance
                              |
              +-------+-------+-------+
              |               |       |
        assignment_risk  autoroll_alerts  suggest_autoroll
                              |               |
                              v               v
                    [risk assessment]   [roll suggestion]
                              |               |
                              v               v
                    trade(propose_exit)  trade(propose_roll)
                              |               |
                              v               v
                         confirm(id)     confirm(id)

Phase 1: Authentication

First-time login

  1. Call login() -- returns user_code and verification_uri
  2. User opens URL in browser and enters the code
  3. Call check_login(device_code) -- returns tokens on success
  4. Save access_token and refresh_token

Returning user

If the user already has tokens from a previous session:

  • Configure the access_token as a Bearer header on the MCP connection
  • If the token is expired, call refresh_session(refresh_token) to get new tokens

Token lifecycle

access_token (short-lived) --expires--> refresh_session(refresh_token)
                                              |
                                              v
                                        new access_token + refresh_token

Phase 2: Onboarding (first time only)

After authentication, check get_onboarding_status() to see what steps remain. The flow is sequential:

Step Tool Pre-requisite
1 accept_eua(confirmed=true) Read and present legal://eua resource
2 acknowledge_risk(confirmed=true) Read and present legal://risk-disclosure resource
3 set_risk_profile(...) Ask user about experience and tolerance
4 set_account_mode(mode="paper") Ask user preference
5 set_broker_keys(broker, mode, api_key, api_secret) User provides Alpaca credentials

After step 5 completes, onboarding tools are hidden and the 4 root tools appear: account, strategy, trade, positions.

Phase 3: Strategy Optimization

Open the strategy hub

Call strategy() to reveal the strategy tools.

Run the optimizer

create_strategy(ticker="SPY", max_capital=50000)
    -> job_id

Poll for results

get_strategy_status(job_id)
    -> status: "running", progress: {trials: {completed: 120, total: 200}}
    -> status: "completed", result: {top_strategies: [...]}

Save a strategy

save_strategy(run_id=job_id, strategy_rank=1, notes="Best for SPY")
    -> saved_strategy_id

The saved_strategy_id is the key that threads the entire audit chain.

Phase 4: Chain Scan

Using saved strategy (recommended)

find_iron_condors(saved_strategy_id="e5f6g7h8-...")

Auto-loads ticker, DTE range, IV rank settings from the saved strategy. No need to pass additional parameters.

Using explicit parameters

find_iron_condors(ticker="SPY", preset="balanced")

Review candidates

Candidates are sorted by score (best first). Key metrics per candidate:

  • pop -- probability of profit
  • ror -- return on risk
  • net_credit -- max profit per spread
  • max_loss -- max loss per spread
  • dte -- days to expiration

Phase 5: Trade Execution

Propose entry

trade(
    action="propose_entry",
    ticker="SPY",
    candidate={...from find_iron_condors...},
    qty=2,
    saved_strategy_id="e5f6g7h8-..."
)
    -> proposal_id, expires_at (60-second TTL)

Confirm or cancel

trade(action="confirm", proposal_id="p1q2r3s4-...")
    -> order details from broker

or

trade(action="cancel", proposal_id="p1q2r3s4-...")
    -> cancelled

List proposals

trade(action="list", status="pending")
    -> array of proposals

Phase 6: Position Management

Monitoring

positions(action="list")                          -- all open positions
positions(action="detail", position_id="...")      -- single position
positions(action="summary")                        -- portfolio aggregate
positions(action="orders")                         -- pending orders
positions(action="performance", position_id="...") -- position analytics

Risk monitoring

positions(action="assignment_risk", position_id="...")
    -> per-leg sigma distance and breach flags

Autoroll

positions(action="autoroll_alerts")
    -> recent alerts from background scanner

positions(action="suggest_autoroll", position_id="...")
    -> computed roll suggestion

Execute roll

trade(action="propose_roll", position_id="...", intent="spread_roll")
    -> proposal_id

trade(action="confirm", proposal_id="...")
    -> order placed

Exit position

trade(action="propose_exit", position_id="...", reason="profit target reached")
    -> proposal_id

trade(action="confirm", proposal_id="...")
    -> position closed

The saved_strategy_id Audit Chain

The saved_strategy_id connects every step from optimization through execution:

create_strategy(ticker, max_capital)
    |
    v  run_id
save_strategy(run_id, strategy_rank)
    |
    v  saved_strategy_id
find_iron_condors(saved_strategy_id)  <- auto-loads params from run
    |
    v  candidates[]
trade(propose_entry, candidate, saved_strategy_id)  <- links to strategy
    |
    v  proposal_id
trade(confirm, proposal_id)  <- order includes saved_strategy_id
    |
    v  order_id -> position_id
positions(detail, position_id)  <- linked back to optimizer run

This provides full traceability for:

  • Regulatory audit: what algorithm and parameters produced this trade?
  • Performance attribution: how well did this optimization strategy perform?
  • Decision replay: what did the optimizer recommend and what was actually traded?

Cross-references