---
name: invest-api
description: "Investment analysis via OpenBB Invest API (99 endpoints). Use when: user asks about stocks, ETFs, crypto, portfolio analysis, technical indicators (14 types), quantitative risk metrics, fixed income/yield curve, macro economics, shorts/dark pool, regulators/COT, economy surveys, or investment advice. Covers US and Swedish markets. NOT for: real-time trading, order execution, or account management. No API key needed for most endpoints."
homepage: https://invest-api.k8s.home/docs
metadata: { "openclaw": { "emoji": "📈", "requires": { "bins": ["curl"] } } }
---

# Investment Analysis Skill

Query stock data, run portfolio analysis, and get investment insights via the OpenBB Invest API. 99 endpoints across 14 data providers.

## When to Use

- "What's AAPL trading at?"
- "Analyze my portfolio" / "Should I buy or sell?"
- "Show me technical indicators for TSLA" / "What's the Ichimoku cloud for NVDA?"
- "What are the top gainers today?"
- "Any upcoming earnings this week?"
- "What's the macro outlook?" / "What's the yield curve look like?"
- "How risky is my VOLV-B.ST position?" / "What's the Sortino ratio?"
- "Is anyone shorting AAPL?" / "Show dark pool activity"
- "What are the latest FOMC documents?"
- "Where are gold futures positioned?" (COT data)
- "Compare AAPL, MSFT, GOOGL sector rotation vs SPY"

## When NOT to Use

- Placing trades or managing brokerage accounts
- Real-time tick-by-tick data (this API has request latency)
- Cryptocurrency on-chain analysis
- Tax or accounting advice

## API Base URL

```
BASE=https://invest-api.k8s.home
```

All responses follow `{"success": true, "data": {...}, "error": null}`.

## Stock Data (no key needed)

```bash
# Current quote
curl -sk "$BASE/api/v1/stock/AAPL/quote"

# Company profile (sector, industry, description)
curl -sk "$BASE/api/v1/stock/AAPL/profile"

# Key ratios (PE, PB, ROE, EPS, beta, dividend yield)
curl -sk "$BASE/api/v1/stock/AAPL/metrics"

# Financial statements (income, balance sheet, cash flow)
curl -sk "$BASE/api/v1/stock/AAPL/financials"

# Historical prices (OHLCV)
curl -sk "$BASE/api/v1/stock/AAPL/historical?days=365"

# Recent news
curl -sk "$BASE/api/v1/stock/AAPL/news"

# All-in-one summary (quote + profile + metrics + financials)
curl -sk "$BASE/api/v1/stock/AAPL/summary"

# Executive team and compensation
curl -sk "$BASE/api/v1/stock/AAPL/management"

# Historical dividend records
curl -sk "$BASE/api/v1/stock/AAPL/dividends"

# SEC filings (10-K, 10-Q, 8-K)
curl -sk "$BASE/api/v1/stock/AAPL/filings?form_type=10-K"

# Company search by name
curl -sk "$BASE/api/v1/search?query=apple"
```

## Swedish Stocks

Append `.ST` suffix for Stockholm exchange:

```bash
curl -sk "$BASE/api/v1/stock/VOLV-B.ST/quote"    # Volvo
curl -sk "$BASE/api/v1/stock/ERIC-B.ST/quote"     # Ericsson
curl -sk "$BASE/api/v1/stock/HM-B.ST/quote"       # H&M
curl -sk "$BASE/api/v1/stock/SEB-A.ST/quote"      # SEB
```

## Portfolio Analysis

Provide holdings with buy-in cost. Returns BUY_MORE / HOLD / SELL recommendation per holding with confidence and reasons.

```bash
curl -sk -X POST "$BASE/api/v1/portfolio/analyze" \
  -H "Content-Type: application/json" \
  -d '{
    "holdings": [
      {"symbol": "AAPL", "shares": 100, "buy_in_price": 150.0},
      {"symbol": "VOLV-B.ST", "shares": 50, "buy_in_price": 250.0},
      {"symbol": "MSFT", "shares": 30, "buy_in_price": 380.0}
    ]
  }'
```

Max 50 holdings per request.

## Technical Analysis (14 indicators)

```bash
# Composite: RSI, MACD, SMA, EMA, Bollinger Bands + signal interpretation
curl -sk "$BASE/api/v1/stock/AAPL/technical"

# Individual indicators
curl -sk "$BASE/api/v1/stock/AAPL/technical/atr"         # Average True Range (volatility)
curl -sk "$BASE/api/v1/stock/AAPL/technical/adx"         # Trend strength (>25 strong)
curl -sk "$BASE/api/v1/stock/AAPL/technical/stoch"       # Stochastic (overbought/oversold)
curl -sk "$BASE/api/v1/stock/AAPL/technical/obv"         # On-Balance Volume
curl -sk "$BASE/api/v1/stock/AAPL/technical/ichimoku"    # Ichimoku Cloud
curl -sk "$BASE/api/v1/stock/AAPL/technical/donchian"    # Donchian Channels (breakouts)
curl -sk "$BASE/api/v1/stock/AAPL/technical/aroon"       # Aroon (trend direction)
curl -sk "$BASE/api/v1/stock/AAPL/technical/cci"         # Commodity Channel Index
curl -sk "$BASE/api/v1/stock/AAPL/technical/kc"          # Keltner Channels
curl -sk "$BASE/api/v1/stock/AAPL/technical/fib"         # Fibonacci Retracement
curl -sk "$BASE/api/v1/stock/AAPL/technical/ad"          # Accumulation/Distribution
curl -sk "$BASE/api/v1/stock/AAPL/technical/cones"       # Volatility Cones
curl -sk "$BASE/api/v1/stock/AAPL/technical/vwap"        # Volume Weighted Average Price

# Relative Rotation Graph (multi-symbol sector rotation)
curl -sk "$BASE/api/v1/technical/relative-rotation?symbols=AAPL,MSFT,GOOGL&benchmark=SPY"
# Returns quadrant per symbol: Leading / Weakening / Lagging / Improving
```

## Quantitative Risk Metrics

```bash
# Sharpe ratio, volatility, summary statistics
curl -sk "$BASE/api/v1/stock/AAPL/performance?days=365"

# CAPM: market risk, systematic risk, idiosyncratic risk
curl -sk "$BASE/api/v1/stock/AAPL/capm"

# Sortino ratio (downside risk only -- better than Sharpe for asymmetric returns)
curl -sk "$BASE/api/v1/stock/AAPL/sortino?days=365"

# Omega ratio (full distribution gain/loss)
curl -sk "$BASE/api/v1/stock/AAPL/omega?days=365"

# Normality tests (Jarque-Bera, Shapiro-Wilk)
curl -sk "$BASE/api/v1/stock/AAPL/normality?days=365"

# Unit root / stationarity tests (ADF, KPSS)
curl -sk "$BASE/api/v1/stock/AAPL/unitroot?days=365"

# Rolling statistics (variance, stdev, mean, skew, kurtosis, quantile)
curl -sk "$BASE/api/v1/stock/AAPL/rolling/skew?days=365&window=30"
curl -sk "$BASE/api/v1/stock/AAPL/rolling/variance?days=365&window=20"
```

## Shorts & Dark Pool (no key needed)

```bash
# Daily short volume and percent
curl -sk "$BASE/api/v1/stock/AAPL/shorts/volume"

# Fails-to-deliver records (SEC)
curl -sk "$BASE/api/v1/stock/AAPL/shorts/ftd"

# Short interest, days to cover (FINRA)
curl -sk "$BASE/api/v1/stock/AAPL/shorts/interest"

# Dark pool / OTC trade volume (FINRA)
curl -sk "$BASE/api/v1/darkpool/AAPL/otc"
```

## Sentiment & Analyst Data

```bash
# Aggregated sentiment (news + recommendations + upgrades)
curl -sk "$BASE/api/v1/stock/AAPL/sentiment"

# Per-article news sentiment scores
curl -sk "$BASE/api/v1/stock/AAPL/news-sentiment?limit=30"

# Insider trades (SEC/Finnhub)
curl -sk "$BASE/api/v1/stock/AAPL/insider-trades"

# Analyst buy/hold/sell counts
curl -sk "$BASE/api/v1/stock/AAPL/recommendations"

# Recent upgrades/downgrades with price targets
curl -sk "$BASE/api/v1/stock/AAPL/upgrades"
```

## Fixed Income (FRED/Federal Reserve)

```bash
# Full yield curve rates (4W-30Y)
curl -sk "$BASE/api/v1/fixed-income/treasury-rates"

# Yield curve with maturity/rate pairs (optional date)
curl -sk "$BASE/api/v1/fixed-income/yield-curve"
curl -sk "$BASE/api/v1/fixed-income/yield-curve?date=2025-01-15"

# Treasury auction data (bid-to-cover, yields)
curl -sk "$BASE/api/v1/fixed-income/treasury-auctions"

# TIPS real yields
curl -sk "$BASE/api/v1/fixed-income/tips-yields"

# Effective Federal Funds Rate (with percentiles)
curl -sk "$BASE/api/v1/fixed-income/effr"

# SOFR rate (with moving averages)
curl -sk "$BASE/api/v1/fixed-income/sofr"

# Corporate bond yields (AAA/AA/A)
curl -sk "$BASE/api/v1/fixed-income/hqm"

# Commercial paper rates
curl -sk "$BASE/api/v1/fixed-income/commercial-paper"

# Corporate bond spot rates
curl -sk "$BASE/api/v1/fixed-income/spot-rates"

# Treasury/corporate spreads
curl -sk "$BASE/api/v1/fixed-income/spreads?series=tcm"
```

## Macro Economics

```bash
# Key indicators: Fed rate, treasury yields, CPI, unemployment, GDP, VIX
curl -sk "$BASE/api/v1/macro/overview"

# Any FRED time series by ID
curl -sk "$BASE/api/v1/macro/series/DFF?limit=30"        # Fed Funds Rate
curl -sk "$BASE/api/v1/macro/series/CPIAUCSL?limit=12"   # CPI

# Structured macro data (multi-country support)
curl -sk "$BASE/api/v1/macro/cpi?country=united_states"
curl -sk "$BASE/api/v1/macro/gdp?gdp_type=real"
curl -sk "$BASE/api/v1/macro/unemployment?country=united_states"
curl -sk "$BASE/api/v1/macro/pce"                                   # Fed preferred inflation
curl -sk "$BASE/api/v1/macro/money-measures"                        # M1/M2 money supply
curl -sk "$BASE/api/v1/macro/cli?country=united_states"             # Leading indicator
curl -sk "$BASE/api/v1/macro/house-price-index?country=united_states"
```

## Economy Data & Surveys

```bash
# Search 800K+ FRED economic series
curl -sk "$BASE/api/v1/economy/fred-search?query=inflation"

# Regional economic data (by state/county)
curl -sk "$BASE/api/v1/economy/fred-regional?series_id=UNRATE"

# Fed balance sheet / SOMA portfolio
curl -sk "$BASE/api/v1/economy/central-bank-holdings"

# Primary dealer positions (Wall Street firm positioning)
curl -sk "$BASE/api/v1/economy/primary-dealer-positioning"

# Balance of payments
curl -sk "$BASE/api/v1/economy/balance-of-payments"

# FOMC meeting documents
curl -sk "$BASE/api/v1/economy/fomc-documents?year=2026"

# Consumer sentiment (recession predictor)
curl -sk "$BASE/api/v1/economy/surveys/michigan"

# Senior Loan Officer Survey (strongest recession signal)
curl -sk "$BASE/api/v1/economy/surveys/sloos"

# Detailed employment data
curl -sk "$BASE/api/v1/economy/surveys/nonfarm-payrolls"

# NY manufacturing outlook
curl -sk "$BASE/api/v1/economy/surveys/empire-state"

# BLS data search
curl -sk "$BASE/api/v1/economy/surveys/bls-search?query=wages"
```

## Market Data

```bash
# ETF
curl -sk "$BASE/api/v1/etf/SPY/info"
curl -sk "$BASE/api/v1/etf/SPY/historical?days=365"
curl -sk "$BASE/api/v1/etf/SPY/nport"                        # Detailed N-PORT holdings
curl -sk "$BASE/api/v1/etf/search?query=technology"

# Index
curl -sk "$BASE/api/v1/index/available"
curl -sk "$BASE/api/v1/index/%5EGSPC/historical?days=365"     # S&P 500
curl -sk "$BASE/api/v1/index/sp500-multiples?series=pe_ratio" # Historical S&P 500 valuation
curl -sk "$BASE/api/v1/index/%5EGSPC/constituents"            # Index member stocks

# Crypto
curl -sk "$BASE/api/v1/crypto/BTC-USD/historical?days=30"
curl -sk "$BASE/api/v1/crypto/search?query=bitcoin"

# Forex
curl -sk "$BASE/api/v1/currency/USDSEK/historical?days=365"
curl -sk "$BASE/api/v1/currency/reference-rates"              # ECB rates (28 currencies)

# Options
curl -sk "$BASE/api/v1/options/AAPL/chains"

# Futures
curl -sk "$BASE/api/v1/futures/CL=F/historical?days=365"
curl -sk "$BASE/api/v1/futures/CL=F/curve"
```

## Regulators (no key needed)

```bash
# Commitment of Traders (futures positions)
curl -sk "$BASE/api/v1/regulators/cot?symbol=GC=F"
curl -sk "$BASE/api/v1/regulators/cot/search?query=gold"

# SEC litigation releases
curl -sk "$BASE/api/v1/regulators/sec/litigation"

# Search institutional investors
curl -sk "$BASE/api/v1/regulators/sec/institutions?query=berkshire"

# Ticker to CIK mapping
curl -sk "$BASE/api/v1/regulators/sec/cik-map/AAPL"
```

## Calendar Events

```bash
curl -sk "$BASE/api/v1/calendar/earnings?start_date=2026-03-10&end_date=2026-03-17"
curl -sk "$BASE/api/v1/calendar/dividends?start_date=2026-03-10&end_date=2026-03-17"
curl -sk "$BASE/api/v1/calendar/ipo?start_date=2026-03-01&end_date=2026-03-31"
curl -sk "$BASE/api/v1/calendar/splits?start_date=2026-03-01&end_date=2026-03-31"
```

## Stock Discovery

```bash
curl -sk "$BASE/api/v1/discover/gainers"        # Top gainers
curl -sk "$BASE/api/v1/discover/losers"         # Top losers
curl -sk "$BASE/api/v1/discover/active"         # Most active
curl -sk "$BASE/api/v1/discover/undervalued"    # Undervalued large caps
curl -sk "$BASE/api/v1/discover/growth"         # Growth tech stocks
```

## Estimates & Ownership

```bash
curl -sk "$BASE/api/v1/stock/AAPL/estimates"           # Analyst consensus
curl -sk "$BASE/api/v1/stock/AAPL/share-statistics"    # Float, short interest
curl -sk "$BASE/api/v1/stock/AAPL/sec-insider"         # SEC Form 4
curl -sk "$BASE/api/v1/stock/AAPL/institutional"       # 13F institutional holders
curl -sk "$BASE/api/v1/screener"                       # Stock screener
```

## Recommended Workflows

### Comprehensive Stock Analysis
1. `/stock/{symbol}/summary` -- fundamentals overview
2. `/stock/{symbol}/technical` -- composite technical signals
3. `/stock/{symbol}/technical/ichimoku` -- trend system
4. `/stock/{symbol}/performance` -- Sharpe, volatility
5. `/stock/{symbol}/sortino` -- downside risk
6. `/stock/{symbol}/shorts/volume` -- short selling pressure
7. `/stock/{symbol}/sentiment` -- market sentiment
8. `/stock/{symbol}/sec-insider` -- insider activity
9. `/stock/{symbol}/upgrades` -- analyst actions + price targets
10. `/macro/overview` -- market context
11. `/portfolio/analyze` -- rule-engine recommendation

### Macro & Fixed Income Analysis
1. `/macro/overview` -- headline indicators
2. `/fixed-income/yield-curve` -- rate environment
3. `/fixed-income/effr` -- Fed funds rate detail
4. `/macro/cpi` -- inflation
5. `/macro/pce` -- Fed preferred inflation
6. `/macro/money-measures` -- M1/M2 money supply
7. `/economy/surveys/michigan` -- consumer confidence
8. `/economy/surveys/sloos` -- lending conditions
9. `/macro/cli` -- leading indicator (recession risk)

### Sector Rotation Analysis
1. `/technical/relative-rotation?symbols=XLK,XLF,XLE,XLV&benchmark=SPY` -- RRG quadrants
2. `/index/sp500-multiples?series=shiller_pe_ratio` -- market valuation context
3. `/discover/gainers` + `/discover/losers` -- daily movers

### Short Squeeze Screening
1. `/stock/{symbol}/shorts/volume` -- short volume %
2. `/stock/{symbol}/shorts/interest` -- days to cover
3. `/stock/{symbol}/shorts/ftd` -- fails to deliver
4. `/darkpool/{symbol}/otc` -- dark pool activity
5. `/stock/{symbol}/share-statistics` -- float, short % of float

Synthesize all data into a coherent recommendation. The API provides structured data only -- all reasoning and natural language analysis should be done by the LLM.

## Notes

- Prices are delayed (not real-time); yfinance data is typically 15-20 min delayed
- Swedish stocks use `.ST` suffix (Stockholm exchange)
- Portfolio analysis uses a rule engine (PE, revenue growth, P&L, analyst targets) returning BUY_MORE/HOLD/SELL
- The `-k` flag is needed because the API uses a self-signed TLS certificate
- Multi-country support for CPI, GDP, unemployment, CLI, HPI (use `country=united_states`, `country=japan`, etc.)
- Health check: `curl -sk "$BASE/health"`