kai/openbb-invest-api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: comprehensive README update for 99 endpoints

Browse Source 
- Update endpoint count from 32 to 99
- Add all new endpoint sections: technical (14), quantitative extended,
  shorts/dark pool, fixed income, macro expanded, economy, surveys,
  regulators, equity fundamentals
- Add free providers table (stockgrid, FINRA, CFTC, multpl, ECB, OECD)
- Update data sources table with all 14 providers
- Update project structure with all new service/route files
- Update OpenClaw integration workflow with new endpoints
- Update quick start examples with new features
This commit is contained in:
Yaojia Wang
2026-03-19 19:59:44 +01:00
parent a57a6835c5
commit c5c9c7db83
1 changed files with 198 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files

277
README.md
View File

@@ -1,6 +1,6 @@
# OpenBB Investment Analysis API # OpenBB Investment Analysis API
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. REST API wrapping OpenBB SDK with 99 endpoints covering stock data, sentiment analysis, technical indicators, quantitative risk metrics, fixed income, macro economics, shorts/dark pool, regulators, and rule-based investment analysis. 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 ## API Keys
@@ -13,16 +13,23 @@ The core functionality uses **yfinance** (free, no API key). The API works witho
| Provider | Env Variable | How to Get | What It Unlocks | Free Limit | | Provider | Env Variable | How to Get | What It Unlocks | Free Limit |
|----------|-------------|------------|-----------------|------------| |----------|-------------|------------|-----------------|------------|
| **Finnhub** | `INVEST_API_FINNHUB_API_KEY` | https://finnhub.io/register | Insider trades, recommendation trends, company news | 60 calls/min | | **Finnhub** | `INVEST_API_FINNHUB_API_KEY` | https://finnhub.io/register | Insider trades, recommendation trends, company news | 60 calls/min |
| **FRED** | `INVEST_API_FRED_API_KEY` | https://fred.stlouisfed.org/docs/api/api_key.html | Macro data: Fed rate, CPI, GDP, unemployment, treasury yields | 120 calls/min | | **FRED** | `INVEST_API_FRED_API_KEY` | https://fred.stlouisfed.org/docs/api/api_key.html | Macro data, fixed income, surveys, money supply | 120 calls/min |
| **Alpha Vantage** | `INVEST_API_ALPHAVANTAGE_API_KEY` | https://www.alphavantage.co/support/#api-key | News sentiment scores (bullish/bearish per article per ticker) | 25 calls/day | | **Alpha Vantage** | `INVEST_API_ALPHAVANTAGE_API_KEY` | https://www.alphavantage.co/support/#api-key | News sentiment scores (bullish/bearish per article per ticker) | 25 calls/day |
### Optional Paid Keys (for higher quality data) ### Free Providers (no key needed)
| Provider | Env Variable | What It Adds | | Provider | Data Provided |
|----------|-------------|--------------| |----------|---------------|
| **Intrinio** | `OBB_INTRINIO_API_KEY` | Institutional-grade fundamentals | | **yfinance** | Quotes, fundamentals, financials, historical prices, news, ETF, index, crypto, forex, options, futures, analyst upgrades, price targets, dividends, management |
| **Tiingo** | `OBB_TIINGO_TOKEN` | Reliable historical price data | | **SEC** | Insider trading (Form 4), institutional holdings (13F), company filings, N-PORT disclosures, CIK mapping |
| **Benzinga** | `OBB_BENZINGA_API_KEY` | Real-time news, analyst ratings | | **stockgrid** | Short volume data |
| **FINRA** | Short interest, dark pool OTC data |
| **multpl** | S&P 500 historical valuation multiples |
| **CFTC** | Commitment of Traders reports |
| **ECB** | Currency reference rates |
| **OECD** | GDP, unemployment, CPI, CLI, housing price index |
| **openbb-technical** | 14 technical indicators (local computation) |
| **openbb-quantitative** | Risk metrics, CAPM, normality tests (local computation) |
### Configuration ### Configuration
@@ -59,36 +66,39 @@ Server starts at `http://localhost:8000`. Visit `http://localhost:8000/docs` for
# Health check # Health check
curl http://localhost:8000/health curl http://localhost:8000/health
# US stock quote # Stock quote
curl http://localhost:8000/api/v1/stock/AAPL/quote curl http://localhost:8000/api/v1/stock/AAPL/quote
# Swedish stock quote # Technical indicators (14 individual + composite)
curl http://localhost:8000/api/v1/stock/VOLV-B.ST/quote
# Sentiment analysis (Finnhub + Alpha Vantage)
curl http://localhost:8000/api/v1/stock/AAPL/sentiment
# 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 curl http://localhost:8000/api/v1/stock/AAPL/technical
curl http://localhost:8000/api/v1/stock/AAPL/technical/ichimoku
# Quantitative risk metrics # Relative Rotation Graph (multi-symbol)
curl http://localhost:8000/api/v1/stock/AAPL/performance curl "http://localhost:8000/api/v1/technical/relative-rotation?symbols=AAPL,MSFT,GOOGL&benchmark=SPY"
curl http://localhost:8000/api/v1/stock/AAPL/capm
# SEC insider trading # Quantitative analysis
curl http://localhost:8000/api/v1/stock/AAPL/sec-insider curl http://localhost:8000/api/v1/stock/AAPL/sortino
curl http://localhost:8000/api/v1/stock/AAPL/rolling/skew?window=20
# ETF info # Fixed income
curl http://localhost:8000/api/v1/etf/SPY/info curl http://localhost:8000/api/v1/fixed-income/yield-curve
curl http://localhost:8000/api/v1/fixed-income/treasury-rates
# Crypto price history # Macro economics
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 curl http://localhost:8000/api/v1/macro/overview
curl http://localhost:8000/api/v1/macro/cpi
curl http://localhost:8000/api/v1/macro/money-measures
# Economy surveys
curl http://localhost:8000/api/v1/economy/surveys/michigan
curl http://localhost:8000/api/v1/economy/surveys/sloos
# Shorts & dark pool
curl http://localhost:8000/api/v1/stock/AAPL/shorts/volume
curl http://localhost:8000/api/v1/darkpool/AAPL/otc
# Regulators
curl "http://localhost:8000/api/v1/regulators/cot/search?query=gold"
# Portfolio analysis # Portfolio analysis
curl -X POST http://localhost:8000/api/v1/portfolio/analyze \ curl -X POST http://localhost:8000/api/v1/portfolio/analyze \
@@ -96,7 +106,7 @@ curl -X POST http://localhost:8000/api/v1/portfolio/analyze \
-d '{"holdings":[{"symbol":"AAPL","shares":100,"buy_in_price":150},{"symbol":"VOLV-B.ST","shares":50,"buy_in_price":250}]}' -d '{"holdings":[{"symbol":"AAPL","shares":100,"buy_in_price":150},{"symbol":"VOLV-B.ST","shares":50,"buy_in_price":250}]}'
``` ```
## API Endpoints ## API Endpoints (99 total)
### Health ### Health
@@ -115,6 +125,10 @@ curl -X POST http://localhost:8000/api/v1/portfolio/analyze \
| GET | `/api/v1/stock/{symbol}/historical?days=365` | Historical OHLCV data | | GET | `/api/v1/stock/{symbol}/historical?days=365` | Historical OHLCV data |
| GET | `/api/v1/stock/{symbol}/news` | Recent company news | | GET | `/api/v1/stock/{symbol}/news` | Recent company news |
| GET | `/api/v1/stock/{symbol}/summary` | Aggregated: quote + profile + metrics + financials | | GET | `/api/v1/stock/{symbol}/summary` | Aggregated: quote + profile + metrics + financials |
| GET | `/api/v1/stock/{symbol}/management` | Executive team: name, title, compensation |
| GET | `/api/v1/stock/{symbol}/dividends` | Historical dividend records |
| GET | `/api/v1/stock/{symbol}/filings?form_type=10-K` | SEC filings (10-K, 10-Q, 8-K) |
| GET | `/api/v1/search?query=` | Company search by name (SEC/NASDAQ) |
### Sentiment & Analyst Data (Finnhub + Alpha Vantage + yfinance) ### Sentiment & Analyst Data (Finnhub + Alpha Vantage + yfinance)
@@ -126,20 +140,96 @@ curl -X POST http://localhost:8000/api/v1/portfolio/analyze \
| GET | `/api/v1/stock/{symbol}/recommendations` | Monthly analyst buy/hold/sell counts (Finnhub) | | GET | `/api/v1/stock/{symbol}/recommendations` | Monthly analyst buy/hold/sell counts (Finnhub) |
| GET | `/api/v1/stock/{symbol}/upgrades` | Analyst upgrades/downgrades with price targets (yfinance) | | GET | `/api/v1/stock/{symbol}/upgrades` | Analyst upgrades/downgrades with price targets (yfinance) |
### Technical Analysis (local computation, no key needed) ### Technical Analysis (14 indicators, local computation, no key needed)
| Method | Path | Description | | Method | Path | Description |
|--------|------|-------------| |--------|------|-------------|
| GET | `/api/v1/stock/{symbol}/technical` | RSI, MACD, SMA, EMA, Bollinger Bands + signal interpretation | | GET | `/api/v1/stock/{symbol}/technical` | Composite: RSI, MACD, SMA, EMA, Bollinger Bands + signals |
| GET | `/api/v1/stock/{symbol}/technical/atr` | Average True Range (volatility, position sizing) |
| GET | `/api/v1/stock/{symbol}/technical/adx` | Average Directional Index (trend strength) |
| GET | `/api/v1/stock/{symbol}/technical/stoch` | Stochastic Oscillator (overbought/oversold) |
| GET | `/api/v1/stock/{symbol}/technical/obv` | On-Balance Volume (volume-price divergence) |
| GET | `/api/v1/stock/{symbol}/technical/ichimoku` | Ichimoku Cloud (comprehensive trend system) |
| GET | `/api/v1/stock/{symbol}/technical/donchian` | Donchian Channels (breakout detection) |
| GET | `/api/v1/stock/{symbol}/technical/aroon` | Aroon Indicator (trend direction/changes) |
| GET | `/api/v1/stock/{symbol}/technical/cci` | Commodity Channel Index (cyclical trends) |
| GET | `/api/v1/stock/{symbol}/technical/kc` | Keltner Channels (ATR-based volatility bands) |
| GET | `/api/v1/stock/{symbol}/technical/fib` | Fibonacci Retracement (support/resistance levels) |
| GET | `/api/v1/stock/{symbol}/technical/ad` | Accumulation/Distribution Line |
| GET | `/api/v1/stock/{symbol}/technical/cones` | Volatility Cones (realized vol quantiles) |
| GET | `/api/v1/stock/{symbol}/technical/vwap` | Volume Weighted Average Price |
| GET | `/api/v1/technical/relative-rotation?symbols=&benchmark=SPY` | Relative Rotation Graph (multi-symbol sector rotation) |
### Quantitative Analysis (openbb-quantitative, no key needed) ### Quantitative Analysis (local computation, no key needed)
| Method | Path | Description | | Method | Path | Description |
|--------|------|-------------| |--------|------|-------------|
| GET | `/api/v1/stock/{symbol}/performance?days=365` | Sharpe ratio, summary statistics, volatility | | 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}/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}/normality?days=365` | Normality tests: Jarque-Bera, Shapiro-Wilk, K-S |
| GET | `/api/v1/stock/{symbol}/unitroot?days=365` | Unit root tests: ADF, KPSS for stationarity | | GET | `/api/v1/stock/{symbol}/unitroot?days=365` | Unit root tests: ADF, KPSS for stationarity |
| GET | `/api/v1/stock/{symbol}/sortino?days=365` | Sortino ratio (downside risk only) |
| GET | `/api/v1/stock/{symbol}/omega?days=365` | Omega ratio (full distribution gain/loss) |
| GET | `/api/v1/stock/{symbol}/rolling/{stat}?days=365&window=30` | Rolling stats: variance, stdev, mean, skew, kurtosis, quantile |
### Shorts & Dark Pool (stockgrid/FINRA/SEC, no key needed)
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/stock/{symbol}/shorts/volume` | Daily short volume and percent (stockgrid) |
| GET | `/api/v1/stock/{symbol}/shorts/ftd` | Fails-to-deliver records (SEC) |
| GET | `/api/v1/stock/{symbol}/shorts/interest` | Short interest, days to cover (FINRA) |
| GET | `/api/v1/darkpool/{symbol}/otc` | OTC/dark pool aggregate trade volume (FINRA) |
### Fixed Income (FRED/Federal Reserve, free key)
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/fixed-income/treasury-rates` | Full yield curve rates (4W-30Y) |
| GET | `/api/v1/fixed-income/yield-curve?date=` | Yield curve with maturity/rate pairs |
| GET | `/api/v1/fixed-income/treasury-auctions` | Treasury auction bid-to-cover, yields |
| GET | `/api/v1/fixed-income/tips-yields` | TIPS real yields by maturity |
| GET | `/api/v1/fixed-income/effr` | Effective Federal Funds Rate with percentiles |
| GET | `/api/v1/fixed-income/sofr` | SOFR rate with 30/90/180-day moving averages |
| GET | `/api/v1/fixed-income/hqm` | High Quality Market corporate bond yields |
| GET | `/api/v1/fixed-income/commercial-paper` | Commercial paper rates by maturity/type |
| GET | `/api/v1/fixed-income/spot-rates` | Corporate bond spot rates and par yields |
| GET | `/api/v1/fixed-income/spreads?series=tcm` | Treasury/corporate spreads |
### Macro Economics (FRED/OECD, free key)
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/macro/overview` | Key indicators: Fed rate, treasury yields, CPI, unemployment, GDP, VIX |
| GET | `/api/v1/macro/series/{series_id}?limit=30` | Any FRED time series by ID |
| GET | `/api/v1/macro/cpi?country=united_states` | Consumer Price Index (multi-country) |
| GET | `/api/v1/macro/gdp?gdp_type=real` | GDP: nominal, real, or forecast |
| GET | `/api/v1/macro/unemployment?country=united_states` | Unemployment rate (multi-country) |
| GET | `/api/v1/macro/pce` | Personal Consumption Expenditures (Fed preferred inflation) |
| GET | `/api/v1/macro/money-measures` | M1/M2 money supply |
| GET | `/api/v1/macro/cli?country=united_states` | Composite Leading Indicator (recession predictor) |
| GET | `/api/v1/macro/house-price-index?country=united_states` | Housing price index (multi-country) |
### Economy Data (FRED/Federal Reserve)
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/economy/fred-search?query=` | Search 800K+ FRED economic series |
| GET | `/api/v1/economy/fred-regional?series_id=` | Regional economic data (by state/county/MSA) |
| GET | `/api/v1/economy/balance-of-payments` | Current/capital/financial account balances |
| GET | `/api/v1/economy/central-bank-holdings` | Fed SOMA portfolio holdings |
| GET | `/api/v1/economy/primary-dealer-positioning` | Primary dealer net positions |
| GET | `/api/v1/economy/fomc-documents?year=` | FOMC meeting documents |
### Economy Surveys (FRED/BLS)
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/economy/surveys/michigan` | University of Michigan Consumer Sentiment |
| GET | `/api/v1/economy/surveys/sloos` | Senior Loan Officer Survey (recession signal) |
| GET | `/api/v1/economy/surveys/nonfarm-payrolls` | Detailed employment data |
| GET | `/api/v1/economy/surveys/empire-state` | NY manufacturing outlook |
| GET | `/api/v1/economy/surveys/bls-search?query=` | Search BLS data series |
### Calendar Events (no key needed) ### Calendar Events (no key needed)
@@ -160,20 +250,23 @@ curl -X POST http://localhost:8000/api/v1/portfolio/analyze \
| GET | `/api/v1/stock/{symbol}/institutional` | Institutional holders from SEC 13F filings | | GET | `/api/v1/stock/{symbol}/institutional` | Institutional holders from SEC 13F filings |
| GET | `/api/v1/screener` | Stock screener | | GET | `/api/v1/screener` | Stock screener |
### ETF Data (yfinance, no key needed) ### ETF Data (yfinance + SEC, no key needed)
| Method | Path | Description | | Method | Path | Description |
|--------|------|-------------| |--------|------|-------------|
| GET | `/api/v1/etf/{symbol}/info` | ETF profile, issuer, holdings | | 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/{symbol}/historical?days=365` | ETF price history |
| GET | `/api/v1/etf/{symbol}/nport` | Detailed ETF holdings from SEC N-PORT filings |
| GET | `/api/v1/etf/search?query=` | Search ETFs by name | | GET | `/api/v1/etf/search?query=` | Search ETFs by name |
### Index Data (yfinance, no key needed) ### Index Data (yfinance + multpl + cboe, no key needed)
| Method | Path | Description | | Method | Path | Description |
|--------|------|-------------| |--------|------|-------------|
| GET | `/api/v1/index/available` | List available indices | | GET | `/api/v1/index/available` | List available indices |
| GET | `/api/v1/index/{symbol}/historical?days=365` | Index price history (^GSPC, ^DJI, ^IXIC) | | GET | `/api/v1/index/{symbol}/historical?days=365` | Index price history (^GSPC, ^DJI, ^IXIC) |
| GET | `/api/v1/index/sp500-multiples?series=pe_ratio` | Historical S&P 500 valuation (PE, Shiller PE, P/B, dividend yield) |
| GET | `/api/v1/index/{symbol}/constituents` | Index member stocks with sector/price data |
### Crypto Data (yfinance, no key needed) ### Crypto Data (yfinance, no key needed)
@@ -182,11 +275,12 @@ curl -X POST http://localhost:8000/api/v1/portfolio/analyze \
| GET | `/api/v1/crypto/{symbol}/historical?days=365` | Crypto price history (BTC-USD, ETH-USD) | | GET | `/api/v1/crypto/{symbol}/historical?days=365` | Crypto price history (BTC-USD, ETH-USD) |
| GET | `/api/v1/crypto/search?query=` | Search cryptocurrencies | | GET | `/api/v1/crypto/search?query=` | Search cryptocurrencies |
### Currency / Forex (yfinance, no key needed) ### Currency / Forex (yfinance + ECB, no key needed)
| Method | Path | Description | | Method | Path | Description |
|--------|------|-------------| |--------|------|-------------|
| GET | `/api/v1/currency/{symbol}/historical?days=365` | Forex price history (EURUSD, USDSEK) | | GET | `/api/v1/currency/{symbol}/historical?days=365` | Forex price history (EURUSD, USDSEK) |
| GET | `/api/v1/currency/reference-rates` | ECB reference rates for 28 major currencies |
### Derivatives (yfinance, no key needed) ### Derivatives (yfinance, no key needed)
@@ -196,12 +290,15 @@ curl -X POST http://localhost:8000/api/v1/portfolio/analyze \
| GET | `/api/v1/futures/{symbol}/historical?days=365` | Futures price history | | GET | `/api/v1/futures/{symbol}/historical?days=365` | Futures price history |
| GET | `/api/v1/futures/{symbol}/curve` | Futures term structure/curve | | GET | `/api/v1/futures/{symbol}/curve` | Futures term structure/curve |
### Macro Economics (FRED, free key) ### Regulators (CFTC/SEC, no key needed)
| Method | Path | Description | | Method | Path | Description |
|--------|------|-------------| |--------|------|-------------|
| GET | `/api/v1/macro/overview` | Key indicators: Fed rate, treasury yields, CPI, unemployment, GDP, VIX | | GET | `/api/v1/regulators/cot?symbol=` | Commitment of Traders (futures positions) |
| GET | `/api/v1/macro/series/{series_id}?limit=30` | Any FRED time series by ID | | GET | `/api/v1/regulators/cot/search?query=` | Search COT report symbols |
| GET | `/api/v1/regulators/sec/litigation` | SEC litigation releases |
| GET | `/api/v1/regulators/sec/institutions?query=` | Search institutional investors |
| GET | `/api/v1/regulators/sec/cik-map/{symbol}` | Ticker to SEC CIK mapping |
### Portfolio Analysis (no key needed) ### Portfolio Analysis (no key needed)
@@ -256,38 +353,51 @@ All settings are configurable via environment variables with the `INVEST_API_` p
| `INVEST_API_LOG_LEVEL` | `info` | Logging level | | `INVEST_API_LOG_LEVEL` | `info` | Logging level |
| `INVEST_API_DEBUG` | `false` | Enable debug mode (auto-reload) | | `INVEST_API_DEBUG` | `false` | Enable debug mode (auto-reload) |
| `INVEST_API_FINNHUB_API_KEY` | _(empty)_ | Finnhub API key for analyst data | | `INVEST_API_FINNHUB_API_KEY` | _(empty)_ | Finnhub API key for analyst data |
| `INVEST_API_FRED_API_KEY` | _(empty)_ | FRED API key for macro data | | `INVEST_API_FRED_API_KEY` | _(empty)_ | FRED API key for macro/fixed income/surveys |
| `INVEST_API_ALPHAVANTAGE_API_KEY` | _(empty)_ | Alpha Vantage API key for news sentiment | | `INVEST_API_ALPHAVANTAGE_API_KEY` | _(empty)_ | Alpha Vantage API key for news sentiment |
## Project Structure ## Project Structure
``` ```
openbb-invest-api/ openbb-invest-api/
├── main.py # FastAPI app entry point ├── main.py # FastAPI app entry point (lifespan, curl_cffi patch)
├── config.py # Settings (env-based) ├── config.py # Settings (env-based)
├── models.py # Pydantic request/response models ├── models.py # Pydantic request/response models
├── mappers.py # Dict-to-model mapping functions ├── mappers.py # Dict-to-model mapping functions
├── route_utils.py # Shared route utilities (validation, error handling) ├── route_utils.py # Shared route utilities (validation, error handling)
├── obb_utils.py # Shared OpenBB result conversion utilities ├── obb_utils.py # Shared OpenBB result conversion + fetch helpers
├── openbb_service.py # OpenBB SDK wrapper (async) │
├── finnhub_service.py # Finnhub REST client (insider, analyst data) ├── openbb_service.py # Equity data via OpenBB/yfinance (quote, profile, metrics, etc.)
├── alphavantage_service.py # Alpha Vantage REST client (news sentiment) ├── finnhub_service.py # Finnhub REST client (insider, analyst data)
├── quantitative_service.py # Risk metrics, CAPM, normality tests ├── alphavantage_service.py # Alpha Vantage REST client (news sentiment)
├── calendar_service.py # Calendar events, screening, ownership ├── technical_service.py # 14 technical indicators via openbb-technical
├── market_service.py # ETF, index, crypto, currency, derivatives ├── quantitative_service.py # Risk metrics, CAPM, Sortino, Omega, rolling stats
├── macro_service.py # FRED macro data via OpenBB ├── macro_service.py # FRED macro data via OpenBB
├── technical_service.py # Technical indicators via openbb-technical ├── economy_service.py # Economy data: CPI, GDP, Fed holdings, FOMC docs
├── analysis_service.py # Rule engine for portfolio analysis ├── surveys_service.py # Economy surveys: Michigan, SLOOS, NFP, BLS
├── routes.py # Core stock data + portfolio + discovery routes ├── fixed_income_service.py # Fixed income: yield curve, treasury, SOFR, spreads
├── routes_sentiment.py # Sentiment & analyst routes (Finnhub + Alpha Vantage) ├── shorts_service.py # Shorts & dark pool (stockgrid, FINRA, SEC)
├── routes_quantitative.py # Quantitative analysis routes ├── regulators_service.py # CFTC COT reports, SEC litigation, institutions
├── routes_calendar.py # Calendar, estimates, ownership routes ├── market_service.py # ETF, index, crypto, currency, derivatives
├── routes_market.py # ETF, index, crypto, currency, derivatives routes ├── calendar_service.py # Calendar events, screening, ownership
├── routes_macro.py # Macro economics routes (FRED) ├── analysis_service.py # Rule engine for portfolio analysis
├── routes_technical.py # Technical analysis routes │
├── environment.yml # Conda environment ├── routes.py # Core stock data + portfolio + discovery routes
├── pyproject.toml # Project metadata ├── routes_sentiment.py # Sentiment & analyst routes
└── tests/ # 102 tests ├── routes_technical.py # Technical analysis routes (14 indicators)
├── routes_quantitative.py # Quantitative analysis routes
├── routes_macro.py # Macro economics routes
├── routes_economy.py # Economy data routes
├── routes_surveys.py # Economy survey routes
├── routes_fixed_income.py # Fixed income routes
├── routes_shorts.py # Shorts & dark pool routes
├── routes_regulators.py # Regulator data routes
├── routes_calendar.py # Calendar, estimates, ownership routes
├── routes_market.py # ETF, index, crypto, currency, derivatives routes
│
├── Dockerfile # Docker build (curl_cffi==0.7.4, safari TLS patch)
├── pyproject.toml # Project metadata + dependencies
└── tests/ # 102 tests
``` ```
## Running Tests ## Running Tests
@@ -315,11 +425,13 @@ Example OpenClaw workflow:
2. OpenClaw calls `GET /api/v1/stock/AAPL/summary` for fundamental data 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 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 4. OpenClaw calls `GET /api/v1/stock/AAPL/technical` for technical signals
5. OpenClaw calls `GET /api/v1/stock/AAPL/performance` for risk metrics (Sharpe, volatility) 5. OpenClaw calls `GET /api/v1/stock/AAPL/performance` for risk metrics (Sharpe, Sortino)
6. OpenClaw calls `GET /api/v1/stock/AAPL/sec-insider` for insider trading activity 6. OpenClaw calls `GET /api/v1/stock/AAPL/shorts/volume` for short selling activity
7. OpenClaw calls `GET /api/v1/macro/overview` for market context 7. OpenClaw calls `GET /api/v1/stock/AAPL/sec-insider` for insider trading activity
8. OpenClaw calls `POST /api/v1/portfolio/analyze` with user's holdings 8. OpenClaw calls `GET /api/v1/macro/overview` for market context
9. OpenClaw's LLM synthesizes all structured data into a personalized recommendation 9. OpenClaw calls `GET /api/v1/fixed-income/yield-curve` for rate environment
10. OpenClaw calls `POST /api/v1/portfolio/analyze` with user's holdings
11. OpenClaw's LLM synthesizes all structured data into a personalized recommendation
## Kubernetes Deployment ## Kubernetes Deployment
@@ -333,7 +445,7 @@ Example OpenClaw workflow:
### Architecture ### Architecture
``` ```
git push → Gitea → Drone CI (kaniko) → Docker Registry → ArgoCD → K8s git push -> Gitea -> Drone CI (kaniko) -> Docker Registry -> ArgoCD -> K8s
``` ```
### Cluster Info ### Cluster Info
@@ -410,7 +522,7 @@ steps:
--from-literal=INVEST_API_ALPHAVANTAGE_API_KEY=your_key --from-literal=INVEST_API_ALPHAVANTAGE_API_KEY=your_key
``` ```
6. Add DNS: `invest-api.k8s.home → 192.168.68.22` 6. Add DNS: `invest-api.k8s.home -> 192.168.68.22`
7. Verify: 7. Verify:
```bash ```bash
@@ -431,13 +543,20 @@ docker run -p 8000:8000 invest-api
| Source | Cost | Key Required | Data Provided | | Source | Cost | Key Required | Data Provided |
|--------|------|-------------|---------------| |--------|------|-------------|---------------|
| **yfinance** | Free | No | Quotes, fundamentals, financials, historical prices, news, discovery, ETF, index, crypto, forex, options, futures, analyst upgrades/downgrades, price targets | | **yfinance** | Free | No | Quotes, fundamentals, financials, historical prices, news, discovery, ETF, index, crypto, forex, options, futures, analyst upgrades/downgrades, price targets, dividends, management |
| **SEC** | Free | No | Insider trading (Form 4), institutional holdings (13F), company filings | | **SEC** | Free | No | Insider trading (Form 4), institutional holdings (13F), company filings, N-PORT disclosures, CIK mapping, litigation releases |
| **stockgrid** | Free | No | Daily short volume data |
| **FINRA** | Free | No | Short interest, dark pool OTC trade data |
| **CFTC** | Free | No | Commitment of Traders reports |
| **multpl** | Free | No | S&P 500 historical valuation multiples (PE, Shiller PE, P/B, dividend yield) |
| **ECB** | Free | No | Currency reference rates (28 currencies) |
| **OECD** | Free | No | GDP, unemployment, CPI, Composite Leading Indicator, housing price index |
| **Finnhub** | Free | Yes (free registration) | Insider trades, analyst recommendations, company news | | **Finnhub** | Free | Yes (free registration) | Insider trades, analyst recommendations, company news |
| **Alpha Vantage** | Free | Yes (free registration) | News sentiment scores (bullish/bearish per ticker per article), 25 req/day | | **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 | | **FRED** | Free | Yes (free registration) | Fed rate, treasury yields, CPI, PCE, money supply, surveys, 800K+ economic series |
| **openbb-technical** | Free | No (local computation) | RSI, MACD, SMA, EMA, Bollinger Bands | | **Federal Reserve** | Free | No | EFFR, SOFR, money measures, central bank holdings, primary dealer positions, FOMC documents |
| **openbb-quantitative** | Free | No (local computation) | Sharpe ratio, CAPM, normality tests, unit root tests, summary statistics | | **openbb-technical** | Free | No (local) | ATR, ADX, Stochastic, OBV, Ichimoku, Donchian, Aroon, CCI, Keltner, Fibonacci, A/D, VWAP, Volatility Cones, Relative Rotation |
| **openbb-quantitative** | Free | No (local) | Sharpe, Sortino, Omega ratios, CAPM, normality tests, unit root tests, rolling statistics |
## Known Issues ## Known Issues