{"recommended_starting_workflow":{"workflow_id":"portfolio_build","reason":"Recommended first workflow for autonomous portfolio agents because it starts with symbol discovery, constructs a bounded portfolio, and produces reusable symbol_exchange values for downstream evaluation and comparison."},"agent_guidance":{"ordered_planning_steps":["Fetch /v1/ai/tools for tool metadata and parameter locations.","Fetch /v1/pricing/catalog to resolve current STC costs by pricing_rule_id.","Choose a workflow here, then execute steps in order.","Reuse symbol_exchange values from screeners, selections, or portfolio_construct outputs.","Skip duplicate paid symbol calls when a symbol_exchange was already resolved in the workflow."],"payment_rails":["subscription","x402","mpp"],"pricing_note":"STC is the pricing source of truth across all rails."},"data_provenance":{"historical_coverage_start_year":1980,"approximate_observation_count":"16M+","update_frequency":"weekly","classification_framework":"Stock Trends trend classification methodology","semantic_continuity":"Stock Trends indicators use a consistent classification doctrine across decades of observations.","native_signal_domains":["trend classification","relative performance","relative performance direction","volume activity","market breadth","sector leadership","regime structure"],"research_value":["long-horizon signal validation","regime analysis","sector rotation research","portfolio construction research","causal and probabilistic market analysis","agentic market-intelligence workflows"],"important_limits":["Historical depth supports research and probabilistic interpretation but does not guarantee future performance.","Stock Trends outputs are not investment advice, price targets, or direct buy/sell commands.","Externally named market events are not native Stock Trends labels unless separately curated."]},"workflows":[{"workflow_id":"regime_analysis","name":"Market Regime Analysis","description":"Full market regime intelligence pipeline: current regime classification, historical regime sequence for context, and probabilistic forward forecast.","tags":["agent","research","regime"],"supported_rails":["subscription","x402","mpp"],"total_stc_cost":0.75,"total_estimated_usd_cost":0.75,"pricing_note":"STC is the pricing source of truth. The estimated USD value uses the current operational policy of 1 STC approximately 1 USD and is for planning only.","decision_guidance":"Use when the agent needs market-level context before selecting bullish, bearish, or mixed symbol and portfolio workflows.","best_for":"Market context before symbol selection, screening, or portfolio construction.","agent_goal_examples":["Decide whether a portfolio agent should use bullish, bearish, or mixed candidate filters.","Summarize current regime and recent regime direction before selecting symbols."],"symbol_selection_guidance":"This workflow does not select symbols directly; use its regime result to choose bias filters for /v1/agent/screener/top or /v1/portfolio/construct.","interpretation_guidance":null,"required_interpretation_steps":[],"next_step_guidance":["Use /v1/agent/screener/top to discover candidates.","Use /v1/decision/evaluate-symbol for a known symbol.","Use /v1/portfolio/construct when the goal is an allocation proposal."],"steps":[{"step_id":"regime_latest","endpoint":"GET /v1/market/regime/latest","method":"GET","path":"/v1/market/regime/latest","pricing_rule_id":"market_regime_latest","stc_cost":0.15,"estimated_usd_cost":0.15,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Retrieve the current market regime classification.","purpose":"Classify current market regime.","workflow_role":"Market context.","required_inputs":{},"optional_inputs":{},"safe_example_request":{"method":"GET","path":"/v1/market/regime/latest","query":{}},"output_summary":"Current regime classification and aggregate signal distribution.","related_endpoints":["/v1/market/regime/history","/v1/market/regime/forecast"],"optional":false},{"step_id":"regime_history","endpoint":"GET /v1/market/regime/history","method":"GET","path":"/v1/market/regime/history","pricing_rule_id":"market_regime_history","stc_cost":0.25,"estimated_usd_cost":0.25,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Retrieve historical regime sequence for context.","purpose":"Review recent market regime transitions.","workflow_role":"Historical market context.","required_inputs":{},"optional_inputs":{"limit":{"type":"integer","required":false,"safe_default":12,"minimum":1,"maximum":52},"start":{"type":"string","required":false,"format":"date","example":"2025-01-03","description":"Inclusive start weekdate in YYYY-MM-DD format."}},"safe_example_request":{"method":"GET","path":"/v1/market/regime/history","query":{"limit":12}},"output_summary":"Recent weekly market regime sequence.","related_endpoints":["/v1/market/regime/latest","/v1/market/regime/forecast"],"optional":true},{"step_id":"regime_forecast","endpoint":"GET /v1/market/regime/forecast","method":"GET","path":"/v1/market/regime/forecast","pricing_rule_id":"market_regime_forecast","stc_cost":0.35,"estimated_usd_cost":0.35,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Retrieve probabilistic forward regime forecast.","purpose":"Estimate near-term regime direction using deterministic recent-score logic.","workflow_role":"Regime decision guidance.","required_inputs":{},"optional_inputs":{"lookback":{"type":"integer","required":false,"safe_default":5,"minimum":2,"maximum":13}},"safe_example_request":{"method":"GET","path":"/v1/market/regime/forecast","query":{"lookback":5}},"output_summary":"Deterministic regime outlook and confidence fields.","related_endpoints":["/v1/market/regime/latest","/v1/market/regime/history"],"optional":false}]},{"workflow_id":"symbol_decision","name":"Regime-Aware Symbol Decision","description":"Classify the current market regime then evaluate a single symbol for a directional research bias in that regime context.","tags":["agent","research","decision"],"supported_rails":["subscription","x402","mpp"],"total_stc_cost":0.65,"total_estimated_usd_cost":0.65,"pricing_note":"STC is the pricing source of truth. The estimated USD value uses the current operational policy of 1 STC approximately 1 USD and is for planning only.","decision_guidance":"Use when the agent has a target symbol and needs deterministic Stock Trends signal and regime context before deeper history or portfolio calls.","best_for":"Evaluating a known symbol in current market-regime context.","agent_goal_examples":["Evaluate IBM-N after resolving it from /v1/instruments/resolve.","Score a symbol carried forward from a screener, STWR report, or portfolio position."],"symbol_selection_guidance":"Provide symbol_exchange directly when available. If only a ticker is known, first call /v1/instruments/lookup or /v1/instruments/resolve and reuse the returned symbol_exchange.","interpretation_guidance":null,"required_interpretation_steps":[],"next_step_guidance":["Use /v1/indicators/latest or /v1/stim/latest for deeper single-symbol context.","Use /v1/portfolio/evaluate when comparing the symbol inside an allocation."],"steps":[{"step_id":"regime_latest","endpoint":"GET /v1/market/regime/latest","method":"GET","path":"/v1/market/regime/latest","pricing_rule_id":"market_regime_latest","stc_cost":0.15,"estimated_usd_cost":0.15,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Retrieve the current market regime classification.","purpose":"Classify current market regime.","workflow_role":"Market context.","required_inputs":{},"optional_inputs":{},"safe_example_request":{"method":"GET","path":"/v1/market/regime/latest","query":{}},"output_summary":"Current regime classification and aggregate signal distribution.","related_endpoints":["/v1/market/regime/history","/v1/market/regime/forecast"],"optional":false},{"step_id":"evaluate_symbol","endpoint":"POST /v1/decision/evaluate-symbol","method":"POST","path":"/v1/decision/evaluate-symbol","pricing_rule_id":"evaluate_symbol","stc_cost":0.5,"estimated_usd_cost":0.5,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Evaluate a symbol directional research bias given the current regime.","purpose":"Evaluate one symbol for directional decision-support bias in regime context.","workflow_role":"Symbol-level decision step.","required_inputs":{"symbol_exchange":{"type":"string","required":true,"example":"IBM-N","safe_default_for_demo":"IBM-N","pattern":"^[A-Z0-9.]+-[A-Z]$","description":"Stock Trends symbol plus exchange suffix."}},"optional_inputs":{"symbol":{"type":"string","required":false,"example":"IBM","description":"Ticker symbol. Use with exchange when symbol_exchange is not supplied."},"exchange":{"type":"string","required":false,"enum":["N","Q","A","B","T","I"],"example":"N","description":"Stock Trends exchange suffix. Common examples: N=NYSE, Q=NASDAQ, A=AMEX, T=TSX."}},"safe_example_request":{"method":"POST","path":"/v1/decision/evaluate-symbol","json":{"symbol_exchange":"IBM-N"}},"output_summary":"Deterministic symbol decision with Stock Trends signal and regime context.","related_endpoints":["/v1/market/regime/latest","/v1/indicators/latest","/v1/stim/latest"],"optional":false}]},{"workflow_id":"stim_forecast_review","name":"ST-IM Forecast Review","description":"Review ST-IM forward-return expectations for one symbol across the 4, 13, and 40 week horizons, with indicator and price context.","tags":["agent","research","stim","forecast"],"supported_rails":["subscription","x402","mpp"],"total_stc_cost":0.0335,"total_estimated_usd_cost":0.0335,"pricing_note":"STC is the pricing source of truth. The estimated USD value uses the current operational policy of 1 STC approximately 1 USD and is for planning only.","decision_guidance":"Use when an agent needs to interpret ST-IM expected return distributions for one resolved symbol before making a ranking, review, or portfolio decision.","best_for":"Single-symbol probabilistic forward-return review.","agent_goal_examples":["Review IBM-N ST-IM expectations across 4, 13, and 40 week horizons.","Estimate whether a symbol's ST-IM mean returns exceed base-period means with adequate probability."],"symbol_selection_guidance":"Use symbol_exchange directly when known. If only a ticker is known, first call /v1/instruments/lookup or /v1/instruments/resolve and reuse the returned symbol_exchange.","interpretation_guidance":"/v1/meta/inference and /v1/meta/stim must be consulted before interpreting ST-IM results. Raw x4wk/x13wk/x40wk means are not sufficient alone; compare them to base_period_mean_returns_pct and use x4wksd/x13wksd/x40wksd to estimate the probability of exceeding base means. Preserve provider identity, forecast horizon, distribution, confidence, evidence, uncertainty, explanation, signal source, and auditability. STIM Select-style logic should emphasize 13-week probability of exceeding the base mean >= 55% and lower confidence bounds relative to base-period means where applicable.","required_interpretation_steps":["Call GET /v1/meta/inference before interpreting provider-specific inference outputs.","Call GET /v1/meta/stim before interpreting ST-IM results.","Compare x4wk, x13wk, and x40wk to base_period_mean_returns_pct.","Use x4wksd, x13wksd, and x40wksd to estimate probability of exceeding base means.","Interpret ST-IM probabilities as conditional historical tendencies, not guarantees or buy/sell commands.","Disclose stale or fallback data when is_stale=true or missing_reason is present."],"next_step_guidance":["Use /v1/decision/evaluate-symbol after interpreting ST-IM probability context.","Use /v1/portfolio/evaluate when reviewing the symbol inside an existing allocation."],"steps":[{"step_id":"meta_inference","endpoint":"GET /v1/meta/inference","method":"GET","path":"/v1/meta/inference","pricing_rule_id":null,"stc_cost":0.0,"estimated_usd_cost":0.0,"supported_rails":[],"pricing_note":"Public non-metered planning helper; no STC charge applies.","description":"Retrieve provider-agnostic inference and cognition contract before provider-specific interpretation.","purpose":"Retrieve provider-agnostic inference and cognition contract before provider-specific interpretation.","workflow_role":null,"required_inputs":{},"optional_inputs":{},"safe_example_request":{"method":"GET","path":"/v1/meta/inference","query":{}},"output_summary":null,"related_endpoints":[],"optional":false},{"step_id":"meta_stim","endpoint":"GET /v1/meta/stim","method":"GET","path":"/v1/meta/stim","pricing_rule_id":null,"stc_cost":0.0,"estimated_usd_cost":0.0,"supported_rails":[],"pricing_note":"Public non-metered planning helper; no STC charge applies.","description":"Retrieve ST-IM field definitions and base-period mean returns before interpretation.","purpose":"Retrieve ST-IM field definitions and base-period mean returns before interpretation.","workflow_role":null,"required_inputs":{},"optional_inputs":{},"safe_example_request":{"method":"GET","path":"/v1/meta/stim","query":{}},"output_summary":null,"related_endpoints":[],"optional":false},{"step_id":"stim_latest","endpoint":"GET /v1/stim/latest","method":"GET","path":"/v1/stim/latest","pricing_rule_id":"stim_latest_paid","stc_cost":0.0025,"estimated_usd_cost":0.0025,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Retrieve latest ST-IM forward return distributions for IBM-N or another resolved symbol.","purpose":"Retrieve latest ST-IM forward return distribution outputs for one instrument.","workflow_role":"Forward distribution enrichment.","required_inputs":{"symbol_exchange":{"type":"string","required":true,"example":"IBM-N","safe_default_for_demo":"IBM-N","pattern":"^[A-Z0-9.]+-[A-Z]$","description":"Stock Trends symbol plus exchange suffix."}},"optional_inputs":{"symbol":{"type":"string","required":false,"example":"IBM","description":"Ticker symbol. Use with exchange when symbol_exchange is not supplied."},"exchange":{"type":"string","required":false,"enum":["N","Q","A","B","T","I"],"example":"N","description":"Stock Trends exchange suffix. Common examples: N=NYSE, Q=NASDAQ, A=AMEX, T=TSX."}},"safe_example_request":{"method":"GET","path":"/v1/stim/latest","query":{"symbol_exchange":"IBM-N"}},"output_summary":"ST-IM forward return expectations and statistical distributions across 4, 13, and 40 weeks.","related_endpoints":["/v1/meta/inference","/v1/meta/stim","/v1/indicators/latest","/v1/stim/history","/v1/selections/published/latest"],"optional":false},{"step_id":"indicators_latest","endpoint":"GET /v1/indicators/latest","method":"GET","path":"/v1/indicators/latest","pricing_rule_id":"indicators_latest_paid","stc_cost":0.0035,"estimated_usd_cost":0.0035,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Retrieve latest Stock Trends indicator context for the same symbol.","purpose":"Retrieve the latest weekly Stock Trends indicator row for one instrument.","workflow_role":"Single-symbol signal confirmation.","required_inputs":{"symbol_exchange":{"type":"string","required":true,"example":"IBM-N","safe_default_for_demo":"IBM-N","pattern":"^[A-Z0-9.]+-[A-Z]$","description":"Stock Trends symbol plus exchange suffix."}},"optional_inputs":{"symbol":{"type":"string","required":false,"example":"IBM","description":"Ticker symbol. Use with exchange when symbol_exchange is not supplied."},"exchange":{"type":"string","required":false,"enum":["N","Q","A","B","T","I"],"example":"N","description":"Stock Trends exchange suffix. Common examples: N=NYSE, Q=NASDAQ, A=AMEX, T=TSX."},"cs_only":{"type":"boolean","required":false,"safe_default":true,"example":true,"description":"Filter to Common Stocks only where the endpoint supports instrument type filtering."}},"safe_example_request":{"method":"GET","path":"/v1/indicators/latest","query":{"symbol_exchange":"IBM-N","cs_only":true}},"output_summary":"Latest indicator snapshot with trend classification, trend_cnt, mt_cnt, rsi, rsi_updn, vol_tag, price-change fields, moving averages, and weekly high/low context.","related_endpoints":["/v1/indicators/history","/v1/stim/latest","/v1/selections/history"],"optional":false},{"step_id":"prices_latest","endpoint":"GET /v1/prices/latest","method":"GET","path":"/v1/prices/latest","pricing_rule_id":"prices_latest_paid","stc_cost":0.0025,"estimated_usd_cost":0.0025,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Retrieve latest weekly price context for the same symbol.","purpose":"Retrieve latest weekly price context for one instrument.","workflow_role":"Price context enrichment.","required_inputs":{"symbol_exchange":{"type":"string","required":true,"example":"IBM-N","safe_default_for_demo":"IBM-N","pattern":"^[A-Z0-9.]+-[A-Z]$","description":"Stock Trends symbol plus exchange suffix."}},"optional_inputs":{"symbol":{"type":"string","required":false,"example":"IBM","description":"Ticker symbol. Use with exchange when symbol_exchange is not supplied."},"exchange":{"type":"string","required":false,"enum":["N","Q","A","B","T","I"],"example":"N","description":"Stock Trends exchange suffix. Common examples: N=NYSE, Q=NASDAQ, A=AMEX, T=TSX."},"cs_only":{"type":"boolean","required":false,"safe_default":true,"example":true,"description":"Filter to Common Stocks only where the endpoint supports instrument type filtering."}},"safe_example_request":{"method":"GET","path":"/v1/prices/latest","query":{"symbol_exchange":"IBM-N","cs_only":true}},"output_summary":"Latest weekly price, adjusted close, high/low, volume (actual shares traded), trades, split factor, and price change.","related_endpoints":["/v1/indicators/latest","/v1/prices/history"],"optional":false},{"step_id":"stim_history","endpoint":"GET /v1/stim/history","method":"GET","path":"/v1/stim/history","pricing_rule_id":"stim_history_paid","stc_cost":0.0075,"estimated_usd_cost":0.0075,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Optionally retrieve bounded historical ST-IM distributions using query metadata.","purpose":"Retrieve a symbol-level history of ST-IM distribution records.","workflow_role":"Historical forward-distribution context.","required_inputs":{"symbol_exchange":{"type":"string","required":true,"example":"IBM-N","safe_default_for_demo":"IBM-N","pattern":"^[A-Z0-9.]+-[A-Z]$","description":"Stock Trends symbol plus exchange suffix."}},"optional_inputs":{"symbol":{"type":"string","required":false,"example":"IBM","description":"Ticker symbol. Use with exchange when symbol_exchange is not supplied."},"exchange":{"type":"string","required":false,"enum":["N","Q","A","B","T","I"],"example":"N","description":"Stock Trends exchange suffix. Common examples: N=NYSE, Q=NASDAQ, A=AMEX, T=TSX."},"start":{"type":"string","required":false,"format":"date","example":"2025-01-03","description":"Inclusive start weekdate in YYYY-MM-DD format."},"end":{"type":"string","required":false,"format":"date","example":"2025-12-26","description":"Inclusive end weekdate in YYYY-MM-DD format."},"limit":{"type":"integer","required":false,"safe_default":260,"minimum":1,"maximum":2600,"example":260,"description":"Maximum number of rows returned."},"include_gaps":{"type":"boolean","required":false,"safe_default":false}},"safe_example_request":{"method":"GET","path":"/v1/stim/history","query":{"symbol_exchange":"IBM-N","limit":52}},"output_summary":"Historical ST-IM distributions across 4, 13, and 40 week horizons.","related_endpoints":["/v1/meta/inference","/v1/meta/stim","/v1/stim/latest","/v1/indicators/history"],"optional":true},{"step_id":"indicators_history","endpoint":"GET /v1/indicators/history","method":"GET","path":"/v1/indicators/history","pricing_rule_id":"indicators_history_paid","stc_cost":0.01,"estimated_usd_cost":0.01,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Optionally retrieve bounded historical indicator context using query metadata.","purpose":"Retrieve a bounded weekly history of Stock Trends indicator rows for one instrument.","workflow_role":"Historical signal context and trend persistence review.","required_inputs":{"symbol_exchange":{"type":"string","required":true,"example":"IBM-N","safe_default_for_demo":"IBM-N","pattern":"^[A-Z0-9.]+-[A-Z]$","description":"Stock Trends symbol plus exchange suffix."}},"optional_inputs":{"symbol":{"type":"string","required":false,"example":"IBM","description":"Ticker symbol. Use with exchange when symbol_exchange is not supplied."},"exchange":{"type":"string","required":false,"enum":["N","Q","A","B","T","I"],"example":"N","description":"Stock Trends exchange suffix. Common examples: N=NYSE, Q=NASDAQ, A=AMEX, T=TSX."},"cs_only":{"type":"boolean","required":false,"safe_default":true,"example":true,"description":"Filter to Common Stocks only where the endpoint supports instrument type filtering."},"start":{"type":"string","required":false,"format":"date","example":"2025-01-03","description":"Inclusive start weekdate in YYYY-MM-DD format."},"end":{"type":"string","required":false,"format":"date","example":"2025-12-26","description":"Inclusive end weekdate in YYYY-MM-DD format."},"limit":{"type":"integer","required":false,"safe_default":260,"minimum":1,"maximum":2600,"example":260,"description":"Maximum number of rows returned."}},"safe_example_request":{"method":"GET","path":"/v1/indicators/history","query":{"symbol_exchange":"IBM-N","limit":52,"cs_only":true}},"output_summary":"Weekly indicator history with trend classification, trend_cnt, mt_cnt, rsi, rsi_updn, vol_tag, price-change fields, moving averages, and high/low context.","related_endpoints":["/v1/indicators/latest","/v1/stim/history","/v1/prices/history"],"optional":true},{"step_id":"prices_history","endpoint":"GET /v1/prices/history","method":"GET","path":"/v1/prices/history","pricing_rule_id":"prices_history_paid","stc_cost":0.0075,"estimated_usd_cost":0.0075,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Optionally retrieve bounded historical price context using query metadata.","purpose":"Retrieve weekly price history for one instrument.","workflow_role":"Historical price context.","required_inputs":{"symbol_exchange":{"type":"string","required":true,"example":"IBM-N","safe_default_for_demo":"IBM-N","pattern":"^[A-Z0-9.]+-[A-Z]$","description":"Stock Trends symbol plus exchange suffix."}},"optional_inputs":{"symbol":{"type":"string","required":false,"example":"IBM","description":"Ticker symbol. Use with exchange when symbol_exchange is not supplied."},"exchange":{"type":"string","required":false,"enum":["N","Q","A","B","T","I"],"example":"N","description":"Stock Trends exchange suffix. Common examples: N=NYSE, Q=NASDAQ, A=AMEX, T=TSX."},"cs_only":{"type":"boolean","required":false,"safe_default":true,"example":true,"description":"Filter to Common Stocks only where the endpoint supports instrument type filtering."},"start":{"type":"string","required":false,"format":"date","example":"2025-01-03","description":"Inclusive start weekdate in YYYY-MM-DD format."},"end":{"type":"string","required":false,"format":"date","example":"2025-12-26","description":"Inclusive end weekdate in YYYY-MM-DD format."},"limit":{"type":"integer","required":false,"safe_default":260,"minimum":1,"maximum":2600,"example":260,"description":"Maximum number of rows returned."}},"safe_example_request":{"method":"GET","path":"/v1/prices/history","query":{"symbol_exchange":"IBM-N","limit":52,"cs_only":true}},"output_summary":"Weekly price history for one symbol.","related_endpoints":["/v1/prices/latest","/v1/indicators/history"],"optional":true}]},{"workflow_id":"portfolio_build","name":"Screener → Portfolio Build","description":"Screen for qualifying tickers, construct a portfolio from candidates, then evaluate the constructed portfolio's risk and return profile.","tags":["agent","portfolio","research"],"supported_rails":["subscription","x402","mpp"],"total_stc_cost":2.25,"total_estimated_usd_cost":2.25,"pricing_note":"STC is the pricing source of truth. The estimated USD value uses the current operational policy of 1 STC approximately 1 USD and is for planning only.","decision_guidance":"Use when the agent wants a fresh candidate list and a bounded equal-weight portfolio proposal.","best_for":"First portfolio workflow for agents that need to discover symbols and build an allocation.","agent_goal_examples":["Build a 5-stock equal-weight candidate portfolio from fresh Stock Trends signals.","Use screener output symbols as the candidate context for a portfolio construction run."],"symbol_selection_guidance":"Start with /v1/agent/screener/top. Reuse results[].symbol_exchange from the screener when calling /v1/decision/evaluate-symbol, /v1/stim/latest, /v1/portfolio/evaluate, or /v1/portfolio/compare. Skip duplicate paid symbol calls for repeated symbol_exchange values.","interpretation_guidance":null,"required_interpretation_steps":[],"next_step_guidance":["Use /v1/portfolio/compare to compare the constructed portfolio against an existing allocation.","Use /v1/stim/latest for selected symbols when forward-return distributions are needed."],"steps":[{"step_id":"screener_top","endpoint":"GET /v1/agent/screener/top","method":"GET","path":"/v1/agent/screener/top","pricing_rule_id":"agent_screener_top","stc_cost":0.5,"estimated_usd_cost":0.5,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Screen for top qualifying tickers.","purpose":"Find a ranked candidate set from the latest Stock Trends signal data.","workflow_role":"Candidate discovery and ranking.","required_inputs":{},"optional_inputs":{"limit":{"type":"integer","required":false,"safe_default":25,"minimum":1,"maximum":100},"min_rsi":{"type":"integer","required":false,"safe_default":40,"example":40,"description":"Minimum Stock Trends RSI threshold. RSI baseline is 100."},"exchange":{"type":"string","required":false,"enum":["N","Q","A","B","T","I"]}},"safe_example_request":{"method":"GET","path":"/v1/agent/screener/top","query":{"limit":10,"min_rsi":40}},"output_summary":"Ranked instruments with Stock Trends signal fields and filter summary.","related_endpoints":["/v1/decision/evaluate-symbol","/v1/portfolio/construct","/v1/stim/latest"],"optional":false},{"step_id":"portfolio_construct","endpoint":"POST /v1/portfolio/construct","method":"POST","path":"/v1/portfolio/construct","pricing_rule_id":"portfolio_construct","stc_cost":1.0,"estimated_usd_cost":1.0,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Construct a portfolio from screened candidates.","purpose":"Build an equal-weight candidate portfolio from Stock Trends signals.","workflow_role":"Portfolio construction.","required_inputs":{},"optional_inputs":{"universe":{"type":"string","required":false,"enum":["top"],"safe_default":"top","example":"top","description":"Candidate universe selector. Currently supports top-ranked signal candidates."},"count":{"type":"integer","required":false,"minimum":1,"maximum":10,"safe_default":5,"example":5,"description":"Number of equal-weight positions to construct."},"bias":{"type":"string","required":false,"enum":["auto","bullish","bearish"],"safe_default":"auto","example":"auto","description":"Portfolio orientation selector. auto derives context from market regime signals."},"exchange":{"type":"string","required":false,"enum":["N","Q","A","T"],"example":"N","description":"Optional exchange filter for candidate selection."}},"safe_example_request":{"method":"POST","path":"/v1/portfolio/construct","json":{"universe":"top","count":5,"bias":"auto"}},"output_summary":"Constructed equal-weight portfolio with signal, decision, ST-IM tiebreaker, and regime fields.","related_endpoints":["/v1/agent/screener/top","/v1/portfolio/evaluate","/v1/portfolio/compare"],"optional":false},{"step_id":"portfolio_evaluate","endpoint":"POST /v1/portfolio/evaluate","method":"POST","path":"/v1/portfolio/evaluate","pricing_rule_id":"portfolio_evaluate","stc_cost":0.75,"estimated_usd_cost":0.75,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Evaluate risk and return profile of the constructed portfolio.","purpose":"Evaluate an existing or proposed portfolio.","workflow_role":"Portfolio review.","required_inputs":{"positions":{"type":"array","required":true,"description":"List of symbol/weight positions.","example":[{"symbol_exchange":"IBM-N","weight":1.0}],"items":{"type":"object","properties":{"symbol_exchange":{"type":"string","example":"IBM-N","pattern":"^[A-Z0-9.]+-[A-Z]$","description":"Stock Trends symbol plus exchange suffix."},"weight":{"type":"number","minimum":0,"maximum":1,"example":1.0,"description":"Portfolio weight for this position."}},"required":["symbol_exchange","weight"],"additionalProperties":false}}},"optional_inputs":{},"safe_example_request":{"method":"POST","path":"/v1/portfolio/evaluate","json":{"positions":[{"symbol_exchange":"IBM-N","weight":1.0}]}},"output_summary":"Portfolio-level and position-level Stock Trends evaluation.","related_endpoints":["/v1/portfolio/construct","/v1/portfolio/compare"],"optional":false}]},{"workflow_id":"portfolio_compare_review","name":"Portfolio Compare Review","description":"Evaluate an existing portfolio, construct a proposed alternative, then compare the two portfolios to quantify the difference.","tags":["agent","portfolio"],"supported_rails":["subscription","x402","mpp"],"total_stc_cost":3.0,"total_estimated_usd_cost":3.0,"pricing_note":"STC is the pricing source of truth. The estimated USD value uses the current operational policy of 1 STC approximately 1 USD and is for planning only.","decision_guidance":"Use when the agent needs to evaluate an existing allocation, construct an alternative, and compare both under the same Stock Trends decision framework.","best_for":"Comparing a current allocation against a proposed Stock Trends-informed alternative.","agent_goal_examples":["Evaluate a user portfolio, construct a proposed alternative, then compare score and alignment.","Review whether a newly constructed portfolio improves regime alignment versus a baseline."],"symbol_selection_guidance":"The compare endpoint expects left and right as direct arrays of positions, not wrapper objects. Reuse portfolio arrays returned by /v1/portfolio/construct or positions supplied to /v1/portfolio/evaluate.","interpretation_guidance":null,"required_interpretation_steps":[],"next_step_guidance":["Use comparison.winner, score_delta, and alignment_advantage to summarize differences.","Reuse any symbol_exchange values in losing positions for deeper /v1/decision/evaluate-symbol review."],"steps":[{"step_id":"evaluate_current","endpoint":"POST /v1/portfolio/evaluate","method":"POST","path":"/v1/portfolio/evaluate","pricing_rule_id":"portfolio_evaluate","stc_cost":0.75,"estimated_usd_cost":0.75,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Evaluate current portfolio risk and return profile.","purpose":"Evaluate an existing or proposed portfolio.","workflow_role":"Portfolio review.","required_inputs":{"positions":{"type":"array","required":true,"description":"List of symbol/weight positions.","example":[{"symbol_exchange":"IBM-N","weight":1.0}],"items":{"type":"object","properties":{"symbol_exchange":{"type":"string","example":"IBM-N","pattern":"^[A-Z0-9.]+-[A-Z]$","description":"Stock Trends symbol plus exchange suffix."},"weight":{"type":"number","minimum":0,"maximum":1,"example":1.0,"description":"Portfolio weight for this position."}},"required":["symbol_exchange","weight"],"additionalProperties":false}}},"optional_inputs":{},"safe_example_request":{"method":"POST","path":"/v1/portfolio/evaluate","json":{"positions":[{"symbol_exchange":"IBM-N","weight":1.0}]}},"output_summary":"Portfolio-level and position-level Stock Trends evaluation.","related_endpoints":["/v1/portfolio/construct","/v1/portfolio/compare"],"optional":false},{"step_id":"construct_proposed","endpoint":"POST /v1/portfolio/construct","method":"POST","path":"/v1/portfolio/construct","pricing_rule_id":"portfolio_construct","stc_cost":1.0,"estimated_usd_cost":1.0,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Construct the proposed alternative portfolio.","purpose":"Build an equal-weight candidate portfolio from Stock Trends signals.","workflow_role":"Portfolio construction.","required_inputs":{},"optional_inputs":{"universe":{"type":"string","required":false,"enum":["top"],"safe_default":"top","example":"top","description":"Candidate universe selector. Currently supports top-ranked signal candidates."},"count":{"type":"integer","required":false,"minimum":1,"maximum":10,"safe_default":5,"example":5,"description":"Number of equal-weight positions to construct."},"bias":{"type":"string","required":false,"enum":["auto","bullish","bearish"],"safe_default":"auto","example":"auto","description":"Portfolio orientation selector. auto derives context from market regime signals."},"exchange":{"type":"string","required":false,"enum":["N","Q","A","T"],"example":"N","description":"Optional exchange filter for candidate selection."}},"safe_example_request":{"method":"POST","path":"/v1/portfolio/construct","json":{"universe":"top","count":5,"bias":"auto"}},"output_summary":"Constructed equal-weight portfolio with signal, decision, ST-IM tiebreaker, and regime fields.","related_endpoints":["/v1/agent/screener/top","/v1/portfolio/evaluate","/v1/portfolio/compare"],"optional":false},{"step_id":"compare_portfolios","endpoint":"POST /v1/portfolio/compare","method":"POST","path":"/v1/portfolio/compare","pricing_rule_id":"portfolio_compare","stc_cost":1.25,"estimated_usd_cost":1.25,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Compare current and proposed portfolios to quantify the difference.","purpose":"Compare current and proposed portfolios.","workflow_role":"Portfolio comparison.","required_inputs":{"left":{"type":"array","required":true,"description":"Left portfolio as a direct array of symbol-weight positions.","example":[{"symbol_exchange":"IBM-N","weight":1.0}],"items":{"type":"object","properties":{"symbol_exchange":{"type":"string","example":"IBM-N","pattern":"^[A-Z0-9.]+-[A-Z]$","description":"Stock Trends symbol plus exchange suffix."},"weight":{"type":"number","minimum":0,"maximum":1,"example":1.0,"description":"Portfolio weight for this position."}},"required":["symbol_exchange","weight"],"additionalProperties":false}},"right":{"type":"array","required":true,"description":"Right portfolio as a direct array of symbol-weight positions.","example":[{"symbol_exchange":"MSFT-Q","weight":1.0}],"items":{"type":"object","properties":{"symbol_exchange":{"type":"string","example":"IBM-N","pattern":"^[A-Z0-9.]+-[A-Z]$","description":"Stock Trends symbol plus exchange suffix."},"weight":{"type":"number","minimum":0,"maximum":1,"example":1.0,"description":"Portfolio weight for this position."}},"required":["symbol_exchange","weight"],"additionalProperties":false}}},"optional_inputs":{},"safe_example_request":{"method":"POST","path":"/v1/portfolio/compare","json":{"left":[{"symbol_exchange":"IBM-N","weight":1.0}],"right":[{"symbol_exchange":"MSFT-Q","weight":1.0}]}},"output_summary":"Side-by-side portfolio evaluations and comparison metrics.","related_endpoints":["/v1/portfolio/evaluate","/v1/portfolio/construct"],"optional":false}]}]}