Actions
Buy, Sell, Alert, Dynamic Rebalance, Launch Agent, OpenOption, and CloseOption actions.
Actions
An action defines what happens when a strategy's conditions are met. NexusTrade supports equity and crypto actions (Buy, Sell, Alert, Dynamic Rebalance, Launch Agent) plus options actions (OpenOption, CloseOption) when your strategy is designed for listed options.
Buy
Purchase a specified amount of an asset.
- Dollar amount: Buy $500 of AAPL
- Percentage of portfolio: Buy 10% of portfolio in TSLA
- Number of shares: Buy 25 shares of MSFT
Sell
Sell a specified amount of an asset you currently hold.
- All of position: Sell 100% of AAPL position
- Dollar amount: Sell $1,000 of TSLA
- Number of shares: Sell 10 shares of MSFT
Alert
Send a notification without executing any trade. Useful for monitoring conditions and making manual decisions.
- Sends an in-app notification when the condition triggers.
- Can be combined with watchlist email alerts for comprehensive monitoring.
Rebalance (Dynamic Rebalance)
Rebalancing is implemented as the Dynamic Rebalance action (type DynamicRebalance in the API and YAML). When your strategy condition fires, the engine builds a target allocation for that moment, then submits the usual rebalance-style orders (sell overweight names, buy underweight names) to move the portfolio toward those targets.
This is more capable than a fixed “three tickers at 50/30/20” table: you define where candidates come from, how they are filtered and ranked, and how much of each survivor to hold—all using the same indicators and conditions as the rest of NexusTrade.
1. Universe (candidate assets)
- All US stocks — large liquid equity universe (subject to data and plan limits).
- Crypto — crypto universe where supported.
- Specific assets — a fixed list you choose (this is how you model a classic multi-ETF sleeve: only those symbols enter the pipeline).
At initialization the engine attaches the pipeline and weight logic to each candidate. Delisted symbols are pruned over time using historical delisting data so dead names do not stay in the candidate set.
2. Pipeline (ordered stages)
Stages run in order. Each stage takes the current candidate list and narrows or ranks it. Types (aligned with the app and Rust execute_pipeline):
- Filter — Keep assets where a condition evaluates to true (evaluated per asset, with rolling indicator state updated on each bar).
- Select top — Score every remaining asset with an indicator, sort highest or lowest, keep the first N.
- Select percentile — Same scoring, but keep roughly percentile% of the current count (rounded up), then sort by direction.
If a stage yields no assets, the rebalance does not produce a tradable target for that trigger (allocation can fall back to cash—see weights below).
3. Post-pipeline limit
After the last stage, the engine keeps at most limit assets (default 25). Use this to cap breadth when your pipeline is loose (e.g. after filters on the whole market).
4. Weight indicator (target weights)
For each surviving asset, NexusTrade evaluates your weight indicator and treats the numeric result as a raw weight (negative values are treated as zero). Weights are normalized so they sum to 100% of the invested sleeve. If no positive weights resolve, the model allocates 100% to cash for that rebalance—useful defensive behavior when data is missing or filters are too tight.
That normalized mix is what “target allocation” means in code: it drives which positions are overweight vs underweight before the rebalance order generator runs.
Common patterns (same machinery, different indicators):
- Equal weight — weight indicator returns the same positive constant for every survivor (after normalization, each gets an equal share).
- Custom fixed sleeves — Specific assets universe, pipeline that keeps all (e.g. pass-all filter), weight indicator encodes your desired relative sizes (e.g. 5 / 3 / 2 to approximate 50% / 30% / 20%).
- Market cap or momentum tilts — universe + pipeline narrow to a set; weight indicator uses market cap, momentum, quality, etc., so larger scores get more capital after normalization.
5. Max allocation % (cash sleeve)
Optional 0–100 cap (default 100). If set below 100, invested weights are scaled down and the remainder is held as cash in the target allocation—e.g. 80% means at most 80% of portfolio value in the rebalance sleeve and 20% cash target.
6. Sell eligibility (optional)
canSell is a per-candidate condition for held equities that leave the selected set. A non-target position is sold only when the condition is true; false or unavailable results retain it. For example, PositionPercentChange >= 0 implements “never sell at a loss / rotate winners only.” The policy does not block trim sells when a name remains selected but its target weight falls. An explicit deploymentPercent: 0 is a risk-off cash-out and overrides canSell. Retained names are additive, so the live book can temporarily hold more names than limit. Held equities encountered outside the current universe are also evaluated rather than being locked indefinitely. On broad universes, stateful sell conditions add opt-in per-candidate evaluation work on each tick.
7. Transparency (backtests & live)
Dynamic rebalances record audit metadata: pipeline stage input/output counts and sample scores, plus per-asset raw vs normalized weights. A full exit blocked by canSell also records a trading-audit reason. That matches what you see in strategy and event tooling when you drill into a rebalance.
Rebalance Asset Limits
Per-plan caps on how many assets may appear in a single Rebalance action (universe breadth / rebalance complexity). Limits apply to the configured action, not to unrelated strategies:
| Plan |
Max Assets per Rebalance |
| Observer (Free) |
100 |
| Data-Driven Investor |
100 |
| Algorithmic Trader |
150 |
| Unstoppable Quant |
525 |
Launch Agent
Launch an autonomous AI agent that can analyze your portfolio and execute multi-step operations when strategy conditions trigger. This is the most powerful action type — instead of a simple buy or sell, the agent can perform research, analysis, and complex trading operations.
How It Works
- When your strategy condition triggers, NexusTrade launches an AI agent with your specified task.
- The agent receives your portfolio context (positions, buying power, and optionally current market data).
- The agent plans and executes the task autonomously, using the same tools Aurora uses for any multi-step agent run.
- You receive a notification when the agent is launched and when it completes.
Configuration
- Initial Message: Describe what the agent should do (e.g., "Analyze my portfolio and rebalance if any position exceeds 25% of total value").
- Planning Model: The AI model used for high-level planning and reasoning.
- Execution Model: The AI model used for executing individual steps.
- Max Iterations: How many steps the agent can take (10-100). Higher values allow more complex tasks.
- Include Market Data: When enabled, the agent receives current prices, position values, and portfolio weights in its initial context.
Use Cases
- Automatic portfolio rebalancing with intelligent analysis
- Multi-step research and trading based on market conditions
- Complex conditional operations that go beyond simple buy/sell rules
- Automated portfolio monitoring with AI-driven decision making
Agent Suppression
Only one agent can run per strategy at a time. If a strategy condition triggers while an agent is already running for that strategy, the new launch is suppressed until the current agent completes.
OpenOption
OpenOption opens a new options position. The platform resolves specific contracts at execution time from an options builder with these components:
- Underlying: A specific ticker (e.g. SPY) or a dynamic universe pipeline that selects underlyings at runtime (same infrastructure as Rebalance).
- Legs: One or more legs, each specifying call/put, long/short, and how to find the strike and expiration.
- Strike selection: Choose strikes by percent from ATM, dollars from ATM, or target delta (e.g. 30-delta put).
- Expiration selection: A DTE window (e.g. 30-45 days) with a preference for nearest, middle, or furthest.
- Greek filters (per leg): Optional min/max constraints on delta, IV, gamma, theta, vega, or rho to narrow candidate contracts during resolution.
- Strike/expiration fallback ranges: If the target strike is unaffordable, the system searches a fallback range (OTM-to-ITM or ITM-to-OTM direction). A similar fallback exists for expirations (shortest-first or longest-first).
- Ratio: For ratio spreads, each leg has a ratio field (default 1).
- Spread type: Vertical, iron condor, straddle, strangle, calendar, diagonal, or custom. Auto-detected from legs if not specified.
- Allocation: Percent of buying power, dollars, percent of portfolio, or a fixed contract count.
Why not Launch Agent for opening or closing options trades? OpenOption and CloseOption are machine-readable trading actions: the backtester and live engine know exactly how to pick contracts, size positions, and place or close orders from the fields you configure. Launch Agent is different—it starts an AI session that can browse, reason, and call tools; outcomes are not guaranteed to be the same every run, and the system cannot treat that as a repeatable “if condition X then open spread Y” rule. So for defined options entries and exits, use OpenOption/CloseOption (you can still describe what you want in natural language—see below).
Natural language → OpenOption: You do not have to wire every leg by hand in YAML. In Aurora chat or portfolio YAML, describe the trade in ordinary words (for example: “sell 30-delta puts, 30–45 DTE, 10% of buying power”). Aurora (or the portfolio tools) translate that into a proper OpenOption configuration that backtests and deploys like any other strategy action.
CloseOption
CloseOption closes existing option positions. All filter fields are optional—omit any to match all positions.
Position filters: underlying symbols, option type (call/put), direction (long/short), spread type.
Value-based filters: P/L percent thresholds (take profit / stop loss), min/max DTE, min/max days held.
Greek-based filters: spread-level delta range, IV range, and theta range. For example, close when net spread delta drifts past a threshold, or when IV drops below a level after an IV-crush event.
Quantity: Close all matching positions, a specific contract count, or a percentage of the position.
- Close scope: The default
spread scope closes complete spreads atomically. Use leg scope only for explicit spread adjustments, such as buying back the short call leg of a debit spread while leaving the long call open.
- Exits for options: Always use CloseOption to exit options positions—do not use Sell on option legs.
- ConditionTrue: For take-profit, stop-loss, DTE-based, or Greek-based exits, the condition is often
ConditionTrue because the thresholds live on the CloseOption action itself.
For the full list of OpenOption and CloseOption features, see Options trading. For defaults on portfolio starting capital when trading options, see the same page.