Stock Trends API documentation

The Stock Trends API provides decision, portfolio, pricing, and market intelligence endpoints designed for AI agents and financial applications.

Start with pricing discovery, then execute a symbol or portfolio workflow.

Recommended starting point: review pricing ? estimate cost ? execute a decision or portfolio request.

Pricing clarity: 1 STC = $1.00 USD for current billing and payment presentation. A 0.50 STC request costs $0.50 USD. The live pricing catalog and response headers are authoritative.

Quickstart

Three paths to your first successful call.

Path 1 — Explore the API reference

https://api.stocktrends.com/v1/docs
https://api.stocktrends.com/v1/openapi.json

The interactive docs and OpenAPI schema are publicly accessible. Use these to explore endpoints, parameters, and response shapes before writing any code. The live pricing catalog is at GET /v1/pricing/catalog.

Path 2 — Subscription access (API key)

curl https://api.stocktrends.com/v1/agent/screener/top \
  -H "X-API-Key: YOUR_API_KEY"

Returns top-ranked instruments using your subscription API key. Get a plan ?

Path 3 — Agent pay

# x402: permissionless per-request payment
        GET https://api.stocktrends.com/v1/agent/screener/top
        
        # MPP: funded session-based payment
        GET https://api.stocktrends.com/v1/agent/screener/top
        X-StockTrends-Payment-Method: mpp
        X-StockTrends-Payment-Network: base
        X-StockTrends-Payment-Reference: mpp-ref-12345
        X-StockTrends-Payment-Amount: 0.5
        X-StockTrends-Payment-Channel-Id: mppch_...

The API supports both x402 per-request payment and MPP funded session-based payment for agent workflows. Use x402 for permissionless pay-as-you-go access. Use MPP for repeated premium requests against a funded balance. x402 quickstart · MPP quickstart

Pricing clarity: STC and USD cost

Stock Trends Credits (STC) are the API's pricing unit. For current billing and payment presentation, 1 STC = $1.00 USD. This means a request priced at 0.50 STC costs $0.50 USD, a request priced at 0.75 STC costs $0.75 USD, and a request priced at 1.25 STC costs $1.25 USD.

x402 and MPP requests may be settled through machine-payment rails, including USDC on Base where supported, but the user-facing economic cost is still shown from the STC-denominated endpoint price. The live pricing catalog and response headers remain authoritative before execution.

Example requests

GET /v1/agent/screener/top — Top-ranked instruments (0.50 STC)

curl "https://api.stocktrends.com/v1/agent/screener/top" \
  -H "X-API-Key: YOUR_API_KEY"

# Optional filters: ?exchange=N&limit=10&sort=rsi&trend=^+,^-

GET /v1/stim/latest — Latest return distribution stats

curl "https://api.stocktrends.com/v1/stim/latest?symbol_exchange=IBM-N" \
  -H "X-API-Key: YOUR_API_KEY"

GET /v1/market/regime/latest — Current market regime (0.15 STC)

curl "https://api.stocktrends.com/v1/market/regime/latest" \
  -H "X-API-Key: YOUR_API_KEY"

POST /v1/portfolio/evaluate — Evaluate a portfolio (0.75 STC)

curl -X POST "https://api.stocktrends.com/v1/portfolio/evaluate" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "positions": [
      {"symbol_exchange": "AAPL-Q", "weight": 0.5},
      {"symbol_exchange": "IBM-N",  "weight": 0.5}
    ]
  }'

Use symbol_exchange format: SYMBOL-EXCHANGE (e.g. AAPL-Q, IBM-N, MSFT-Q). Weights must sum to 1.0 ±0.01. Maximum 25 positions.

POST /v1/portfolio/compare — Compare two portfolios (1.25 STC)

curl -X POST "https://api.stocktrends.com/v1/portfolio/compare" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "left": [
      {"symbol_exchange": "AAPL-Q", "weight": 0.6},
      {"symbol_exchange": "MSFT-Q", "weight": 0.4}
    ],
    "right": [
      {"symbol_exchange": "IBM-N",  "weight": 0.5},
      {"symbol_exchange": "NVDA-Q", "weight": 0.5}
    ]
  }'

Access modes

The API supports four access patterns. Choose based on your use case.

Agents can discover current endpoint pricing programmatically via GET /v1/pricing/catalog. The API response headers are authoritative for endpoint costs.

Authentication and payment headers

Subscription access

X-API-Key: YOUR_API_KEY

x402 payment proof — sent on the retry after a 402 response

X-StockTrends-Payment-Method: x402
X-StockTrends-Payment-Network: base
X-StockTrends-Payment-Token: USDC
X-StockTrends-Payment-Reference: 0x...your_tx_hash

MPP funded session payment

X-StockTrends-Payment-Method: mpp
X-StockTrends-Payment-Network: base
X-StockTrends-Payment-Reference: mpp-ref-12345
X-StockTrends-Payment-Amount: 0.5
X-StockTrends-Payment-Channel-Id: mppch_...

Optional: agent identity headers

X-StockTrends-Agent-Id: your-agent-id
X-StockTrends-Agent-Type: autonomous
X-StockTrends-Agent-Vendor: your-vendor
X-StockTrends-Request-Purpose: screening

Agent identity headers are optional but improve usage tracking and ledger visibility in GET /agents/{agent_id}/usage and /ledger.

Core endpoint families

• Decision: symbol evaluation
• Portfolio: construct, evaluate, compare
• Market intelligence: regime, breadth, leadership
• Pricing: pricing metadata and cost estimation
• Agents: usage tracking, ledger, lifecycle control
• Workflows: workflow registry

High-value endpoints

• POST /decision/evaluate-symbol
• POST /portfolio/construct
• POST /portfolio/evaluate
• POST /portfolio/compare
• GET /market/regime/latest
• GET /agent/screener/top
• GET /pricing
• GET /cost-estimate

Common errors

For AI agents and automated systems

The API is designed for agent-driven workflows with structured outputs, pricing awareness, and controlled execution.

Recommended agent discovery sequence:

1. GET /v1/ai/context — Understand dataset structure, terminology, and indicator logic
2. GET /v1/pricing/catalog — Discover live endpoint pricing rules
3. GET /v1/agent/screener/top — First premium endpoint; supports both API key and x402 payment
4. Execute decision or portfolio workflows with results from the screener

Agents without a subscription can use two payment rails. Use x402 for permissionless per-request payment: send the request, receive HTTP 402 with payment instructions, submit on-chain payment, and retry with proof headers. Use MPP for funded session-based payment: fund a session, keep the channel_id, and let your agent make repeated premium requests against that balance.

• Agent pay walkthrough: Agent Pay Quickstart
• MPP quickstart: Funded session-based agent pay
• OpenAPI schema: openapi.json
• Interactive docs: API explorer
• LLM descriptor: llms.txt

Base API