positions -- Positions Query Tool

The unified positions query tool. Dispatches to one of 8 actions via the action parameter. Always visible at root post-onboarding -- no hub expansion needed.

All actions are read-only except suggest_autoroll, which computes a roll suggestion but does not execute anything.

Actions

list

Return all open positions for the current user.

Parameter Type Required Description
action string Yes "list"

Response: Array of IronCondorSchema objects (all open positions).

detail

Return a single position by ID with full details.

Parameter Type Required Description
action string Yes "detail"
position_id string Yes UUID of the position

Response: Single IronCondorSchema object with complete leg details, entry data, current P&L, and status.

Errors: POSITION_NOT_FOUND if the ID is invalid or not owned by the user.

summary

Return aggregate portfolio statistics across all open positions.

Parameter Type Required Description
action string Yes "summary"

Response: PortfolioSummarySchema with aggregated metrics: total positions, net credit, unrealized P&L, capital deployed, etc.

orders

Return pending and optionally terminal (filled/cancelled) orders.

Parameter Type Required Default Description
action string Yes -- "orders"
include_terminal bool No false Include filled and cancelled orders

Response: Array of PendingOrderSchema objects.

performance

Return performance analytics. Can be called for a specific position or for the aggregate portfolio.

Parameter Type Required Default Description
action string Yes -- "performance"
position_id string No null Position UUID. Omit for aggregate portfolio metrics

Response: Performance summary with P&L, win/loss stats, and holding period metrics.

assignment_risk

Return per-leg assignment risk analysis for an Iron Condor position. Reports sigma distance, moneyness, and breach probability for each leg.

Parameter Type Required Description
action string Yes "assignment_risk"
position_id string Yes UUID of the IC position

Assignment risk uses sigma distance (not delta) to assess how threatened each leg is. This is the correct application of sigma distance -- monitoring open positions, not filtering entry candidates.

Response: Per-leg risk report with sigma distances and breach flags.

Errors: POSITION_NOT_FOUND if the ID is invalid.

autoroll_alerts

Return recent autoroll suggestions generated by the background scanner. These are read-only notifications, not executed trades.

Parameter Type Required Default Description
action string Yes -- "autoroll_alerts"
limit int No 20 Max alerts to return (1-50)
since string No null ISO 8601 timestamp -- only return alerts after this time

Response: Array of autoroll alert objects from Redis streams.

suggest_autoroll

Compute a roll suggestion for a specific position. Does NOT execute the roll -- it only returns what the roll would look like. To execute, pass the suggestion to trade(action=propose_roll).

Parameter Type Required Description
action string Yes "suggest_autoroll"
position_id string Yes UUID of the IC position

Response: Roll suggestion with new strikes, expiry, expected credit, and the reason for the suggestion (e.g. "short put breached 1.2 sigma").

Common Response Schemas

IronCondorSchema (used by list and detail)

Represents a 4-leg Iron Condor position with:

  • Position metadata: ID, ticker, status, entry date
  • Leg details: all 4 strikes, expiration, quantities
  • P&L: entry credit, current value, unrealized P&L
  • Strategy reference: linked optimizer run (if traded via Assistatron)

PortfolioSummarySchema (used by summary)

Aggregate metrics across all open positions:

  • Position count
  • Total capital deployed
  • Net credit / unrealized P&L
  • Buying power impact

PendingOrderSchema (used by orders)

Order details including:

  • Order ID, type, status
  • Ticker, legs, quantity
  • Fill status and price

Cross-references