Evaluating the Stock Trends API

Use Stock Trends when you need classified market states, probabilistic forward-return context, mature outcome evidence, portfolio return history, and agent-ready workflow metadata — not just quotes and OHLCV.

This page provides framework evaluation evidence for developers, AI agents, researchers, and prospective customers. It documents the historical foundation, ST-IM realized outcome data, Monte Carlo process analysis, portfolio evidence endpoints, and agent research workflows. These materials support evaluation and research — they are not guarantees or price targets.

Stock Trends API vs. a Generic Market Data API

The Stock Trends API is not a data pipe. It layers a decades-tested classification and inference framework on top of market data, making it practical to build evidence-grounded agent workflows without assembling the framework yourself.

The Stock Trends Classification Framework

The Stock Trends framework transforms weekly price and volume data into structured, named market states. This classification layer makes long-horizon statistical research possible: it creates repeatable, comparable observations across decades and market cycles.

Core framework elements exposed through the API:

• Trend classification — Bullish, Bearish, Weak Bullish, Weak Bearish, and crossover states
• Relative strength vs. the S&P 500 — above or below benchmark, with direction
• Volume behavior — high, low, or normal relative to historical norms
• Multi-horizon forward outcome tracking — 4-week, 13-week, and 40-week horizons
• Market breadth and sector leadership — regime context across exchanges

The framework is designed to improve the distribution of investment outcomes by supporting more systematic, evidence-based decision-making. It does not issue simplistic buy/sell commands or guarantee results.

ST-IM Select: Mature Realized Outcome Evidence

The Stock Trends Inference Model (ST-IM) uses base-period means derived from the full historical observation record as evaluation thresholds. ST-IM Select identifies observations whose modeled return distributions exceed those thresholds across forward-return horizons.

The table below shows mature realized outcomes from historical ST-IM Select observations. These are actual forward returns from observations that have already completed their measurement window — not projections. The data is available live through the API at GET /v1/selections/stim-select/outcomes/summary.

How to read this table:

• Avg return exceeds the base-period mean at all three horizons, indicating the ST-IM Select filter has historically identified observations with above-baseline average returns.
• Median return is lower than the average, reflecting a distribution with positive skew and a wide range of outcomes — most observations cluster near or slightly above zero, with meaningful upside cases pulling the average higher.
• Outperform base rate at 13w and 40w is below 50%, meaning most individual observations do not outperform the base-period mean — this is consistent with average performance being driven by a skewed distribution rather than uniform outperformance.
• These results are intended as framework evaluation evidence, not as projections of future returns.

Picks of the Week: Monte Carlo Simulation

Picks of the Week is a long-running weekly Stock Trends report based on stable, rule-based selection criteria. Monte Carlo simulation characterizes process-level outcome distributions: rather than measuring isolated average returns, it stress-tests repeated application of the same selection process across many simulated portfolio sequences.

Two simulation methods are used:

• Realistic simulation — follows actual historical chronology and weekly available Picks of the Week populations, as the process would have been applied in practice
• Theoretical simulation — samples from the full return distribution without chronological constraint

Simulation results (portfolio growth multiples from a normalized starting value of 1.0):

The wide range from minimum to maximum outcome reflects realistic uncertainty in repeated process application. These simulations characterize possible outcome distributions — they do not prove guaranteed alpha or eliminate the possibility of loss.

Self-hosted developer deployment planned.

Portfolio Evidence

The Stock Trends API exposes portfolio return history and strategy framework context as structured endpoints. These allow agents and researchers to evaluate actual portfolio-level evidence alongside the strategy rules that governed it.

Return evidence endpoints

• GET /v1/stocktrends/portfolios/{port_id}/returns — portfolio return history by portfolio ID for live Stock Trends portfolios where return history is exposed. Use to evaluate portfolio-level outcome evidence.

Strategy and methodology context endpoints

• GET /v1/stocktrends/strategies — list all available strategies with definitions
• GET /v1/stocktrends/strategies/{strategy_id} — full strategy detail including buy/sell conditions, stop-loss settings, and investment assumptions
• GET /v1/stocktrends/portfolios/{port_id}/strategy — strategy context for a specific portfolio

The return history endpoints provide evidence. The strategy endpoints provide the methodology context that explains what rules generated that history. Together they allow agents to evaluate portfolios without treating them as a black box.

Agent Evaluation Workflow

A practical workflow for agents and researchers evaluating the Stock Trends framework:

1. Discover tools — GET /v1/ai/tools and /llms.txt provide machine-readable workflow guidance and endpoint metadata
2. Understand assumptions — GET /v1/meta/stim exposes ST-IM base-period means and modeling assumptions
3. Review ST-IM outcome evidence — GET /v1/selections/stim-select/outcomes/summary returns mature realized outcome data across 4-week, 13-week, and 40-week horizons
4. Inspect strategy definitions — GET /v1/stocktrends/strategies and GET /v1/stocktrends/strategies/{strategy_id} expose the rules behind each portfolio strategy
5. Evaluate a portfolio — GET /v1/stocktrends/portfolios/{port_id}/returns provides return history for any live Stock Trends portfolio
6. Generate research output — combine outcome evidence, strategy context, and regime/breadth data into advisory-safe research summaries using framework evaluation language rather than investment advice

Relevant resources:

• /v1/openapi.json — full OpenAPI spec
• /llms.txt — machine-readable agent discovery
• GET /v1/ai/context — indicator and dataset grounding
• GET /v1/ai/tools — primary agent workflow discovery
• GET /v1/meta/stim — ST-IM assumptions and base-period data
• GET /v1/selections/stim-select/outcomes/summary — mature realized outcome data
• GET /v1/stocktrends/strategies — strategy framework definitions
• GET /v1/stocktrends/portfolios/{port_id}/returns — portfolio return history