feat: integrate quantitative, calendar, market data endpoints

Add 3 new service layers and route modules: - quantitative_service: Sharpe ratio, CAPM, normality tests, unit root tests - calendar_service: earnings/dividends/IPO/splits calendars, estimates, SEC ownership - market_service: ETF, index, crypto, forex, options, futures data Total endpoints: 50. All use free providers (yfinance, SEC). Update README with comprehensive endpoint documentation.
2026-03-09 10:28:33 +01:00
parent 00f2cb5e74
commit 507194397e
8 changed files with 980 additions and 18 deletions
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # OpenBB Investment Analysis API

-REST API wrapping OpenBB SDK, providing stock data query, sentiment analysis, technical indicators, macro data, and rule-based investment analysis for US and Swedish markets. Designed to be called by OpenClaw (or any AI assistant) — the API returns structured data, all LLM reasoning happens on the caller side.
+REST API wrapping OpenBB SDK, providing stock data, sentiment analysis, technical indicators, quantitative risk metrics, macro data, market data (ETF/index/crypto/forex/options), and rule-based investment analysis for US and Swedish markets. Designed to be called by OpenClaw (or any AI assistant) -- the API returns structured data, all LLM reasoning happens on the caller side.

 ## API Keys

@@ -42,6 +42,7 @@ export INVEST_API_ALPHAVANTAGE_API_KEY=your_alphavantage_key
 ```bash
 conda env create -f environment.yml
 conda activate openbb-invest-api
+pip install openbb-quantitative openbb-econometrics
 ```

 ### 2. Start the server
@@ -64,15 +65,28 @@ curl http://localhost:8000/api/v1/stock/AAPL/quote
 # Swedish stock quote
 curl http://localhost:8000/api/v1/stock/VOLV-B.ST/quote

-# Sentiment analysis (requires Finnhub + Alpha Vantage keys)
+# Sentiment analysis (Finnhub + Alpha Vantage)
 curl http://localhost:8000/api/v1/stock/AAPL/sentiment

-# News sentiment with per-article scores (requires Alpha Vantage key)
+# News sentiment with per-article scores (Alpha Vantage)
 curl http://localhost:8000/api/v1/stock/AAPL/news-sentiment

 # Technical indicators
 curl http://localhost:8000/api/v1/stock/AAPL/technical

+# Quantitative risk metrics
+curl http://localhost:8000/api/v1/stock/AAPL/performance
+curl http://localhost:8000/api/v1/stock/AAPL/capm
+
+# SEC insider trading
+curl http://localhost:8000/api/v1/stock/AAPL/sec-insider
+
+# ETF info
+curl http://localhost:8000/api/v1/etf/SPY/info
+
+# Crypto price history
+curl http://localhost:8000/api/v1/crypto/BTC-USD/historical?days=30
+
 # Macro overview (requires FRED key)
 curl http://localhost:8000/api/v1/macro/overview

@@ -108,7 +122,7 @@ curl -X POST http://localhost:8000/api/v1/portfolio/analyze \
 |--------|------|-------------|
 | GET | `/api/v1/stock/{symbol}/sentiment` | Aggregated: news sentiment + recommendations + upgrades |
 | GET | `/api/v1/stock/{symbol}/news-sentiment?limit=30` | News articles with per-ticker sentiment scores (Alpha Vantage) |
-| GET | `/api/v1/stock/{symbol}/insider-trades` | Insider transactions (CEO/CFO buys and sells) |
+| GET | `/api/v1/stock/{symbol}/insider-trades` | Insider transactions via Finnhub |
 | GET | `/api/v1/stock/{symbol}/recommendations` | Monthly analyst buy/hold/sell counts |
 | GET | `/api/v1/stock/{symbol}/upgrades` | Recent analyst upgrades and downgrades |

@@ -118,6 +132,70 @@ curl -X POST http://localhost:8000/api/v1/portfolio/analyze \
 |--------|------|-------------|
 | GET | `/api/v1/stock/{symbol}/technical` | RSI, MACD, SMA, EMA, Bollinger Bands + signal interpretation |

+### Quantitative Analysis (openbb-quantitative, no key needed)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/v1/stock/{symbol}/performance?days=365` | Sharpe ratio, summary statistics, volatility |
+| GET | `/api/v1/stock/{symbol}/capm` | CAPM: market risk, systematic risk, idiosyncratic risk |
+| GET | `/api/v1/stock/{symbol}/normality?days=365` | Normality tests: Jarque-Bera, Shapiro-Wilk, Kolmogorov-Smirnov |
+| GET | `/api/v1/stock/{symbol}/unitroot?days=365` | Unit root tests: ADF, KPSS for stationarity |
+
+### Calendar Events (no key needed)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/v1/calendar/earnings?start_date=&end_date=` | Upcoming earnings announcements |
+| GET | `/api/v1/calendar/dividends?start_date=&end_date=` | Upcoming dividend dates |
+| GET | `/api/v1/calendar/ipo?start_date=&end_date=` | Upcoming IPOs |
+| GET | `/api/v1/calendar/splits?start_date=&end_date=` | Upcoming stock splits |
+
+### Estimates & Ownership (yfinance + SEC, no key needed)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/v1/stock/{symbol}/estimates` | Analyst consensus estimates |
+| GET | `/api/v1/stock/{symbol}/share-statistics` | Float, shares outstanding, short interest |
+| GET | `/api/v1/stock/{symbol}/sec-insider` | Insider trading from SEC (Form 4) |
+| GET | `/api/v1/stock/{symbol}/institutional` | Institutional holders from SEC 13F filings |
+| GET | `/api/v1/screener` | Stock screener |
+
+### ETF Data (yfinance, no key needed)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/v1/etf/{symbol}/info` | ETF profile, issuer, holdings |
+| GET | `/api/v1/etf/{symbol}/historical?days=365` | ETF price history |
+| GET | `/api/v1/etf/search?query=` | Search ETFs by name |
+
+### Index Data (yfinance, no key needed)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/v1/index/available` | List available indices |
+| GET | `/api/v1/index/{symbol}/historical?days=365` | Index price history (^GSPC, ^DJI, ^IXIC) |
+
+### Crypto Data (yfinance, no key needed)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/v1/crypto/{symbol}/historical?days=365` | Crypto price history (BTC-USD, ETH-USD) |
+| GET | `/api/v1/crypto/search?query=` | Search cryptocurrencies |
+
+### Currency / Forex (yfinance, no key needed)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/v1/currency/{symbol}/historical?days=365` | Forex price history (EURUSD, USDSEK) |
+
+### Derivatives (yfinance, no key needed)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/v1/options/{symbol}/chains` | Options chain data |
+| GET | `/api/v1/futures/{symbol}/historical?days=365` | Futures price history |
+| GET | `/api/v1/futures/{symbol}/curve` | Futures term structure/curve |
+
 ### Macro Economics (FRED, free key)

 | Method | Path | Description |
@@ -192,26 +270,22 @@ openbb-invest-api/
 ├── openbb_service.py       # OpenBB SDK wrapper (async)
 ├── finnhub_service.py      # Finnhub REST client (insider, analyst data)
 ├── alphavantage_service.py # Alpha Vantage REST client (news sentiment)
+├── quantitative_service.py # Risk metrics, CAPM, normality tests
+├── calendar_service.py     # Calendar events, screening, ownership
+├── market_service.py       # ETF, index, crypto, currency, derivatives
 ├── macro_service.py        # FRED macro data via OpenBB
 ├── technical_service.py    # Technical indicators via openbb-technical
 ├── analysis_service.py     # Rule engine for portfolio analysis
 ├── routes.py               # Core stock data + portfolio + discovery routes
 ├── routes_sentiment.py     # Sentiment & analyst routes (Finnhub + Alpha Vantage)
+├── routes_quantitative.py  # Quantitative analysis routes
+├── routes_calendar.py      # Calendar, estimates, ownership routes
+├── routes_market.py        # ETF, index, crypto, currency, derivatives routes
 ├── routes_macro.py         # Macro economics routes (FRED)
 ├── routes_technical.py     # Technical analysis routes
 ├── environment.yml         # Conda environment
 ├── pyproject.toml          # Project metadata
 └── tests/                  # 102 tests
-    ├── test_models.py
-    ├── test_mappers.py
-    ├── test_openbb_service.py
-    ├── test_finnhub_service.py
-    ├── test_analysis_service.py
-    ├── test_routes.py
-    ├── test_routes_sentiment.py
-    ├── test_alphavantage_service.py
-    ├── test_routes_macro.py
-    └── test_routes_technical.py
 ```

 ## Running Tests
@@ -239,16 +313,20 @@ Example OpenClaw workflow:
 2. OpenClaw calls `GET /api/v1/stock/AAPL/summary` for fundamental data
 3. OpenClaw calls `GET /api/v1/stock/AAPL/sentiment` for news/analyst sentiment
 4. OpenClaw calls `GET /api/v1/stock/AAPL/technical` for technical signals
-5. OpenClaw calls `GET /api/v1/macro/overview` for market context
-6. OpenClaw calls `POST /api/v1/portfolio/analyze` with user's holdings
-7. OpenClaw's LLM synthesizes all structured data into a personalized recommendation
+5. OpenClaw calls `GET /api/v1/stock/AAPL/performance` for risk metrics (Sharpe, volatility)
+6. OpenClaw calls `GET /api/v1/stock/AAPL/sec-insider` for insider trading activity
+7. OpenClaw calls `GET /api/v1/macro/overview` for market context
+8. OpenClaw calls `POST /api/v1/portfolio/analyze` with user's holdings
+9. OpenClaw's LLM synthesizes all structured data into a personalized recommendation

 ## Data Sources

 | Source | Cost | Key Required | Data Provided |
 |--------|------|-------------|---------------|
-| **yfinance** | Free | No | Quotes, fundamentals, financials, historical prices, news, discovery |
+| **yfinance** | Free | No | Quotes, fundamentals, financials, historical prices, news, discovery, ETF, index, crypto, forex, options, futures |
+| **SEC** | Free | No | Insider trading (Form 4), institutional holdings (13F), company filings |
 | **Finnhub** | Free | Yes (free registration) | Insider trades, analyst recommendations, upgrades/downgrades |
 | **Alpha Vantage** | Free | Yes (free registration) | News sentiment scores (bullish/bearish per ticker per article), 25 req/day |
 | **FRED** | Free | Yes (free registration) | Fed rate, treasury yields, CPI, unemployment, GDP, VIX, 800K+ economic series |
 | **openbb-technical** | Free | No (local computation) | RSI, MACD, SMA, EMA, Bollinger Bands |
+| **openbb-quantitative** | Free | No (local computation) | Sharpe ratio, CAPM, normality tests, unit root tests, summary statistics |