TradingAgents/api

Trading Agents REST API

FastAPI-based REST API for managing multi-agent trading analyses with real-time WebSocket support.

Features

• REST API for creating, monitoring, and managing trading analyses
• WebSocket support for real-time status updates
• Parallel execution of multiple analyses (configurable concurrency)
• SQLite database for persistent storage
• API key authentication for secure access
• Complete analysis history with logs and reports

Installation

1. Install API dependencies:

cd TradingAgents
pip install -r requirements-api.txt

2. Initialize the database and create an API key:

python -m api.cli_admin init-database
python -m api.cli_admin create-key "My First Key"

Save the generated API key - you'll need it for all API requests.

Running the API

Start the API server:

python -m api.main

Or with uvicorn directly:

uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload

The API will be available at http://localhost:8000

API Documentation

Once the server is running, visit:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Quick Start

1. Create an Analysis

curl -X POST "http://localhost:8000/api/v1/analyses" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ticker": "AAPL",
    "analysis_date": "2025-10-21",
    "selected_analysts": ["market", "news", "social", "fundamentals"],
    "research_depth": 1
  }'

Response:

{
  "id": "uuid-here",
  "ticker": "AAPL",
  "analysis_date": "2025-10-21",
  "status": "pending",
  "progress_percentage": 0,
  ...
}

2. Monitor via WebSocket

const ws = new WebSocket('ws://localhost:8000/api/v1/ws/analyses/{analysis_id}');

ws.onmessage = (event) => {
  const update = JSON.parse(event.data);
  console.log(`Status: ${update.status}, Progress: ${update.progress_percentage}%`);
};

3. Get Analysis Results

curl "http://localhost:8000/api/v1/analyses/{analysis_id}" \
  -H "X-API-Key: YOUR_API_KEY"

API Endpoints

Analyses

• POST /api/v1/analyses - Create and start new analysis
• GET /api/v1/analyses - List all analyses (with filtering)
• GET /api/v1/analyses/{id} - Get full analysis details
• GET /api/v1/analyses/{id}/status - Get current status
• GET /api/v1/analyses/{id}/reports - Get all reports
• GET /api/v1/analyses/{id}/reports/{type} - Get specific report
• GET /api/v1/analyses/{id}/logs - Get execution logs
• DELETE /api/v1/analyses/{id} - Cancel/delete analysis

Tickers

• GET /api/v1/tickers - List all tickers with analysis counts
• GET /api/v1/tickers/{ticker}/analyses - Get all analyses for ticker
• GET /api/v1/tickers/{ticker}/latest - Get latest analysis for ticker

Data

• GET /api/v1/data/cache - List cached ticker data
• GET /api/v1/data/cache/{ticker} - Get cached market data

WebSocket

• WS /api/v1/ws/analyses/{id} - Real-time status updates

API Key Management

Create API Key

python -m api.cli_admin create-key "Description"

List API Keys

python -m api.cli_admin list-keys

Revoke API Key

python -m api.cli_admin revoke-key <key_id>

Activate API Key

python -m api.cli_admin activate-key <key_id>

Configuration

Environment Variables

• API_DATABASE_URL - Database connection string (default: sqlite:///./api_database.db)
• MAX_CONCURRENT_ANALYSES - Maximum parallel analyses (default: 4)
• Standard TradingAgents config (LLM providers, API keys, etc.)

Architecture

api/
├── main.py              # FastAPI application
├── database.py          # SQLAlchemy models
├── auth.py              # API key authentication
├── state_manager.py     # Analysis execution manager
├── models/              # Pydantic request/response models
├── endpoints/           # REST endpoint handlers
└── websockets/          # WebSocket handlers

Database Schema

• analyses - Analysis metadata and status
• analysis_logs - Execution logs (tool calls, reasoning)
• analysis_reports - Generated reports (by type)
• api_keys - Authentication keys

Parallel Execution

The API uses a ThreadPoolExecutor to run multiple analyses concurrently:

• Default: 4 concurrent analyses
• Configurable via MAX_CONCURRENT_ANALYSES env var
• Each analysis runs in its own thread
• Database writes are thread-safe
• Cached data is read-only (thread-safe)

Example Frontend Integration

class TradingAnalysisClient {
  constructor(apiKey, baseURL = 'http://localhost:8000') {
    this.apiKey = apiKey;
    this.baseURL = baseURL;
  }

  async createAnalysis(ticker, date, analysts = ['market', 'news']) {
    const response = await fetch(`${this.baseURL}/api/v1/analyses`, {
      method: 'POST',
      headers: {
        'X-API-Key': this.apiKey,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        ticker,
        analysis_date: date,
        selected_analysts: analysts,
        research_depth: 1,
      }),
    });
    return await response.json();
  }

  connectWebSocket(analysisId, onUpdate) {
    const ws = new WebSocket(`ws://localhost:8000/api/v1/ws/analyses/${analysisId}`);
    ws.onmessage = (event) => onUpdate(JSON.parse(event.data));
    return ws;
  }

  async getAnalysis(analysisId) {
    const response = await fetch(
      `${this.baseURL}/api/v1/analyses/${analysisId}`,
      { headers: { 'X-API-Key': this.apiKey } }
    );
    return await response.json();
  }
}

Troubleshooting

Database locked error

SQLite has limited concurrent write support. If you get database locked errors:

• Reduce MAX_CONCURRENT_ANALYSES
• Or switch to PostgreSQL by changing API_DATABASE_URL

Import errors

Make sure you're running from the TradingAgents root directory:

cd TradingAgents
python -m api.main

WebSocket connection refused

Check that the server is running and CORS is properly configured for your frontend origin.

Production Deployment

For production use:

1. Use PostgreSQL instead of SQLite
2. Secure CORS - Set specific allowed origins in main.py
3. HTTPS/WSS - Use reverse proxy (nginx) with SSL
4. Monitoring - Add logging, metrics, and health checks
5. Rate limiting - Add rate limiting middleware
6. Backup - Regular database backups

License

Same as TradingAgents/Litadel main project.