The workhorse. Scans one or more markets and returns the strongest seasonal setups right now as ranked decision cards - headline, direction, edge score, entry window, and a research hand-off. Use when the user asks what to trade or when to enter.

Inputs: markets (plural - a list or CSV of market ids/names), window (e.g. "now"), direction (long | short), min_win_rate, min_years, min_days, max_days, min_avg_return, min_median_return, min_sharpe, pe_cycle, years, min_winning_years, rank_by, limit, view

Maps to: GET /v1/scan

Deep-dives one named ticker - the best current seasonal setup plus alternative setups, full receipts, and a ready-to-place ticket. Use when the user asks about a specific symbol.

Inputs: symbol (required), market, direction, days_out, entry_date, pe_cycle, years, period, reverse, view, include_chart

Maps to: GET /v1/analyze/{symbol}

Returns today's AI daily pick as a full Pattern Card WITH its live, forward-tested track record - the strongest proof TradeWave can offer (the pick is made in advance, then scored later). Use when the user asks for "today's pick", "the trade of the day", or wants to see proof the seasonal patterns work before trusting them.

Inputs: none

Maps to: GET /v1/daily-pick

The one-call morning briefing: today's daily pick (decision view), the live forward-tested track-record summary with the last five outcomes, and the top setups entering their seasonal window now. Use on "good morning", "my briefing", or any open-ended start-of-day prompt. Sections degrade gracefully - a partial briefing beats no briefing.

Inputs: none

Maps to: GET /v1/daily-pick + GET /v1/daily-pick/track-record + GET /v1/scan (composed, fetched in parallel)

The zero-input starting point. Returns what is seasonally in play right now across the caller's in-scope markets - a fast "what should I be looking at today" overview.

Inputs: none required (optional markets (plural), min_win_rate, view)

Maps to: GET /v1/scan with window=now

Puts two or more setups side by side on the same yardstick - edge score, win rate, Sharpe, avg/median return, ML basis - so the assistant can reason about which is stronger. Use when the user is choosing between candidates.

Inputs: symbols (required, a list of ticker symbols, e.g. ["GLD", "SLV", "GDX"]), market (optional, applied to every symbol), view

Maps to: GET /v1/analyze/{symbol} (per symbol)

Returns the 15 active TradeWave markets and which are within the caller's tier scope. Use this to discover what markets are available before fetching opportunities.

Inputs: none

Maps to: GET /v1/markets

Reports the caller's identity and entitlements as resolved from the authenticated TradeWave account or developer key - plan, in-scope markets, ML allowance, and remaining quota. Use it after connecting to confirm what the current connection can access.

Inputs: none

Maps to: GET /v1/me

Self-documents the method: what TradeWave measures (seasonal + 62-feature ML), what it is blind to (fundamentals, news, macro, live price), and how the assistant should pair it with its own research tools. Call this once so the model frames TradeWave correctly as a research partner.

Inputs: none

Maps to: static method description

Lists the tradeable symbols in a market.

Inputs: market (market id, e.g. "2")

Maps to: GET /v1/markets/{market_id}/symbols

Find the best seasonal trade setups for a market and date window, ranked by historical edge. Use when the user asks what to trade, when to enter, or which symbols have a strong seasonal tendency.

Inputs: market (required), from, to, direction (long | short), min_win_rate (0-1), limit

Returns: ranked list - symbol, direction, entry date, holding period, Sharpe ratio, avg/median return %, win rate. ML fields are included only when the connected TradeWave account or developer key has ML access and the market is ML-eligible (ids 0-4, 11); otherwise they are null.

Maps to: GET /v1/opportunities

A security's top seasonal patterns throughout the year, ranked by Sharpe ratio - the list the wave viewer shows in its pattern dropdown. Coverage: per-symbol patterns exist for market ids 0, 1, 2, 7, and 9 only (DOW 30, NASDAQ 100, S&P 500, Futures & Commodities, FOREX Liquid); any other market returns a clear error - use find_best_opportunities to scan those instead.

Inputs: symbol (required), market (required), pe_cycle, years, min_winning_years, min_days, max_days, min_avg_return, min_sharpe

Maps to: GET /v1/securities/{symbol}/patterns

Returns aggregate seasonal pattern statistics for a symbol - win rate, average/median profit, Sharpe ratio, and related percentages. No price series is returned.

Inputs: market (required), symbol (required), pe_cycle, years, period, reverse

Maps to: GET /v1/patterns/{market_id}/{symbol}

Returns The Trend Chart DATA (not an image) for a seasonal setup - a single year-averaged, normalized 0-100 seasonal index curve (seasonal_curve, one {date, index} point per day). It is the typical within-year shape (where it rises, peaks, fades), NOT per-year cumulative price paths, and the index is never a price. Agents can reason over the shape. Raw prices are intentionally not exposed.

Inputs: market (required), symbol (required), entry_date, days_out, direction, years, pe_cycle, period, reverse

Maps to: GET /v1/seasonal-chart

Runs the ML model on a list of opportunities and returns ml_score, win_prob, pred_return, and pred_mfe for each. Availability and daily allowance follow the connected TradeWave account's web plan or the developer key's API plan. If ML is unavailable or the daily allowance is spent, the response returns a graceful upgrade stub instead of failing.

Inputs: list of {symbol, date, days_out, direction}

Maps to: POST /v1/score

Returns today's ML-selected featured opportunity. The daily pick is the top ML-scored setup published each morning before market open.

Inputs: none

Maps to: GET /v1/daily-pick

Returns the verifiable, time-stamped win/loss record of all past daily picks - this is the live, forward-tested track_record.win_rate, distinct from the seasonal historical_win_rate and the per-instance ml_win_prob. Use this to show the AI's historical performance to the user.

Inputs: none

Maps to: GET /v1/daily-pick/track-record