# OpenBB Investment Analysis API

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

### Required: None

The core functionality uses **yfinance** (free, no API key). The API works without any keys configured.

### Recommended Free Keys

| 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 |
| **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 |

### Free Providers (no key needed)

| Provider | Data Provided |
|----------|---------------|
| **yfinance** | Quotes, fundamentals, financials, historical prices, news, ETF, index, crypto, forex, options, futures, analyst upgrades, price targets, dividends, management |
| **SEC** | Insider trading (Form 4), institutional holdings (13F), company filings, N-PORT disclosures, CIK mapping |
| **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

Set environment variables before starting, or add to a `.env` file:

```bash
export INVEST_API_FINNHUB_API_KEY=your_finnhub_key
export INVEST_API_FRED_API_KEY=your_fred_key
export INVEST_API_ALPHAVANTAGE_API_KEY=your_alphavantage_key
```

## Quick Start

### 1. Create conda environment

```bash
conda create -n openbb-invest-api python=3.12 -y
conda activate openbb-invest-api
pip install -e .
pip install openbb-quantitative openbb-econometrics openbb-technical
```

### 2. Start the server

```bash
python main.py
```

Server starts at `http://localhost:8000`. Visit `http://localhost:8000/docs` for Swagger UI.

### 3. Test it

```bash
# Health check
curl http://localhost:8000/health

# Stock quote
curl http://localhost:8000/api/v1/stock/AAPL/quote

# Technical indicators (14 individual + composite)
curl http://localhost:8000/api/v1/stock/AAPL/technical
curl http://localhost:8000/api/v1/stock/AAPL/technical/ichimoku

# Relative Rotation Graph (multi-symbol)
curl "http://localhost:8000/api/v1/technical/relative-rotation?symbols=AAPL,MSFT,GOOGL&benchmark=SPY"

# Quantitative analysis
curl http://localhost:8000/api/v1/stock/AAPL/sortino
curl http://localhost:8000/api/v1/stock/AAPL/rolling/skew?window=20

# Fixed income
curl http://localhost:8000/api/v1/fixed-income/yield-curve
curl http://localhost:8000/api/v1/fixed-income/treasury-rates

# Macro economics
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
curl -X POST http://localhost:8000/api/v1/portfolio/analyze \
  -H "Content-Type: application/json" \
  -d '{"holdings":[{"symbol":"AAPL","shares":100,"buy_in_price":150},{"symbol":"VOLV-B.ST","shares":50,"buy_in_price":250}]}'
```

## API Endpoints (102 total)

### Health

| Method | Path | Description |
|--------|------|-------------|
| GET | `/health` | Health check |

### Stock Data (yfinance, no key needed)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/stock/{symbol}/quote` | Current price and volume |
| GET | `/api/v1/stock/{symbol}/profile` | Company overview (sector, industry, description) |
| GET | `/api/v1/stock/{symbol}/metrics` | Key ratios (PE, PB, ROE, EPS, etc.) |
| GET | `/api/v1/stock/{symbol}/financials` | Income statement + balance sheet + cash flow |
| 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}/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 + Reddit)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/stock/{symbol}/sentiment` | Composite sentiment score from all sources (-1 to +1) |
| GET | `/api/v1/stock/{symbol}/news-sentiment?limit=30` | News articles with per-ticker sentiment scores (Alpha Vantage) |
| GET | `/api/v1/stock/{symbol}/social-sentiment` | Social media sentiment from Reddit + Twitter (Finnhub) |
| GET | `/api/v1/stock/{symbol}/reddit-sentiment` | Reddit mentions, upvotes, rank (ApeWisdom, free) |
| GET | `/api/v1/stock/{symbol}/insider-trades` | Insider transactions via 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/discover/reddit-trending` | Top 25 trending stocks on Reddit (free) |

The `/sentiment` endpoint aggregates 4 sources into a weighted composite score:

| Source | Weight | Data |
|--------|--------|------|
| News (Alpha Vantage) | 25% | Article-level bullish/bearish scores |
| Analysts (Finnhub) | 30% | Buy/sell recommendation ratio |
| Upgrades (yfinance) | 20% | Recent upgrade/downgrade actions |
| Reddit (ApeWisdom) | 25% | 24h mention change trend |

### Technical Analysis (14 indicators, local computation, no key needed)

| Method | Path | Description |
|--------|------|-------------|
| 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 (local computation, 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, K-S |
| 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)

| 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 + SEC, 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/{symbol}/nport` | Detailed ETF holdings from SEC N-PORT filings |
| GET | `/api/v1/etf/search?query=` | Search ETFs by name |

### Index Data (yfinance + multpl + cboe, 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) |
| 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)

| 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 + ECB, no key needed)

| Method | Path | Description |
|--------|------|-------------|
| 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)

| 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 |

### Regulators (CFTC/SEC, no key needed)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/regulators/cot?symbol=` | Commitment of Traders (futures positions) |
| 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)

| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/v1/portfolio/analyze` | Rule-based analysis of holdings (max 50) |

Request body:
```json
{
  "holdings": [
    {"symbol": "AAPL", "shares": 100, "buy_in_price": 150.0},
    {"symbol": "VOLV-B.ST", "shares": 50, "buy_in_price": 250.0}
  ]
}
```

Response includes per-holding: current price, P&L, key metrics, analyst target price, and a rule-engine recommendation (BUY_MORE / HOLD / SELL) with confidence level and reasons.

### Stock Discovery (no key needed)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/discover/gainers` | Top gainers |
| GET | `/api/v1/discover/losers` | Top losers |
| GET | `/api/v1/discover/active` | Most active |
| GET | `/api/v1/discover/undervalued` | Undervalued large caps |
| GET | `/api/v1/discover/growth` | Growth tech stocks |

## Rule Engine

The portfolio analysis endpoint uses a rule-based engine (no LLM) that scores each holding on four signals:

| Signal | BUY_MORE (+1) | HOLD (0) | SELL (-1) |
|--------|---------------|----------|-----------|
| Price vs analyst target | >15% upside | -10% to +15% | >10% downside |
| PE ratio | < 15 | 15 - 35 | > 35 or negative |
| Revenue growth | > 10% YoY | 0 - 10% | Negative |
| P&L vs cost basis | Loss > 20% | -20% to +50% | Profit > 50% |

Scores are summed. Total >= 2 = BUY_MORE, <= -2 = SELL, otherwise HOLD. Confidence is HIGH/MEDIUM/LOW based on how many signals agree.

## Configuration

All settings are configurable via environment variables with the `INVEST_API_` prefix:

| Variable | Default | Description |
|----------|---------|-------------|
| `INVEST_API_HOST` | `0.0.0.0` | Server bind address |
| `INVEST_API_PORT` | `8000` | Server port |
| `INVEST_API_CORS_ORIGINS` | `["http://localhost:3000"]` | Allowed CORS origins (JSON array) |
| `INVEST_API_LOG_LEVEL` | `info` | Logging level |
| `INVEST_API_DEBUG` | `false` | Enable debug mode (auto-reload) |
| `INVEST_API_FINNHUB_API_KEY` | _(empty)_ | Finnhub API key for analyst 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 |

## Project Structure

```
openbb-invest-api/
├── main.py                  # FastAPI app entry point (lifespan, curl_cffi patch)
├── config.py                # Settings (env-based)
├── models.py                # Pydantic request/response models
├── mappers.py               # Dict-to-model mapping functions
├── route_utils.py           # Shared route utilities (validation, error handling)
├── obb_utils.py             # Shared OpenBB result conversion + fetch helpers
│
├── openbb_service.py        # Equity data via OpenBB/yfinance (quote, profile, metrics, etc.)
├── finnhub_service.py       # Finnhub REST client (insider, analyst data)
├── alphavantage_service.py  # Alpha Vantage REST client (news sentiment)
├── technical_service.py     # 14 technical indicators via openbb-technical
├── quantitative_service.py  # Risk metrics, CAPM, Sortino, Omega, rolling stats
├── macro_service.py         # FRED macro data via OpenBB
├── economy_service.py       # Economy data: CPI, GDP, Fed holdings, FOMC docs
├── surveys_service.py       # Economy surveys: Michigan, SLOOS, NFP, BLS
├── fixed_income_service.py  # Fixed income: yield curve, treasury, SOFR, spreads
├── shorts_service.py        # Shorts & dark pool (stockgrid, FINRA, SEC)
├── regulators_service.py    # CFTC COT reports, SEC litigation, institutions
├── market_service.py        # ETF, index, crypto, currency, derivatives
├── calendar_service.py      # Calendar events, screening, ownership
├── analysis_service.py      # Rule engine for portfolio analysis
│
├── routes.py                # Core stock data + portfolio + discovery routes
├── routes_sentiment.py      # Sentiment & analyst routes
├── 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

```bash
conda activate openbb-invest-api
python -m pytest tests/ -v
```

## Swedish Stocks

Swedish stocks are supported via the `.ST` suffix (Stockholm exchange):
- `VOLV-B.ST` (Volvo)
- `ERIC-B.ST` (Ericsson)
- `HM-B.ST` (H&M)
- `SEB-A.ST` (SEB)
- `SAND.ST` (Sandvik)

## Integration with OpenClaw

This API is designed to be called by OpenClaw as an MCP tool or HTTP data source. OpenClaw sends requests to this API to fetch structured stock data and rule-based analysis, then uses its LLM to generate natural language investment advice.

Example OpenClaw workflow:
1. User asks: "Should I buy more AAPL?"
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/stock/AAPL/performance` for risk metrics (Sharpe, Sortino)
6. OpenClaw calls `GET /api/v1/stock/AAPL/shorts/volume` for short selling activity
7. OpenClaw calls `GET /api/v1/stock/AAPL/sec-insider` for insider trading activity
8. OpenClaw calls `GET /api/v1/macro/overview` for market context
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

### Prerequisites

- Kubernetes cluster with ingress-nginx
- Docker Registry at `192.168.68.11:30500`
- Drone CI connected to Gitea
- ArgoCD installed

### Architecture

```
git push -> Gitea -> Drone CI (kaniko) -> Docker Registry -> ArgoCD -> K8s
```

### Cluster Info

| Component | Value |
|-----------|-------|
| API URL | `https://invest-api.k8s.home` |
| Namespace | `invest-api` |
| Image | `192.168.68.11:30500/invest-api:latest` |
| Resources | 100m-500m CPU, 256Mi-512Mi memory |
| Health check | `GET /health` on port 8000 |

### K8s Manifests

Located in `k8s/base/` (Kustomize):

| File | Description |
|------|-------------|
| `namespace.yaml` | `invest-api` namespace |
| `deployment.yaml` | App deployment with health probes |
| `service.yaml` | ClusterIP service on port 8000 |
| `ingress.yaml` | Ingress for `invest-api.k8s.home` |
| `secret.yaml` | Template for API keys |
| `kustomization.yaml` | Kustomize resource list |

ArgoCD Application defined in `k8s/argocd-app.yaml`.

### CI/CD Pipeline

`.drone.yml` uses kaniko to build and push:

```yaml
kind: pipeline
type: kubernetes
name: build-and-push

trigger:
  branch: [main, develop]
  event: [push, custom]

steps:
  - name: build-and-push
    image: gcr.io/kaniko-project/executor:debug
    commands:
      - /kaniko/executor
        --context=/drone/src
        --dockerfile=Dockerfile
        --destination=192.168.68.11:30500/invest-api:${DRONE_COMMIT_SHA:0:8}
        --destination=192.168.68.11:30500/invest-api:latest
        --insecure --skip-tls-verify
```

### Deploy from Scratch

1. Deploy Docker Registry:
   ```bash
   kubectl apply -k k8s-infra/registry/
   ```

2. Configure containerd on worker nodes to trust insecure registry (see `HomeLab Infrastructure` doc)

3. Push code to Gitea -- Drone builds and pushes image automatically

4. Apply ArgoCD Application:
   ```bash
   kubectl apply -f k8s/argocd-app.yaml
   ```

5. Create API key secrets (optional):
   ```bash
   kubectl -n invest-api create secret generic invest-api-secrets \
     --from-literal=INVEST_API_FINNHUB_API_KEY=your_key \
     --from-literal=INVEST_API_FRED_API_KEY=your_key \
     --from-literal=INVEST_API_ALPHAVANTAGE_API_KEY=your_key
   ```

6. Add DNS: `invest-api.k8s.home -> 192.168.68.22`

7. Verify:
   ```bash
   curl -k https://invest-api.k8s.home/health
   curl -k https://invest-api.k8s.home/api/v1/stock/AAPL/quote
   ```

### Docker

Build and run locally:

```bash
docker build -t invest-api .
docker run -p 8000:8000 invest-api
```

## Data Sources

| 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, dividends, management |
| **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 |
| **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, PCE, money supply, surveys, 800K+ economic series |
| **Federal Reserve** | Free | No | EFFR, SOFR, money measures, central bank holdings, primary dealer positions, FOMC documents |
| **ApeWisdom** | Free | No | Reddit stock mentions, upvotes, trending (WSB, r/stocks, r/investing) |
| **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

### curl_cffi TLS Fingerprint

yfinance depends on `curl_cffi` for browser-impersonated HTTP requests. Versions 0.12+ have a BoringSSL bug
that causes `SSL_ERROR_SYSCALL` on some networks (especially Linux). This project pins `curl_cffi==0.7.4`
and patches the default TLS fingerprint from `chrome` to `safari` at startup (in `main.py`) to work around this.