Signals API

Generate and retrieve AI-powered trading signals using multi-agent analysis

Last Updated

16 Oct 2025 - Current Implementation

Overview

The Signals API provides endpoints for generating and retrieving trading signals based on the MarketSense AI multi-agent framework. Each signal includes:

Signal Type: BUY, HOLD, or SELL recommendation
Conviction Score: 0-100 score indicating signal strength
Confidence Level: 0-100 score indicating confidence in the analysis
Reasoning: Chain-of-Thought explanation from the signal generation agent
Agent Outputs: Detailed analysis from each specialized agent

Project ID Format

Understanding Project IDs

The project_id parameter uses the format: ticker:timestamp

New Format: AAPL.US:20251016_143022 (ticker:snapshot_id)
Legacy Format: aapl.us_20251016_143022 (ticker_snapshot_id) - still supported
Components: Ticker symbol + colon + snapshot ID (YYYYMMDD_HHMMSS)
Purpose: Links signals to specific stock data snapshots for reproducibility

Core Endpoints

GET /api/signals/snapshot/{ticker}/{snapshot_id}

Get the latest signal for a specific snapshot (from file storage, not database).

Path Parameters

ticker string required

Stock ticker symbol (e.g., "AAPL.US")
snapshot_id string required

Snapshot ID (format: YYYYMMDD_HHMMSS)

Example Request

curl "http://localhost:8004/api/signals/snapshot/AAPL.US/20251016_143022"

Response (200 OK)

{
  "ticker": "AAPL.US",
  "signal": "BUY",
  "conviction_score": 72.5,
  "confidence": 85.0,
  "reasoning": "Based on comprehensive analysis...",
  "weighted_score": 68.2,
  "price_at_signal": 185.45,
  "generated_at": "2025-10-16T14:30:00Z",
  "llm_provider": "openai",
  "agent_outputs": {
    "fundamentals": {
      "score": 75.0,
      "confidence": 90.0,
      "summary": "Strong fundamentals..."
    },
    "news": {
      "score": 68.0,
      "confidence": 80.0,
      "summary": "Positive sentiment..."
    },
    "price_dynamics": {
      "score": 70.0,
      "confidence": 85.0,
      "summary": "Upward momentum..."
    },
    "macro": {
      "score": 65.0,
      "confidence": 50.0,
      "summary": "Neutral macro environment..."
    }
  }
}

Error Responses

Status Code	Description
404	No signal found for this snapshot
500	Error loading signal

POST /api/signals/generate/{project_id}

Generate a new trading signal for a stock using multi-agent AI analysis.

Path Parameters

project_id string required

Stock project ID in format ticker:timestamp (e.g., "AAPL.US:20251016_143022")

Query Parameters

llm_provider string optional

LLM provider to use: "openai" (default), "anthropic", or "ollama"
save_to_db boolean optional

Save signal to database (default: true)

Example Request (cURL)

curl -X POST \
  "http://localhost:8004/api/signals/generate/AAPL.US:20251016_143022?llm_provider=openai&save_to_db=true"

Example Request (Python)

import requests

response = requests.post(
    "http://localhost:8004/api/signals/generate/AAPL.US:20251016_143022",
    params={
        "llm_provider": "openai",
        "save_to_db": True
    }
)

signal = response.json()
print(f"Signal: {signal['signal']}, Conviction: {signal['conviction_score']}")

Response (200 OK)

{
  "ticker": "AAPL.US",
  "signal": "BUY",
  "conviction_score": 72.5,
  "confidence": 85.0,
  "reasoning": "Based on comprehensive analysis across fundamentals, news sentiment, technical indicators, and macroeconomic factors, AAPL demonstrates strong buy signals. The company shows healthy revenue growth, solid profit margins, and robust balance sheet. Recent news sentiment is overwhelmingly positive with key narratives around new product launches. Technical indicators suggest upward momentum with price above key moving averages. The macroeconomic environment is neutral to slightly positive.",
  "weighted_score": 68.2,
  "price_at_signal": 185.45,
  "generated_at": "2025-10-16T14:30:00Z",
  "llm_provider": "openai",
  "agent_outputs": {
    "fundamentals": {
      "score": 75.0,
      "confidence": 90.0,
      "summary": "Strong fundamentals with healthy revenue growth (15% YoY), solid profit margins (25%), and robust balance sheet. PE ratio of 28.5 is reasonable for the growth profile. ROE of 45% indicates excellent capital efficiency.",
      "metadata": {
        "revenue_growth": 0.15,
        "profit_margin": 0.25,
        "pe_ratio": 28.5,
        "roe": 0.45
      }
    },
    "news": {
      "score": 68.0,
      "confidence": 80.0,
      "summary": "Positive sentiment over the past 60 days. Key narratives include new product launches (iPhone 16 series), market share gains in China, and partnership announcements. Sentiment analysis shows 65% positive, 25% neutral, 10% negative.",
      "metadata": {
        "sentiment_positive": 0.65,
        "sentiment_neutral": 0.25,
        "sentiment_negative": 0.10,
        "article_count": 50
      }
    },
    "price_dynamics": {
      "score": 70.0,
      "confidence": 85.0,
      "summary": "Upward momentum with price above 20, 50, and 200-day SMAs. RSI at 62 suggests strength without overbought conditions. Volume increasing on up days. Bollinger Bands show expanding volatility with price at upper band.",
      "metadata": {
        "rsi": 62,
        "sma_20": 182.0,
        "sma_50": 178.5,
        "sma_200": 170.2,
        "current_price": 185.45
      }
    },
    "macro": {
      "score": 65.0,
      "confidence": 50.0,
      "summary": "Neutral to slightly positive macroeconomic environment. Fed interest rate stability supports equity valuations. Tech sector showing resilience. Consumer spending remains strong. Some concerns around potential economic slowdown in 2026.",
      "metadata": {
        "interest_rate_stable": true,
        "sector_performance": "positive",
        "economic_outlook": "neutral"
      }
    }
  }
}

Processing Flow

This endpoint performs the following steps:

Parses project_id to extract ticker and snapshot_id
Loads stock snapshot from file storage
Fetches macro sources via Tavily API (if configured)
Runs 4 specialized agents in parallel:
- Fundamentals Summarizer (30% weight)
- Progressive News Summarizer (25% weight)
- Stock-Price Dynamics Summarizer (25% weight)
- Macroeconomic Environment Summarizer (20% weight)
Signal Orchestrator aggregates scores and generates final signal
Saves signal to snapshot's analysis folder as JSON
Optionally saves to database (if save_to_db=true)

Typical execution time: 30-60 seconds depending on LLM provider

Error Responses

Status Code	Description
400	Invalid project_id format
404	Stock snapshot not found
500	Error generating signal (LLM provider error, etc.)

Database Endpoints

GET /api/signals/{signal_id}

Get detailed information for a specific signal (from database).

Path Parameters

signal_id integer required

Signal ID from database

Example Request

curl "http://localhost:8004/api/signals/123"

Response (200 OK)

{
  "id": 123,
  "ticker": "AAPL.US",
  "signal": "BUY",
  "conviction_score": 72.5,
  "confidence": 85.0,
  "reasoning": "Based on comprehensive analysis...",
  "weighted_score": 68.2,
  "price_at_signal": 185.45,
  "created_at": "2025-10-16T14:30:00Z",
  "agent_outputs": [
    {
      "agent_name": "fundamentals",
      "score": 75.0,
      "confidence": 90.0,
      "summary": "Strong fundamentals...",
      "metadata": {...},
      "created_at": "2025-10-16T14:29:55Z"
    },
    {
      "agent_name": "news",
      "score": 68.0,
      "confidence": 80.0,
      "summary": "Positive sentiment...",
      "metadata": {...},
      "created_at": "2025-10-16T14:29:56Z"
    },
    {
      "agent_name": "price_dynamics",
      "score": 70.0,
      "confidence": 85.0,
      "summary": "Upward momentum...",
      "metadata": {...},
      "created_at": "2025-10-16T14:29:57Z"
    },
    {
      "agent_name": "macro",
      "score": 65.0,
      "confidence": 50.0,
      "summary": "Neutral macro environment...",
      "metadata": {...},
      "created_at": "2025-10-16T14:29:58Z"
    }
  ]
}

GET /api/signals/history/{ticker}

Retrieve historical signals for a specific ticker.

Path Parameters

ticker string required

Stock ticker symbol

Query Parameters

limit integer optional

Number of signals to return (default: 10, max: 100)
days integer optional

Only signals from last N days

Example Request

curl "http://localhost:8004/api/signals/history/AAPL.US?limit=20&days=30"

Response (200 OK)

[
  {
    "id": 123,
    "ticker": "AAPL.US",
    "signal": "BUY",
    "conviction_score": 72.5,
    "confidence": 85.0,
    "reasoning": "Based on comprehensive analysis...",
    "weighted_score": 68.2,
    "price_at_signal": 185.45,
    "created_at": "2025-10-16T14:30:00Z",
    "agent_outputs": [...]
  },
  {
    "id": 122,
    "ticker": "AAPL.US",
    "signal": "HOLD",
    "conviction_score": 55.0,
    "confidence": 70.0,
    "reasoning": "Mixed signals...",
    "weighted_score": 52.3,
    "price_at_signal": 182.30,
    "created_at": "2025-10-15T09:15:00Z",
    "agent_outputs": [...]
  }
]

GET /api/signals/latest

Retrieve the most recent signals across all tickers.

Query Parameters

limit integer optional

Number of signals to return (default: 20, max: 100)
signal_type string optional

Filter by signal type: "BUY", "HOLD", or "SELL"
min_conviction float optional

Minimum conviction score (0-100)

Example Request

curl "http://localhost:8004/api/signals/latest?signal_type=BUY&min_conviction=70&limit=10"

Response (200 OK)

[
  {
    "id": 125,
    "ticker": "TSLA.US",
    "signal": "BUY",
    "conviction_score": 78.2,
    "confidence": 88.0,
    "reasoning": "Tesla shows exceptional momentum...",
    "weighted_score": 75.5,
    "price_at_signal": 245.80,
    "created_at": "2025-10-16T15:45:00Z"
  },
  {
    "id": 123,
    "ticker": "AAPL.US",
    "signal": "BUY",
    "conviction_score": 72.5,
    "confidence": 85.0,
    "reasoning": "Based on comprehensive analysis...",
    "weighted_score": 68.2,
    "price_at_signal": 185.45,
    "created_at": "2025-10-16T14:30:00Z"
  }
]

DELETE /api/signals/{signal_id}

Delete a signal and its agent outputs from the database.

Example Request

curl -X DELETE "http://localhost:8004/api/signals/123"

Response (200 OK)

{
  "message": "Signal 123 for AAPL.US deleted successfully"
}

Signal Scoring System

Signals are generated using a weighted scoring system based on outputs from four specialized agents:

Agent	Weight	Focus	Data Sources
Fundamentals Summarizer	30%	Financial health, valuation	Balance sheet, income statement, ratios
Progressive News Summarizer	25%	Sentiment, narratives	60-day rolling news with sentiment scores
Stock-Price Dynamics Summarizer	25%	Technical analysis, momentum	Price history, volume, technical indicators
Macroeconomic Environment Summarizer	20%	Sector trends, economic conditions	Tavily web search, sector analysis

Signal Classification Rules

How Signals Are Determined

BUY: Weighted score >= 60 and positive sentiment from majority of agents
SELL: Weighted score <= 40 and negative sentiment from majority of agents
HOLD: Weighted score between 40-60 or mixed agent sentiment
Conviction Score: Higher scores (70+) indicate stronger consensus among agents
Confidence Level: Reflects data quality and agent agreement (80+ is high confidence)

LLM Provider Configuration

The Signals API supports three LLM providers:

Provider	Value	API Key Required	Notes
OpenAI	`openai`	Yes (Settings)	Default, most accurate, GPT-4 based
Anthropic	`anthropic`	Yes (Settings)	Claude-based, good for long context
Ollama	`ollama`	No	Local LLM, free, requires local Ollama server

Important Notes

Signal generation requires valid stock snapshot data. Create a stock snapshot first using the Stocks API.
LLM provider API keys must be configured in Settings before use.
Tavily API key is optional but recommended for better macro environment analysis.
Signal generation takes 30-60 seconds. Consider implementing a queue for multiple requests.
Signals are saved to two locations: (1) Snapshot's analysis folder as JSON, (2) Database (if save_to_db=true)
Signals are for research purposes only and not financial advice.

Rate Limits

Signal generation involves multiple LLM API calls. Recommended rate limits:

OpenAI/Anthropic: 5 signals per minute (API cost considerations)
Ollama (local): No strict limit, but depends on hardware capabilities

Next Steps

Deep Dive: Market Intelligence System
Stocks API - Create stock snapshots for signal generation
Settings API - Configure LLM provider API keys
Agentic Frameworks - Learn about the 4 specialized agents
LLM Providers - Configure OpenAI, Anthropic, or Ollama