Unusual Whales API - Fundamentals endpoints
Layer mapping: L2 / L3 only. Seven endpoints across two
controllers (AvFundamentalController and FundamentalController)
serving fundamental data: balance sheets, cash flows, income
statements, earnings history, consolidated financials, technical
indicators, and a generic fundamental snapshot.
Not in MK3 scope. SPY’s fundamentals are irrelevant for the 0DTE hunter; per-ticker fundamentals matter for L2 swing-trade strategies and L3 longer-horizon positioning. Filed for future per cortana-north-star.
1. Endpoint matrix
| # | Path | Controller | Purpose | Layer |
|---|---|---|---|---|
| 1 | GET /api/av-fundamental/balance-sheets/{ticker} | AvFundamental | Quarterly balance sheets | L2 |
| 2 | GET /api/av-fundamental/cash-flows/{ticker} | AvFundamental | Quarterly cash flow statements | L2 |
| 3 | GET /api/av-fundamental/income-statements/{ticker} | AvFundamental | Quarterly income statements | L2 |
| 4 | GET /api/av-fundamental/earnings/{ticker} | AvFundamental | Earnings history + estimates | L2 |
| 5 | GET /api/av-fundamental/financials/{ticker} | AvFundamental | Consolidated financial summary | L2 |
| 6 | GET /api/av-fundamental/technical-indicator/{ticker} | AvFundamental | Technical indicators (RSI / MACD / etc.) | L1 partial |
| 7 | GET /api/fundamental/{ticker} | Fundamental | Consolidated fundamental snapshot (likely overlap with /financials) | L2 |
Naming convention. AvFundamentalController probably wraps
Alpha Vantage fundamental data (UW + Alpha Vantage partnership);
FundamentalController is a separate UW-curated view.
2. Base contract
| Property | Value |
|---|---|
| Base URL | https://api.unusualwhales.com |
| Auth | Authorization: Bearer <token> header |
| Response envelope | { "data": [...] } |
| Status codes | 200, 422, 500 |
| Cadence | Quarterly for financials; daily for technical indicator |
3. The four quarterly fundamental statements
(balance-sheets, cash-flows, income-statements, earnings,
financials)
All path-scoped by {ticker}. Query parameters typically include:
period(quarterlyorannual)limit(number of periods to return)
Response per quarter (varies by statement, but the union):
| Field | Statement |
|---|---|
fiscal_date | All |
period_type | All (quarterly or annual) |
total_assets, total_liabilities, total_equity | Balance sheet |
cash_and_equivalents | Balance sheet |
operating_cashflow, investing_cashflow, financing_cashflow | Cash flow |
free_cashflow | Cash flow |
revenue, gross_profit, operating_income, net_income | Income statement |
eps_basic, eps_diluted | Income statement + earnings |
revenue_estimate, eps_estimate | Earnings (forward) |
actual_eps, actual_revenue | Earnings (past) |
surprise_pct | Earnings (past) |
Use (L2): ranking + fundamental filters in swing-trade strategy.
Combine with uw-api-screener /stocks for “high-quality
high-growth” baskets.
4. GET /api/av-fundamental/technical-indicator/{ticker} (L1 partial)
Technical indicators (RSI, MACD, Bollinger Bands, etc.).
Path: ticker.
Query parameters (inferred):
indicator(rsi,macd,sma,ema,bb,stoch, …)interval(daily,weekly,monthly, possibly intraday)time_period(lookback)
Response per record (inferred): date, value (or per-indicator
field set for multi-output indicators like MACD).
Use (L1 partial): session-start technical context. RSI(14) on SPY, MACD, Bollinger position. Useful as context features, lower- priority than the flow + GEX + tide signals but a viable complement.
Important. Technical indicators on the underlying SPY are background features, not setup triggers. Setup Hunter primary gates remain regime + flow + GEX. TIs modulate confidence; they don’t fire setups.
5. GET /api/fundamental/{ticker} (L2)
Consolidated fundamental snapshot.
Use: likely the lowest-effort fundamental query - one call
returns the most-used metrics. Probably overlaps with
/av-fundamental/financials. Confirm semantic difference on first
fetch.
6. MK3 use
Not in current scope (except potentially /technical-indicator
for SPY).
When L2 / L3 strategies are built:
- L2 swing-trade quality screen: filter
/screener/stocksresults by fundamentals (revenue growth > X%, debt/equity < Y). - L2 earnings playbook: use
/earningshistory to identify tickers with consistent positive surprises and trade their post-earnings drift. - L3 quality basket: hold the top-N quality names long-term.
For L1 SPY hunter, only /technical-indicator is potentially in
scope, and even that is a context feature not a setup trigger.
7. Nautilus integration shape (when L2/L3 lands)
- One-time daily polling Actor:
UWFundamentalsActor. Pulls all five statement endpoints per ticker in the watchlist once daily (or once per earnings cycle). UWTechnicalIndicatorActor: daily refresh of TIs for SPY (and later: per-ticker for L2).
8. Known gaps
- Per-statement schemas inferred - first fetch should catalog fields per statement.
/financialsvs/fundamental/{ticker}overlap - confirm exact semantic difference./technical-indicatorquery parameters undocumented - first fetch must catalog indicators + intervals + time_period semantics.- Alpha Vantage attribution - if AvFundamental is AV-sourced, there may be additional rate-limit or licensing constraints.
9. Source URLs
https://api.unusualwhales.com/docs/operations/PublicApi.AvFundamentalController.balance_sheetshttps://api.unusualwhales.com/docs/operations/PublicApi.AvFundamentalController.cash_flowshttps://api.unusualwhales.com/docs/operations/PublicApi.AvFundamentalController.income_statementshttps://api.unusualwhales.com/docs/operations/PublicApi.AvFundamentalController.earningshttps://api.unusualwhales.com/docs/operations/PublicApi.AvFundamentalController.financialshttps://api.unusualwhales.com/docs/operations/PublicApi.AvFundamentalController.technical_indicatorhttps://api.unusualwhales.com/docs/operations/PublicApi.FundamentalController.show
cortana-north-star uw-api-companies uw-api-screener uw-api-earnings