approve_agent_plan | ⚠ INDIRECTLY COSTS LLM CREDITS — approving the plan unfreezes the agent which then runs more planning + execution LLM calls. Manual approval required; do NOT call unless the user explicitly told you to advance their Aurora agent. Approve a semi-automated agent that is waiting in pending_plan_approval or pending_action_approval. Auto-detects which approval the agent needs and emits the matching state-machine event so the agent resumes execution. Returns 400 if the agent is not in a pending-approval state. |
archive_agent | Aurora agent surface (no LLM cost — pure DB write). Only relevant when managing Aurora agents. Archive an agent (soft-delete). The agent remains in the database but is hidden from default listings. Address by agentId OR exact title (XOR). |
backtest_portfolio | Submit an asynchronous historical backtest for a portfolio over a date range. Minute interval: first-look default is the last 90 inclusive calendar days; the selected range plus minute-indicator warmup cannot exceed 730 days of minute data, so a multi-year Minute window up to that span is allowed — do not emit 2010, and never split a longer span into yearly Minute jobs. Daily equity may use a long window. Set baseline_symbol to match the book — underlying ticker for single-name options (AAPL→AAPL), per-underlying baselines or equal-weight universe B&H for multi-name options; SPY only for broad equity. Returns a backtest ID immediately; poll query_backtest_status, then query_backtest_history (zero-LLM). Aurora may also use Read Backtest for an LLM narrative once complete. |
build_portfolio | Preview/builder twin of create_portfolio. Runs the SAME construction + per-strategy validation (Portfolio/Strategy/Condition/Indicator) as create_portfolio but PERSISTS NOTHING. Accepts the same IPortfolio JSON (all fields optional so partial drafts can be checked). Returns the canonicalized portfolio plus a per-component issue list (path + component + message) so you can see exactly which strategy/condition/indicator is wrong before committing. A draft that previews clean cannot fail on create_portfolio. Zero research token cost.
Custom data sources: none yet.
Create one with run_compute (pass name and point_kind to promote its signal output directly), or use dataset_to_indicator with a saved dataset; then reference customIndicatorId in create_portfolio. |
clone_strategies_to_portfolio | Replace a deployed (paper/live) portfolio's entire strategy set with deep copies of a source portfolio's strategy objects (by reference, not YAML). Source is a chat or deployed portfolio; the target MUST be a real deployed portfolio (chat portfolios are immutable and cannot be a target). Use this to deploy a chat portfolio's strategies onto a live/paper portfolio without re-describing them. Do NOT automatically backtest after clone — only backtest when the user asked for research validation. The source's prior backtest does not validate the target (different objects), but deploy-only asks should stop at clone/deploy. |
create_agent | ⚠ COSTS LLM CREDITS on the NexusTrade account — spins up an Aurora agent via Router V5 classification + ReAct execution loops, billed per token. **Manual approval required**: do NOT call unless the user explicitly asked to launch an Aurora agent. For strategy creation/backtesting/analysis prefer no-LLM tools: structured create_portfolio (pass full IPortfolio JSON), backtest_portfolio, query_backtest_history, query_*, fetch_portfolios. Create a new autonomous Aurora agent using the same body shape as POST /api/agent. When maxIterations or automationMode are omitted, applies the user's saved ChatSettings. Agent models are product-locked (openai/gpt-5.6-luna planner, openai/gpt-6-luna executor, and the platform tool-role defaults) and cannot be overridden. Pass attachment_ids from upload_chat_attachment (READY) to bind files onto the last user message — same as the web FILES tab. Use this for a method-brief PDF plus a short analyze/report request. |
create_portfolio | Create an algorithmic trading portfolio. **PREFERRED PATH (no LLM cost): pass a fully-structured IPortfolio JSON payload** — see inputSchema for name + strategies[] with nested condition/action/indicator objects and optional strategy-owned orderExecution. DynamicRebalance.deploymentPercent and RebalanceOption.totalBudget.amount are indicator objects: use Value for a constant or PoliticalPurchaseShare with a Bioguide memberId, instrument Equity/Option, and amountBasis Midpoint for a dynamic purchase mix. RebalanceOption.sizingMode proportionalToWeight sizes names by positive weightIndicator values. Omit orderExecution for the explicit Market default; true waiting Limits use UnitPrice for shares/crypto or MinimumNetCredit/MaximumNetDebit for options, whose amount may be an indicator (such as OptionSpreadEntryPrice plus a Value) evaluated when the strategy fires. CustomIndicator nodes MUST include customIndicatorId from list_custom_indicators. Validate without saving by calling build_portfolio with the same JSON first. Fallback NL path `{ message: "..." }` costs LLM credits and should only be used when structured JSON is impractical.
Custom data sources: none yet.
Create one with run_compute (pass name and point_kind to promote its signal output directly), or use dataset_to_indicator with a saved dataset; then reference customIndicatorId in create_portfolio. |
create_portfolio_variant | Deep-copy a source chat or deployed portfolio into a new ChatPortfolio with fresh strategy IDs. Omit patches for a clone-only draft, or apply JSON-Pointer patches (replace/add/remove) for surgical edits. Atomic: unresolved patch paths are hard errors. dry_run validates without persisting. Zero research token cost. |
fetch_portfolios | List or search your portfolios with lightweight metadata (strategy id + name). Matches portfolio name, strategy names, and tickers — same workspace search as the dashboard / GET /api/chat-portfolio. include_chat_portfolios returns workspace DRAFTS only (excludes deployedMirror rows). Recover a past chat draft: include_paper=false, include_live=false, include_chat_portfolios=true, search="Delta 0.07" (then get_portfolio for full strategy JSON). Returns an object: { portfolios, page, limit, total, totalPages, scopes }. Deployed and draft rows page as one list (all deployed, then all drafts), so every row is reachable by walking pages. When search is set, include_positions defaults to false. Use analyze_portfolios only when you need LLM-written analysis. |
fork_shared_portfolio | ⚠ MUTATING — creates or modifies a portfolio. Fork strategies from a shared portfolio into the user's account. target: 'new' creates a chat portfolio; 'existing' patches a deployed portfolio. mode: 'replace' (default) removes old strategies, 'append' keeps them. For monetized portfolios, subscribe first. Returns { forkSharedPortfolioResult: { portfolioId, name, addedCount, removedCount, ... } }. Prefer fork when the user wants to edit/customize strategies. |
get_agent | Aurora agent surface (no LLM cost on this call — pure DB read). Only relevant when the user is actively working with an Aurora agent. Returns status, plan, messages, config. Address by agentId OR by exact title (case-insensitive); provide exactly one. Duplicate titles fail closed with candidate ids. Polling/liveness: use agent.lastProgressAt (advances during sandbox steps, tool cards, LLM rounds, and — while waiting_for_subagents — when children progress) — NOT agent.updatedAt (state transitions only; stays frozen by design while parked on subagents so the waiting-no-wake detector can prefilter). For waiting_for_subagents, a frozen lastProgressAt means children stopped progressing; confirm via child agent statuses. Sandbox step detail: agent.messages[*].data.steps. Poll until status is terminal (complete/stopped/error). |
get_agent_trajectory | Aurora agent surface (no LLM cost on this call — pure DB read). Only relevant when inspecting an Aurora agent run. Raw trace / trajectory events for an agent (for inspection or building evaluator input). Address by agentId OR exact title (XOR). |
get_portfolio | Fetch one portfolio with full strategy objects (condition, action, indicators), positions, and spread-grouped holdings. Zero LLM cost — same data path as GET /api/portfolio/:portfolioId. Resolves deployed paper/live portfolios first, then chat portfolios. Use fetch_portfolios to discover IDs. Response includes conditionFieldAudit (comparison, value, window.length per base condition) — use that for Gate-7/Gate-8 deploy verification, NOT strategy.name or condition.name (those may be stale after GA mutation). |
list_agents | Aurora agent surface (no LLM cost on this call itself — pure DB read). Useful only when the user is actively operating an Aurora agent. For strategy creation/backtesting prefer the structured no-LLM tools (create_portfolio with full JSON payload, backtest_portfolio, query_*, fetch_portfolios). List your Aurora agents with pagination using the same query shape as the agent controller. |
query_backtest_history | Return a time series of {time, value, cash, positionValue, comparisonValue, reservedCollateral} per tick for a completed backtest. Reads from the backtesthistories collection (full minute-resolution; 30-day TTL). Use this to find suspicious single-tick portfolio value jumps without needing the codebase — feed the result through your own jump-detection logic. Cash is derived as value minus Σ(position.quantity × lastPrice). `reservedCollateral` is the collateral locked by open positions at that tick, as the engine computed it; it reads `null` for a run made before collateral reporting existed, which is NOT zero. Never re-derive it from cash − buyingPower. Zero research token cost. |
query_backtest_status | Return the parent backtest document's status, error, interval, timestamps, elapsed time, and completed statistics without reading history/events. Use immediately after backtest_portfolio or before query_backtest_history so ERROR/PENDING/RUNNING states are explicit. Statistics include peakReservedCollateral and medianReservedCollateral — how much capital the book actually had on the line, which a percentage return does not say. Both read "not recorded" for a run made before collateral reporting existed; that is not zero, so do not report it as such. Zero research token cost. |
reject_agent_action | Aurora agent surface (minimal LLM cost — state transition, no re-planning). Only relevant when actively managing an Aurora agent. Reject a semi-automated agent that is waiting in pending_plan_approval or pending_action_approval. Mirrors POST /api/agent/:agentId/reject, marks the latest assistant message as errored, transitions through the state machine, traces the rejection, and publishes a websocket update. |
search_public_portfolios | Search and browse publicly shared portfolios from other NexusTrade users, sorted by performance metrics. Optional profileId filters to one creator's public/monetized books (from Search Creators / /p/:profileId). |
send_agent_message | ⚠ COSTS LLM CREDITS — re-runs the Aurora planner LLM after appending the user's follow-up. Manual approval required; do NOT call unless the user explicitly asked to push a message into an active Aurora agent. Address by agentId OR exact title (XOR). Send a follow-up user message to an agent and re-run the planner, matching POST /api/agent/:agentId/message. This can charge planning tokens, rejects actively running/approved states, may recover terminal states, may transition the agent, and publishes websocket updates. It is not an append-only operation. |
send_chat_message | ⚠ COSTS LLM CREDITS — same path as POST /api/chat. Router V5 classifies the message: Ask Clarity (persisted), Create Agent (spawns Aurora research), or single-tool fulfill (queued prompt job). Use this for chat turns; use create_agent only when you explicitly want agent spawn without single-tool fulfill. Aurora chooses the complete route adaptively. |
star_agent | Aurora agent surface (no LLM cost — pure DB write). Star or unstar a top-level agent for quick sidebar access. Mirrors PATCH /api/agent/:agentId/star. Address by agentId OR exact title (XOR). Omit starred to toggle. |
stop_agent | Aurora agent surface (no LLM cost — pure state transition). Only relevant when actively managing an Aurora agent. Stop a running agent. Sends a cancellation request and cascades to all descendant subagents. The agent must be in an active state (running, initializing, pending approval, etc.). |
unarchive_agent | Aurora agent surface (no LLM cost — pure DB write). Only relevant when managing Aurora agents. Restore an archived agent so it appears in default agent listings again. Address by agentId OR exact title (XOR). |
update_portfolio | Deploy, undeploy, rename, delete, add/remove/replace strategies, or set deployment frequency on portfolios. **rename** requires a non-empty `name` on the operation. **delete** permanently removes a chat, paper, or live portfolio (archives deployed paper/live books; deleting a chat portfolio also archives linked deployments). Pass confirmLive:true only after explicit user confirmation when deleting an active live portfolio. **Structured path (zero LLM cost):** pass an `operations` array — see inputSchema. Use `replaceStrategy` / `replaceStrategies` with full `{name, condition, action, orderExecution?}` strategyObjects (same shape as create_portfolio). New rebalance budgets should be indicators (Value for constants, PoliticalPurchaseShare for dynamic member purchase mix); RebalanceOption accepts sizingMode proportionalToWeight. `orderExecution` defaults to Market; true waiting Limits use UnitPrice for shares/crypto or MinimumNetCredit/MaximumNetDebit for options, whose amount may be an indicator (such as OptionSpreadEntryPrice plus a Value) evaluated when the strategy fires. QuoteRelative normally executes immediately at the snapshotted quote. RebalanceOption: set `action.positionScope` to `portfolio` (single-book — closes/orphans all option spreads in the portfolio) or `strategy` (multi-strategy book). |