{"dataset":"Stock Trends Market Indicators","provider":"Stock Trends Publications","description":"Weekly structured market intelligence dataset covering North American equities and ETFs, with records extending back to 1980 and 16M+ historical observations, including Stock Trends trend classification, trend persistence, trend maturity, relative strength, unusual volume signals, breadth, leadership, ST-IM (Stock Trends Inference Model) forward return distributions, provider-agnostic inference metadata, market regime analytics, and deterministic decision/portfolio workflows.","service_description":"Autonomous portfolio intelligence API for AI agents. Agent-native probabilistic market intelligence infrastructure for stock analytics, pre-trade research context, and trend screening: multi-decade Stock Trends classification history from 1980 with 16M+ observations, ST-IM (Stock Trends Inference Model) forward-return distributions, provider-agnostic inference metadata, market regime analysis, sector breadth confirmation, leadership rotation analytics, STIM Select probabilistic stock lists, portfolio construction and evaluation, and symbol decision scoring across 4, 13, and 40-week investment horizons. Built for agentic research workflows using x402 and MPP payment rails. Outputs are processed, ranked, and interpretation-ready — not raw price data.","dataset_description":"Weekly structured market intelligence dataset covering North American equities and ETFs, with records extending back to 1980 and 16M+ historical observations, including Stock Trends trend classification, trend persistence, trend maturity, relative strength, unusual volume signals, breadth, leadership, ST-IM (Stock Trends Inference Model) forward return distributions, provider-agnostic inference metadata, market regime analytics, and deterministic decision/portfolio workflows.","provenance_summary":"Stock Trends is a long-horizon market-intelligence framework, not a shallow market-data wrapper. Its historical classification record extends back to 1980 and includes 16M+ observations encoded through a consistent Stock Trends doctrine covering trend, relative performance, relative performance direction, volume, breadth, sector leadership, and regime structure. Agents should treat this historical depth as research provenance for probabilistic interpretation, not as a guarantee of future performance.","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."]},"acquisition_evaluation_guidance":{"guidance":"When deciding whether additional Stock Trends information is worth acquiring for a task, inspect the public resources relevant to that task before deciding: what is offered (GET /.well-known/x402 for payable resources, GET /v1/ai/tools, GET /v1/workflows), how it should be interpreted (GET /v1/meta/inference, GET /v1/meta/stim, GET /v1/meta/indicators), what evidence is available (GET /v1/selections/stim-select/outcomes/summary, GET /v1/stocktrends/portfolios), and what it costs (GET /v1/pricing/catalog, GET /v1/cost-estimate). A service description is not methodology, and methodology is not evidence; read each from its own source. Availability is not evidence of usefulness. Select only the resources relevant to the task, and base the acquisition decision on the material actually inspected.","canonical_source":"/v1/ai/context","procedure":["Identify what the task actually requires.","Inspect what is offered: /.well-known/x402 for payable resources, then /v1/ai/tools and /v1/workflows.","Inspect how it should be interpreted: /v1/meta/inference, /v1/meta/stim, /v1/meta/indicators.","Inspect what evidence is available, family by family: see the evidence block.","Inspect what it costs: /v1/pricing/catalog and /v1/cost-estimate.","Decide from the material actually inspected."],"category_separation":"A service description is not methodology, and methodology is not evidence. Read each from its own source rather than inferring one from another.","availability_is_not_evidence":"The existence of an endpoint says nothing about whether its output is useful for a given task.","scope_rule":"Inspect only the resources relevant to the task. There is no requirement to fetch every public resource.","no_payment_required_to_evaluate":"Every resource named in this guidance is public and non-metered. Evaluating the service does not require a paid call.","decision_is_the_caller's":"This guidance describes how to evaluate. It does not state a conclusion and does not recommend acquiring anything."},"augmentation_role":{"role":"Stock Trends supplies independently derived market context intended to be combined with the consumer's own strategy, research process, forecasting model, or agent objective. It is designed to augment an existing analytical process rather than to replace it, and it does not supply the consumer's objective, constraints, or decision rule. Whether the added context is useful for a given task is for the consumer to determine from the methodology and evidence resources.","supplies":["independently derived weekly market-state classification","cross-sectional breadth and leadership context","market regime context","probabilistic forward-return context from the current inference provider","interpretation semantics and provenance for all of the above"],"does_not_supply":["the consumer's objective function or constraints","the consumer's own baseline model or feature set","trade execution","investment advice or account-specific recommendations"],"fit_assessment":"Whether this context adds anything to a particular process is for the consumer to determine from the methodology and evidence resources."},"evidence":{"separation_rule":"These evidence families use different methodologies, cover different populations, and carry different limitations. Evaluate each on its own terms. Do not combine them into a single performance, edge, or alpha claim, and do not treat any of them as a prediction of future results.","families":[{"family_id":"historical_classification_provenance","name":"Historical classification provenance","evidence_type":"data_foundation","methodology":"Weekly Stock Trends classification of North American equities and ETFs applied under a historically consistent doctrine covering trend state, trend persistence, trend maturity, relative performance, relative performance direction, volume activity, breadth, sector leadership, and regime structure.","provenance":"Records extend back to 1980 with 16M+ observations, updated weekly. Stable classification semantics are what make observations from different periods comparable for longitudinal research.","what_it_is":"The data foundation the rest of the service is built on, and the basis for comparing a current state against historically similar states.","what_it_is_not":"Not a performance result, not a backtest, and not an outcome measurement.","inspect_at":["/v1/meta/indicators","/v1/ai/context"],"limitations":["Historical depth supports research and probabilistic interpretation but does not guarantee future performance.","Externally named market events are not native Stock Trends labels unless separately curated.","Stock Trends outputs are not investment advice, price targets, or direct buy/sell commands."]},{"family_id":"inference_outcome_evidence","name":"ST-IM Select realized outcome evidence","evidence_type":"aggregate_signal_rule_outcomes","methodology":"Realized forward returns for historical observations meeting ST-IM Select criteria, measured at the 4, 13, and 40-week horizons against the corresponding base-period mean returns, restricted to observations whose measurement window has completed.","provenance":"Aggregated from the Stock Trends classification record and the ST-IM provider profile published at /v1/meta/stim. Responses carry generated_at and source_latest_mature_weekdate so a caller can audit recency.","what_it_is":"An aggregate outcome measurement for a stated signal rule, over a stated historical population, at stated horizons.","what_it_is_not":"Not current selections, not individual symbols, not a portfolio result, and not a claim that any individual observation outperformed.","inspect_at":["/v1/selections/stim-select/outcomes/summary","/v1/meta/stim"],"limitations":["Aggregate only; current selections and individual symbols are out of scope.","Distribution-level tendencies do not describe any individual outcome.","Subject to regime shifts, non-stationarity, sample-size weakness, and tail events.","Stock Trends outputs are not investment advice, price targets, or direct buy/sell commands."]},{"family_id":"model_portfolio_and_strategy_records","name":"Stock Trends model-portfolio and strategy records","evidence_type":"rule_based_model_records","methodology":"Official Stock Trends model portfolios built from declared strategy rules, exposed with their return histories, closed-position records, and the strategy definitions they were constructed from, so the rules and the recorded results can be inspected together.","provenance":"Live official Stock Trends model portfolio metadata and history. Current live holdings and current buy/sell candidates are intentionally excluded.","what_it_is":"An inspectable rule-based model record with a declared ruleset.","what_it_is_not":"Not audited brokerage-account performance, not live capital, and not a representation of returns any account achieved.","inspect_at":["/v1/stocktrends/portfolios","/v1/stocktrends/portfolios/{port_id}/returns","/v1/stocktrends/portfolios/{port_id}/summary","/v1/stocktrends/portfolios/{port_id}/positions/history","/v1/stocktrends/strategies"],"limitations":["Rule-based model records with declared cost and stop-loss assumptions; not audited brokerage-account performance.","Realised transaction costs and slippage may differ from the declared assumptions.","Stock Trends outputs are not investment advice, price targets, or direct buy/sell commands."]}],"illustrative_structure_surface":{"endpoint":"/v1/ai/proof/market-edge","content":"static illustrative field structure","what_it_is":"A free, unauthenticated view of signal field structure and response shape, for confirming schemas before paid calls.","what_it_is_not":"Not live market data, and not outcome or performance evidence."}},"service_identity":{"short_name":"Stock Trends API","primary_category":"agent_native_probabilistic_market_intelligence_infrastructure","dominant_description":"Agent-native probabilistic market intelligence infrastructure for autonomous market-research agents.","is":["processed_weekly_stock_trends_signals","probabilistic_forward_return_inference","market_regime_breadth_and_leadership_context","deterministic_decision_and_portfolio_analytics"],"is_not":["raw_market_data_api","generic_screener_api","trade_execution_system","investment_adviser","investment_advice"],"core_methodology":["Stock Trends trend classification","relative performance versus benchmark","trend persistence and maturity","long-horizon classification provenance","ST-IM forward-return distributions","market structure confirmation"],"forecast_horizons_weeks":[4,13,40]},"cognition_architecture":{"source":"docs/STOCK_TRENDS_COGNITION_ARCHITECTURE.md","inference_contract_endpoint":"/v1/meta/inference","current_baseline_provider_profile":"/v1/meta/stim","current_baseline_provider":"stim","doctrine":["ST-IM is the current baseline inference provider, not the final intelligence layer.","Future Causal AI is a first-class future inference provider.","Discovery, metadata, OpenAPI, x402/MPP surfaces, and future MCP tools should use provider-agnostic inference concepts where practical.","Reasoning interfaces must preserve uncertainty, evidence, explanations, confidence, signal sources, and auditability."],"provider_agnostic_concepts":["inference_provider","signal_source","forecast_horizon","probability_distribution","confidence_measure","evidence","uncertainty","explanation","reasoning_interpretation","auditability"],"available_providers":[{"provider_id":"stim","name":"Stock Trends Inference Model","status":"current_baseline","profile_endpoint":"/v1/meta/stim","role":"durable, explainable baseline inference provider"}],"current_baseline_provider_role":"current_baseline_inference_provider","future_provider_compatibility":"Future Causal AI providers should integrate through the same inference contract."},"discovery_entrypoints":{"primary_machine_readable":"/.well-known/x402","x402_payment_resources":"/.well-known/x402","task_and_tool_discovery":"/v1/ai/tools","secondary_explanatory":"/v1/ai/context","provider_agnostic_inference_contract":"/v1/meta/inference","stim_provider_profile":"/v1/meta/stim","docs":"/v1/docs","openapi":"/v1/openapi.json"},"update_frequency":"weekly","last_update":"2026-10-09","coverage":{"region":"North America","asset_types":["equities","ETFs"],"historical_coverage_start_year":1980,"approximate_observation_count":"16M+","forecast_horizons_weeks":[4,13,40]},"core_indicators":["trend","trend_cnt","mt_cnt","rsi","rsi_updn","vol_tag"],"field_definitions":{"trend":"Primary Stock Trends trend classification for the instrument.","trend_cnt":"Number of consecutive weeks the current trend classification has persisted.","mt_cnt":"Number of weeks the instrument has remained in its current major trend category.","rsi":"Relative performance ratio versus the S&P 500 benchmark over 13 weeks. Baseline = 100. Values >100 indicate outperformance; <100 indicate underperformance. Not the traditional Wilder RSI oscillator.","rsi_updn":"Weekly direction of relative strength versus benchmark.","vol_tag":"Unusual volume classification for the current week."},"analytical_framework":{"positioning":"Not a raw market data or generic screener service. Outputs are processed, ranked, and interpretation-ready. Each endpoint family serves a distinct analytical role in a research chain.","primary_unit_of_analysis":"weekly Stock Trends signal state plus probabilistic forward-return context","not_raw_market_data":true,"not_generic_screener":true,"rsi_benchmark_baseline":{"field":"rsi","baseline":100,"meaning":"relative performance versus benchmark; >100 outperformance, <100 underperformance","not":"traditional Wilder RSI oscillator","primary_definition":"/v1/meta/indicators","see_also":"interpretation_dependencies.rsi"},"market_structure_context":["market_regime","breadth_confirmation","leadership_concentration","leadership_rotation"],"endpoint_roles":{"market_regime_classifier":"Classifies current market regime from trend distribution. Sets portfolio analysis context.","market_breadth_context":"Measures sector/industry signal participation. Confirms or contradicts regime reading.","leadership_intelligence":"Identifies where RSI outperformance and bullish trend alignment are concentrated.","market_intelligence_filter":"Ranks candidate securities by signal quality before deeper analysis.","probabilistic_forward_inference":"ST-IM forward return distributions. Not momentum — requires base-period mean comparison.","probabilistic_selection_list":"STIM Select: securities satisfying all three ST-IM lower-bound thresholds plus prob13wk >= 55%.","probabilistic_selection_universe":"Base ST-IM selection universe without the published three-horizon threshold filter.","symbol_signal_intelligence":"Current and historical Stock Trends indicator fields for a symbol.","symbol_decision_engine":"Deterministic decision-support context combining symbol signals and regime context.","portfolio_construction_engine":"Produces ranked equal-weight portfolio construction analysis from eligible signal candidates.","portfolio_evaluation_engine":"Evaluates or compares portfolios against current signal and regime context.","curated_signal_report":"Named STWR screening reports: Stock Trends editorial signal lists.","price_context":"Weekly price rows as supporting context for signal interpretation."}},"analytical_chain":{"description":"Recommended research sequence for a full probabilistic market intelligence workflow.","steps":[{"step":1,"role":"semantic_context","endpoint":"/v1/ai/context","purpose":"Load this conceptual operating manual before flattening endpoints into generic tools."},{"step":2,"role":"workflow_selection","endpoint":"/v1/workflows","purpose":"Choose a mission-level workflow and inspect live step costs before paid execution."},{"step":3,"role":"inference_contract","endpoint":"/v1/meta/inference","purpose":"Load the provider-agnostic inference and cognition contract before interpreting provider-specific outputs."},{"step":4,"role":"interpretation_metadata","endpoint":"/v1/meta/stim","also_use":["/v1/meta/indicators","/v1/leadership/definitions"],"purpose":"Load ST-IM provider profile, base-period means, indicator definitions, RSI baseline semantics, and leadership definitions."},{"step":5,"role":"market_regime_classifier","endpoint":"/v1/market/regime/latest","purpose":"Classify current regime and set portfolio analysis context."},{"step":6,"role":"market_breadth_context","endpoint":"/v1/breadth/sector/latest","purpose":"Confirm regime reading with sector-level signal participation."},{"step":7,"role":"leadership_intelligence","endpoint":"/v1/leadership/summary/latest","purpose":"Identify sectors and stocks with concentrated RSI outperformance."},{"step":8,"role":"market_intelligence_filter","endpoint":"/v1/agent/screener/top","purpose":"Discover ranked signal candidates before deeper analysis."},{"step":9,"role":"probabilistic_forward_inference","endpoint":"/v1/stim/latest","purpose":"Enrich candidates with forward return distributions. Requires /v1/meta/inference and /v1/meta/stim for interpretation."},{"step":10,"role":"symbol_decision_engine","endpoint":"/v1/decision/evaluate-symbol","purpose":"Evaluate candidate with deterministic decision-support context in the current regime."},{"step":11,"role":"portfolio_construction_engine","endpoint":"/v1/portfolio/construct","purpose":"Run equal-weight portfolio construction analysis from scored candidates."},{"step":12,"role":"portfolio_evaluation_engine","endpoint":"/v1/portfolio/compare","purpose":"Compare portfolio alternatives; assess signal score and regime alignment differences."}]},"probabilistic_semantics":{"provider_agnostic_contract":{"endpoint":"/v1/meta/inference","architecture_source":"docs/STOCK_TRENDS_COGNITION_ARCHITECTURE.md","available_provider_profiles":{"stim":"/v1/meta/stim"},"future_provider_compatibility":"Future causal AI providers should use the same inference vocabulary for provider identity, horizon, distribution, confidence, evidence, uncertainty, explanation, signal source, and auditability."},"stim_model":{"full_name":"Stock Trends Inference Model","inference_provider_id":"stim","provider_role":"current_baseline_inference_provider","provider_profile_endpoint":"/v1/meta/stim","not_final_intelligence_layer":true,"provenance_summary":"ST-IM is an inference layer built on decades of Stock Trends classification history. Its value is not only point-in-time prediction, but probabilistic interpretation of current signals against long-horizon historical behavior. ST-IM outputs are not guarantees, price targets, investment advice, or direct buy/sell commands.","output_type":"probabilistic forward return distribution","not_momentum":true,"not":["momentum_indicator","simple_price_change_model","generic_technical_indicator"],"horizons_weeks":[4,13,40],"fields_per_horizon":{"xNwk":"expected mean return","xNwk1":"lower confidence bound","xNwk2":"upper confidence bound","xNwksd":"standard deviation"},"base_period_means_pct":{"x4wk":0.0,"x13wk":2.19,"x40wk":6.45},"comparison_required":true,"comparison_rule":"Compare each ST-IM mean and lower confidence bound against the matching base-period mean return.","primary_probability_field":"prob13wk","randomness_assumption":"Markets are noisy, uncertain, and partly random; ST-IM estimates conditional historical tendencies.","distribution_assumption":"normal approximation with central-limit-theorem intuition across large historical observation populations","classification_role":"Stock Trends classifications convert weekly market behavior into structured factor states used to form comparable historical populations.","limitations":["regime_shifts","non_stationarity","sample_size_weakness","tail_events","liquidity_shocks","news_shocks","uncertainty_in_individual_stock_outcomes"],"interpretation_requirement":"Always fetch /v1/meta/inference and /v1/meta/stim before interpreting ST-IM outputs. A positive raw mean is not bullish unless it exceeds the relevant base-period mean. Probabilities are conditional historical tendencies, not guarantees or direct buy/sell commands."},"stim_select":{"description":"Securities satisfying all four publication criteria simultaneously.","thresholds_source":"/v1/meta/stim","criteria_context":"Current explanatory STIM Select methodology; use /v1/meta/stim for authoritative base-period threshold context.","criteria":{"x4wk1":{"operator":">","threshold_pct":0.0,"description":"4-week lower CI bound > base-period mean of 0%"},"x13wk1":{"operator":">","threshold_pct":2.19,"description":"13-week lower CI bound > base-period mean of 2.19%"},"x40wk1":{"operator":">","threshold_pct":6.45,"description":"40-week lower CI bound > base-period mean of 6.45%"},"prob13wk":{"operator":">=","threshold":0.55,"description":"Probability of exceeding 13-week base-period mean >= 55%"}},"ranking":"prob13wk descending","note":"Probabilistic candidates — not investment advice. Not guaranteed outcomes."},"regime_score":{"formula":"bullish_pct - bearish_pct","range":[-1.0,1.0],"interpretation":"Portfolio analysis input, not a trade entry signal.","confirmation_required":"Compare with /v1/breadth/sector/latest and /v1/leadership/summary/latest."}},"endpoint_family_relationships":{"screener_top":{"endpoints":["/v1/agent/screener/top"],"use_when":"broad candidate discovery","semantics":"ranked Stock Trends signal filter, not a generic screener","feeds":["/v1/stim/latest","/v1/decision/evaluate-symbol","/v1/portfolio/construct"]},"selections_latest":{"endpoints":["/v1/selections/latest","/v1/selections/history"],"use_when":"filtered and ranked STIM candidate universe","semantics":"base ST-IM selection records ranked by prob13wk; no published threshold filter applied","interpret_with":["/v1/meta/inference","/v1/meta/stim","/v1/stim/latest"]},"selections_published":{"endpoints":["/v1/selections/published/latest","/v1/selections/published/history"],"use_when":"strict STIM Select-style candidates","semantics":"current STIM Select methodology using three-horizon lower-bound thresholds plus prob13wk publication criteria","thresholds_source":"/v1/meta/stim","authoritative_threshold_context":"/v1/meta/stim","interpret_with":["/v1/meta/inference","/v1/meta/stim"]},"stim_select_outcomes":{"endpoints":["/v1/selections/stim-select/outcomes/summary"],"use_when":"public aggregate evidence for historical ST-IM Select signal-rule outcomes","semantics":"historical realized outcome evidence for observations meeting ST-IM Select criteria; legacy outcomes use fpr_chg13, while default no-date responses read stweekly.stim_select_outcome_summary and expose fpr_chg4, fpr_chg13, and fpr_chg40 metrics; seeded no-date cache rows support limit_rank omitted/null and limit_rank=10","business_boundary":"aggregate only; no current selections, current matching symbols, or individual symbols","interpret_with":["/v1/meta/inference","/v1/meta/stim"]},"stim":{"endpoints":["/v1/stim/latest","/v1/stim/history"],"use_when":"symbol-specific probabilistic forward-return analysis","semantics":"ST-IM distributions across 4, 13, and 40-week horizons","interpret_with":["/v1/meta/inference","/v1/meta/stim","/v1/indicators/latest"]},"indicators":{"endpoints":["/v1/indicators/latest","/v1/indicators/history"],"use_when":"Stock Trends signal context for a symbol","semantics":"trend classification, persistence, maturity, RSI baseline 100, volume tags","research_provenance":"Stock Trends indicators are part of a multi-decade classification framework with records extending back to 1980. Their value comes from consistent semantics across market history: trend state, trend persistence, relative performance, relative performance direction, and volume activity are encoded in a stable doctrine designed for longitudinal research.","interpret_with":["/v1/meta/indicators"]},"regime":{"endpoints":["/v1/market/regime/latest","/v1/market/regime/history","/v1/market/regime/forecast"],"use_when":"market-structure context and portfolio bias","semantics":"market-level trend distribution; confirm before using as bias input","confirm_with":["/v1/breadth/sector/latest","/v1/leadership/summary/latest"]},"breadth":{"endpoints":["/v1/breadth/sector/latest","/v1/breadth/sector/history"],"use_when":"participation and confirmation","semantics":"sector/industry participation behind regime and candidate quality","confirm_with":["/v1/market/regime/latest","/v1/leadership/summary/latest"]},"leadership":{"endpoints":["/v1/leadership/summary/latest","/v1/leadership/rotation/history"],"use_when":"concentration and rotation analysis","semantics":"where benchmark-relative performance and trend alignment are concentrated or rotating","interpret_with":["/v1/leadership/definitions"]},"decision":{"endpoints":["/v1/decision/evaluate-symbol"],"use_when":"single-symbol decision evaluation","semantics":"deterministic synthesis of symbol signal and regime context","feeds":["/v1/portfolio/evaluate","/v1/portfolio/compare"]},"portfolio":{"endpoints":["/v1/portfolio/construct","/v1/portfolio/evaluate","/v1/portfolio/compare"],"use_when":"portfolio analysis and comparison","semantics":"candidate evidence, regime context, and signal structure synthesized into portfolio analysis scores","depends_on":["/v1/market/regime/latest","/v1/agent/screener/top","/v1/stim/latest"]}},"workflow_guidance":{"stim_forecast_review":{"mission":"Review one symbol's ST-IM forward-return distributions across 4, 13, and 40 weeks.","start_with":["/v1/meta/inference","/v1/meta/stim","/v1/instruments/resolve"],"core_path":["/v1/stim/latest","/v1/indicators/latest","/v1/stim/history"],"success_condition":"Compare ST-IM means, confidence bounds, and probabilities against base-period means."},"sector_rotation_analysis":{"workflow_id_available":false,"mission":"Evaluate regime, breadth participation, leadership concentration, and sector rotation.","core_path":["/v1/market/regime/latest","/v1/breadth/sector/latest","/v1/leadership/summary/latest","/v1/leadership/rotation/history"],"success_condition":"Separate broad participation from narrow leadership concentration before selecting candidates."},"portfolio_build":{"mission":"Discover candidates and run bounded Stock Trends-informed portfolio construction analysis.","core_path":["/v1/agent/screener/top","/v1/portfolio/construct","/v1/portfolio/evaluate"],"success_condition":"Portfolio analysis output includes candidate evidence, resolved context, regime context, and score structure."},"portfolio_compare_review":{"mission":"Compare an existing allocation with a Stock Trends-informed analytical alternative.","core_path":["/v1/portfolio/evaluate","/v1/portfolio/construct","/v1/portfolio/compare"],"success_condition":"Explain score_delta, winner, alignment advantage, and regime fit without presenting advice."},"symbol_decision":{"mission":"Evaluate a known symbol in current regime context.","start_with":["/v1/instruments/resolve","/v1/market/regime/latest"],"core_path":["/v1/decision/evaluate-symbol","/v1/indicators/latest","/v1/stim/latest"],"success_condition":"Report deterministic decision-support context, confidence, signal notes, and ST-IM context when requested."},"full_research_sweep":{"workflow_id_available":false,"mission":"Run the recommended analytical chain end to end with budget controls.","core_path":["/v1/ai/context","/v1/workflows","/v1/meta/inference","/v1/meta/stim","/v1/market/regime/latest","/v1/breadth/sector/latest","/v1/leadership/summary/latest","/v1/agent/screener/top","/v1/stim/latest","/v1/decision/evaluate-symbol","/v1/portfolio/construct","/v1/portfolio/compare"],"success_condition":"Produce research context that preserves regime, breadth, leadership, ST-IM, decision, and portfolio evidence."}},"decision_boundaries":{"stock_trends_is_not":["raw_market_data_api","generic_screener_api","trade_execution_system","investment_adviser","investment_advice"],"stim_is_not":["momentum_indicator","simple_price_change_signal"],"regime_breadth_leadership":"market-structure context; do not treat as standalone trade instructions","selections":"filtered or published ST-IM candidate universes, not guaranteed outcomes","portfolio_outputs":"analytical synthesis for research review, not account-specific advice"},"interpretation_dependencies":{"stim":{"required_endpoint":"/v1/meta/stim","provider_agnostic_contract_endpoint":"/v1/meta/inference","required_before":["/v1/meta/inference","/v1/stim/latest","/v1/stim/history","/v1/selections/latest","/v1/selections/published/latest"],"dependency":"base-period mean returns for 4, 13, and 40-week horizons"},"indicators":{"required_endpoint":"/v1/meta/indicators","dependency":"trend codes, trend_cnt, mt_cnt, rsi, rsi_updn, and vol_tag definitions"},"rsi":{"benchmark":"S&P 500","benchmark_baseline":100,"above_baseline":"outperformance","below_baseline":"underperformance","not":"traditional Wilder RSI oscillator","primary_definition":"/v1/meta/indicators","see_also":"analytical_framework.rsi_benchmark_baseline"},"leadership":{"recommended_endpoint":"/v1/leadership/definitions","dependency":"leadership screens, ranking fields, and taxonomy levels"},"pricing":{"required_endpoint":"/v1/pricing/catalog","dependency":"live STC costs before autonomous paid execution"}},"post_endpoint_execution_semantics":{"scope":"analytical POST endpoints only","descriptive_metadata_only":true,"runtime_behavior_changed":false,"common":{"state_mutation":false,"bounded_cost":true,"safe_for_autonomous_execution_with_budget_controls":true,"requires_auth_or_payment":true,"pricing_source":"/v1/pricing/catalog"},"endpoints":{"/v1/decision/evaluate-symbol":{"state_mutation":false,"bounded_cost":true,"deterministic_for_identical_inputs":true,"safe_for_autonomous_execution_with_budget_controls":true},"/v1/portfolio/construct":{"state_mutation":false,"bounded_cost":true,"deterministic_for_identical_inputs":true,"determinism_scope":"same inputs, same weekly data snapshot, same eligible universe","safe_for_autonomous_execution_with_budget_controls":true},"/v1/portfolio/evaluate":{"state_mutation":false,"bounded_cost":true,"deterministic_for_identical_inputs":true,"safe_for_autonomous_execution_with_budget_controls":true},"/v1/portfolio/compare":{"state_mutation":false,"bounded_cost":true,"deterministic_for_identical_inputs":true,"safe_for_autonomous_execution_with_budget_controls":true}}},"research_context_not_investment_advice":{"not_investment_advice":true,"agent_instruction":"Present outputs as probabilistic market research context, not instructions to buy or sell.","no_guarantee":"ST-IM, selections, decisions, and portfolio scores are analytical outputs, not guaranteed outcomes.","user_context_required":"Agents should combine outputs with user objectives, constraints, and independent review."},"recommended_starting_paths":{"autonomous_agent_discovery":["/.well-known/x402","/v1/ai/context","/v1/workflows","/v1/pricing/catalog","/v1/ai/tools"],"interpretation_setup":["/v1/meta/indicators","/v1/meta/inference","/v1/meta/stim","/v1/leadership/definitions"],"candidate_discovery":["/v1/market/regime/latest","/v1/breadth/sector/latest","/v1/leadership/summary/latest","/v1/agent/screener/top","/v1/selections/latest","/v1/selections/published/latest"],"symbol_review":["/v1/instruments/resolve","/v1/indicators/latest","/v1/stim/latest","/v1/decision/evaluate-symbol"],"portfolio_synthesis":["/v1/portfolio/construct","/v1/portfolio/evaluate","/v1/portfolio/compare"]},"trend_categories":{"^+":"bullish","^-":"weak bullish","v^":"bullish crossover","v-":"bearish","v+":"weak bearish","^v":"bearish crossover"},"endpoint_groups":{"discovery":["/.well-known/x402","/v1/ai/tools","/v1/ai/context","/v1/ai/proof/market-edge","/v1/docs","/v1/openapi.json"],"planning_helpers":["/v1/cost-estimate","/v1/workflows","/v1/instruments/lookup","/v1/instruments/resolve","/v1/stwr/reports/catalog","/v1/meta/indicators","/v1/meta/inference","/v1/meta/stim","/v1/meta/stwr","/v1/leadership/definitions","/v1/ai/proof/market-edge"],"pricing":["/v1/pricing","/v1/pricing/catalog","/v1/workflows","/v1/cost-estimate"],"instruments":["/v1/instruments/lookup","/v1/instruments/resolve"],"screening":["/v1/agent/screener/top"],"stim":["/v1/stim/latest","/v1/stim/history"],"market":["/v1/market/regime/latest","/v1/market/regime/history","/v1/market/regime/forecast"],"decision":["/v1/decision/evaluate-symbol"],"portfolio":["/v1/portfolio/construct","/v1/portfolio/evaluate","/v1/portfolio/compare"],"breadth":["/v1/breadth/sector/latest","/v1/breadth/sector/history"],"leadership":["/v1/leadership/definitions","/v1/leadership/summary/latest","/v1/leadership/rotation/history"],"selections":["/v1/selections/latest","/v1/selections/history","/v1/selections/published/latest","/v1/selections/published/history"]},"access_model":{"public_discovery":["/.well-known/x402","/v1/ai/tools","/v1/ai/context","/v1/ai/proof/market-edge","/v1/docs","/v1/openapi.json"],"subscription_supported":true,"x402_agent_pay":"live","mpp":"live"},"auth":{"subscription_scheme":"X-API-Key","subscription_header":"X-API-Key: YOUR_API_KEY","alternative_scheme":"Bearer","alternative_header":"Authorization: Bearer YOUR_API_KEY","agent_identity_headers":["X-StockTrends-Agent-Id","X-StockTrends-Agent-Type","X-StockTrends-Agent-Vendor","X-StockTrends-Agent-Version"],"payment_headers":["X-StockTrends-Payment-Method","X-StockTrends-Payment-Network","X-StockTrends-Payment-Token","X-StockTrends-Payment-Reference","X-StockTrends-Payment-Amount"]},"pricing":{"catalog_endpoint":"/v1/pricing/catalog","pricing_metadata_endpoint":"/v1/pricing","workflow_registry_endpoint":"/v1/workflows","cost_estimate_endpoint":"/v1/cost-estimate","planning_role":"/v1/pricing explains payment identity, agent identity, accepted headers, and rails; /v1/pricing/catalog gives concrete endpoint prices; /v1/workflows gives task-level strategy.","note":"Use the live pricing catalog and API response headers as the authoritative source of endpoint pricing and payment requirements."},"usage_guidance":["Start with /.well-known/x402 for payable-resource discovery, then use /v1/ai/tools for task and tool discovery.","Use /v1/ai/context as the secondary explanatory endpoint for dataset and endpoint-family context.","Before deciding whether paid Stock Trends information is worth acquiring for a task, follow acquisition_evaluation_guidance: inspect the relevant capability, interpretation, evidence, and pricing resources, keep those categories separate, and decide from what was actually inspected.","Use /v1/ai/proof/market-edge (no auth required) to inspect response structure and confirm field schemas. It returns a static synthetic body and is an illustration, not evidence of usefulness.","Use /v1/docs and /v1/openapi.json for exact request and response contracts.","Use /v1/workflows to select a market-research strategy and endpoint sequence.","Use planning helpers (/v1/cost-estimate, /v1/instruments/lookup, /v1/instruments/resolve, /v1/stwr/reports/catalog, /v1/meta/indicators, /v1/meta/inference, /v1/meta/stim, /v1/meta/stwr, /v1/leadership/definitions) to resolve symbols, estimate costs, and understand metadata before paid calls.","Use /v1/pricing/catalog to discover live pricing rules before calling premium endpoints.","Use /v1/pricing to understand payment identity, agent identity, accepted headers, and supported rails.","For x402, the HTTP 402 stocktrends_preview is the final pre-payment surface: inspect it to confirm purpose, inputs, response shape, related endpoints, pricing_rule_id, cost, and rails before paying. It is not the mechanism for discovering endpoint parameters — use /v1/ai/tools or /v1/openapi.json for input schemas, and make the request serviceable before paying. Receiving the challenge does not require a serviceable request: an eligible recognized fixed-price resource answers a bare unpaid probe with it, while availability-gated and parameterized resources resolve availability or path identity first.","Once a payment proof is presented, deterministically invalid input is rejected before any payment challenge or settlement: a malformed symbol_exchange, a missing required parameter combination, an unsupported sort/exchange/trend value, or a semantically incomplete body returns a 400 or 422 input error and nothing is verified or settled. An unpaid probe of an eligible recognized fixed-price resource is answered with the 402 challenge instead, so its payment and input contract is readable at the canonical resource URL; availability-gated and parameterized resources are documented exceptions. Pricing context headers remain on the input error, so the price is still discoverable once the request is corrected.","Use subscription access for persistent developer workflows and x402 for agent-native pay-per-request access.","Start premium agent-pay workflows with /v1/agent/screener/top or /v1/stim/latest.","Cache discovery and metadata responses where appropriate because the dataset updates weekly."],"example_queries":[{"description":"Look up an instrument by symbol","path":"/v1/instruments/lookup?symbol=AAPL"},{"description":"Get a premium ranked screener result set","path":"/v1/agent/screener/top"},{"description":"Retrieve the latest ST-IM distribution for one symbol","path":"/v1/stim/latest?symbol_exchange=IBM-N"},{"description":"Retrieve the current market regime classification","path":"/v1/market/regime/latest"}],"recommended_first_flows":{"human_developer":["/v1/docs","/v1/openapi.json","/v1/pricing/catalog","/v1/stim/latest?symbol_exchange=IBM-N"],"agent":["/.well-known/x402","/v1/ai/tools","/v1/ai/context","/v1/pricing/catalog","/v1/agent/screener/top"]},"docs":"https://api.stocktrends.com/v1/docs","openapi":"https://api.stocktrends.com/v1/openapi.json","llms_txt":"https://api.stocktrends.com/llms.txt","ai_plugin":"https://api.stocktrends.com/.well-known/ai-plugin.json","x402_discovery":"https://api.stocktrends.com/.well-known/x402","tools_manifest":"https://api.stocktrends.com/v1/ai/tools","license":"https://stocktrends.com/stock-trends-data-license","terms":"https://stocktrends.com/terms-of-use","support":{"email":"api@stocktrends.com"}}