Documentation

Stock Trends API

The Stock Trends API is market context infrastructure. It exposes decades of consistently classified weekly market intelligence — instrument trend state and persistence, relative performance, market and sector breadth, leadership concentration and rotation, regime structure, ST-IM forward-return distributions, and portfolio context — so that trading systems, portfolio processes, and AI agents can understand the environment their own strategies are operating in.

It is designed to augment an existing investment process, not replace it. Your strategy supplies the thesis; Stock Trends supplies the surrounding context, classified the same way across market cycles so it stays comparable over time.

Second, it is an agent-native delivery and payment platform. The same context is available through machine-readable discovery, pricing and cost estimation, symbol resolution, and structured workflow metadata, over the REST API or the Stock Trends MCP server, with access through subscription API keys, standard x402 V2 per-request payment, and MPP funded sessions.

Open live API docs Open OpenAPI schema Connect with MCP x402 quickstart MPP quickstart

Recommended agent workflow: discover → price → resolve symbols → screen/select → evaluate → construct portfolio → add regime and leadership context → execute.

Pricing clarity: 1 STC = $1.00 USD for current billing and payment presentation. A 0.50 STC request costs $0.50 USD. GET /v1/pricing/catalog remains authoritative for per-endpoint pricing.

Start here

Choose how you want to connect

The first two rows are transports — how the intelligence reaches your code. The last three are payment rails — how premium usage is paid for. A rail is not a substitute for a transport: every paid request still travels over the REST API, whether you call it directly or through MCP.

Integration Type Best for Where to start
REST API Transport Applications, services, trading and portfolio systems, custom integrations Live API docs
MCP Transport MCP-compatible agents and interactive AI tooling Stock Trends MCP
Subscription Payment rail Managed, authenticated API usage with monthly quota Plans
x402 Payment rail Permissionless per-request machine payment, no account required x402 quickstart
MPP Payment rail Repeated funded agent workflows without per-request settlement MPP quickstart
First use

Start without an API key

You can understand the service, inspect its evidence, and price a workflow before you choose an access method. Every endpoint below is public under current API behaviour and costs nothing to call.

Step Endpoint What you get
1. Discover capabilities GET /v1/ai/tools Capability families, supported rails, recommended call sequence
2. Ground the semantics GET /v1/ai/context Indicator definitions, dataset context, interpretation rules
3. Choose a workflow GET /v1/workflows Task-level workflows and their endpoint sequences
4. Resolve symbols GET /v1/instruments/resolve
GET /v1/instruments/lookup 		Canonical symbol_exchange values before any paid symbol call
5. Inspect pricing GET /v1/pricing/catalog Live per-endpoint STC cost, access type, and supported rails
6. Estimate workflow cost GET /v1/cost-estimate Workflow-level cost for a chosen workflow_id and rail preference
7. Inspect the evidence GET /v1/ai/proof/market-edge
GET /v1/meta/stim 		Signal structure and ST-IM base-period assumptions
8. Read the contract GET /v1/openapi.json Exact request and response schemas

Only after that do you need to choose an access method — subscription, standard x402 V2, or MPP — for premium execution. The objective is that an agent can understand the service and estimate the cost before it spends anything.

Research provenance

Long-horizon signal history for agent discovery

Agent discovery should treat the Stock Trends signal layer as long-horizon market intelligence, not a thin quote wrapper. The framework includes historical classification records extending back to 1980, 16M+ structured observations, and consistent signal semantics across trend, relative performance, volume activity, breadth, leadership, and regime structure.

Use this depth as research provenance for probabilistic interpretation, regime analysis, portfolio construction research, and agentic workflows - not as investment advice, price targets, direct buy/sell commands, or guaranteed future performance.

Primary discovery endpoints

Recommended first call for AI agents:

GET /v1/ai/tools

Returns machine-readable discovery metadata for workflows, pricing behavior, endpoint families, examples, and agent integration guidance.

Endpoint Purpose
GET /v1/ai/tools Primary agent discovery and workflow metadata
GET /v1/ai/context Indicator definitions and dataset grounding
GET /v1/workflows Task-level workflow registry and endpoint sequences
GET /v1/pricing/catalog Live endpoint pricing rules
GET /v1/pricing Payment rails, agent identity headers, and rail guidance
GET /v1/cost-estimate Workflow cost estimation
GET /v1/openapi.json Canonical OpenAPI schema
Capability families

What each family tells you, and when to call it

Endpoints are grouped below by the question they answer rather than by route shape. The OpenAPI schema remains authoritative for exact parameters, request bodies, and response fields — this page is for deciding which family you need and where it sits in a workflow.

Access cues below describe rails supported at the API. Endpoint pricing is dynamic: call GET /v1/pricing/catalog before execution rather than hard-coding costs.

Instrument

Instrument context

What it tells you
How a single instrument is currently classified: trend state, trend persistence, Stock Trends RSI (relative performance versus a benchmark with baseline 100, not Wilder RSI), relative-performance direction, and volume behaviour.

Why use it
To place a symbol your own strategy has surfaced into the Stock Trends classification frame, and to see how long it has been in that state.

Workflow position
resolve symbol → read instrument context → evaluate → portfolio

GET /v1/indicators/latest

GET /v1/indicators/history

Access: Subscription · x402 · MPP

ST-IM

ST-IM forward-return distributions

What it tells you
Probabilistic forward-return distribution statistics for an instrument at 4, 13, and 40 weeks, conditioned on how it is currently classified. ST-IM is probabilistic inference, not a momentum indicator.

Why use it
To attach a distribution — not a point forecast — to a candidate, and to compare candidates on the same probabilistic footing.

Workflow position
resolve symbol → instrument context → ST-IM → decision or portfolio

GET /v1/stim/latest

GET /v1/stim/history

GET /v1/meta/stim — base-period means, public

Access: Subscription · x402 · MPP
/v1/meta/stim is public

Select

STIM Select

What it tells you
Instruments meeting Stock Trends probability and confidence criteria across forward return periods. The published list applies published thresholds; the base selection universe does not.

Why use it
To start from a Stock Trends-generated candidate set instead of screening the whole universe yourself.

Workflow position
screen/select → inspect regime → evaluate candidates → construct portfolio

GET /v1/selections/published/latest

GET /v1/selections/latest — base universe

GET /v1/selections/history

Access: Subscription · x402 · MPP

Decision

Symbol evaluation

What it tells you
A structured, regime-aware evaluation of a single symbol that combines instrument classification with surrounding market context.

Why use it
To get one composed evaluation instead of assembling instrument, ST-IM, and regime context yourself. It is research context, not a buy/sell instruction.

Workflow position
resolve symbol → inspect regime → evaluate symbol → portfolio

POST /v1/decision/evaluate-symbol

Access: Subscription · x402 · MPP

Market

Market regime

What it tells you
The broader participation environment surrounding individual signals and portfolios: bullish, bearish, transitional, or selective, with confidence and regime score.

Why use it
Read regime context before screening, symbol evaluation, or portfolio construction, to understand whether the surrounding market is broadly supportive, selective, transitional, or bearish.

Workflow position
resolve/screen → inspect regime → evaluate candidates → construct/evaluate portfolio

GET /v1/market/regime/latest

GET /v1/market/regime/history

GET /v1/market/regime/forecast

Access: Subscription · x402 · MPP

Breadth

Sector breadth

What it tells you
How widely participation is distributed across sectors and industry groups: bullish and bearish counts and percentages, average Stock Trends RSI, and net breadth.

Why use it
To test whether a move your strategy detected is broadly supported or narrowly concentrated. Breadth is participation context, not a confirmation signal to act on.

Workflow position
inspect regime → inspect breadth → evaluate candidates

GET /v1/breadth/sector/latest

GET /v1/breadth/sector/history

Access: Subscription · x402 · MPP

Leadership

Leadership and rotation

What it tells you
Which names, sectors, and industry groups are leading, and how leadership has been rotating between groups over time.

Why use it
To see where relative strength is concentrated and whether it is moving, before committing to a sector or theme. Leadership tables are rotation context, not picks.

Workflow position
inspect regime → inspect breadth → inspect leadership → construct portfolio

GET /v1/leadership/summary/latest

GET /v1/leadership/rotation/history

GET /v1/leadership/definitions — taxonomy, public

Access: Subscription · x402 · MPP
/v1/leadership/definitions is public

Portfolio

Portfolio workflows

What it tells you
How a supplied portfolio scores against Stock Trends context, how two portfolios compare under the same evaluation logic, and how a scored portfolio can be constructed from candidates.

Why use it
To move from individual signals to a portfolio-level view aligned with current market conditions.

Workflow position
screen → evaluate candidates → construct → evaluate → compare

POST /v1/portfolio/construct

POST /v1/portfolio/evaluate

POST /v1/portfolio/compare

Access: Subscription · x402 · MPP

Evidence

Strategy and model-portfolio evidence

What it tells you
Declared strategy rules, model-portfolio return histories, closed-position history, and portfolio-to-strategy provenance. Rule-based model records with declared transaction-cost and stop-loss assumptions — not audited brokerage performance.

Why use it
To inspect the record and the rules behind it directly, rather than accepting a performance claim. Strategy conditions are metadata, not executable endpoints.

Workflow position
evaluate the framework → then decide whether to integrate it

GET /v1/stocktrends/portfolios

GET /v1/stocktrends/strategies

GET /v1/selections/stim-select/outcomes/summary

Access: public under current API behaviour
Full evidence documentation

Planning

Workflow and cost discovery

What it tells you
Which task-level workflows exist, which endpoints each one sequences, what every endpoint currently costs, and what a whole workflow would cost on a chosen rail.

Why use it
So an autonomous caller can budget before it spends, and so costs are never hard-coded against a catalog that changes.

Workflow position
discover → choose workflow → price → estimate → execute

GET /v1/workflows

GET /v1/pricing/catalog

GET /v1/cost-estimate

Access: public under current API behaviour

Supporting endpoint families

Family Representative endpoints Purpose
Symbol resolution GET /v1/instruments/resolve
GET /v1/instruments/lookup 		Produce a canonical symbol_exchange before any paid symbol call
Methodology metadata GET /v1/meta/indicators
GET /v1/meta/inference
GET /v1/meta/stim
GET /v1/meta/stwr 		Ground field semantics and modelling assumptions before interpreting results
Agent metering GET /v1/agents
GET /v1/agents/{agent_id}/usage
GET /v1/agents/{agent_id}/ledger 		Attributed usage and economics visibility for identified agents

Authentication and payment

Subscription access

Send your API key on every request. The OpenAPI schema declares an API-key scheme in the X-API-Key header, with bearer authentication as an alternative. 

X-API-Key: YOUR_API_KEY

x402 per-request payment

The Stock Trends API supports standard x402 V2 interoperability. A conforming x402 V2 buyer needs no Stock Trends-specific payment integration: call the endpoint, receive the standard PAYMENT-REQUIRED challenge, let your x402 client sign and retry with PAYMENT-SIGNATURE, and read the settlement result from PAYMENT-RESPONSE. 

request premium endpoint
      ↓
402 + PAYMENT-REQUIRED challenge
      ↓
standard x402 client signs the payment authorization
      ↓
retry with PAYMENT-SIGNATURE
      ↓
200 + PAYMENT-RESPONSE

Settlement is USDC on Base (eip155:8453). The x402 quickstart has working TypeScript, Python, and cURL examples.

MPP funded session payment

MPP consumes STC from an active funded session and does not use the x402 challenge flow. See the MPP quickstart for the session workflow, and consult the applicable API documentation for the current declared payment-header set before building an integration.

Use subscription for managed production workloads, standard x402 V2 for permissionless per-request execution, and MPP for repeated funded agent workflows. All three carry the same intelligence over the same API.

Recommended first premium endpoint

GET /v1/agent/screener/top

Returns top-ranked instruments filtered by trend, RSI, exchange, and ST-IM intelligence.

Access: Subscription · x402 · MPP. Call GET /v1/pricing/catalog for the current cost of this endpoint before executing it — the catalog is authoritative and costs should not be hard-coded.

Machine-readable resources

Base API URL

https://api.stocktrends.com/v1