43 lines
2.3 KiB
Markdown
43 lines
2.3 KiB
Markdown
---
|
|
type: decision
|
|
status: active
|
|
date: 2026-03-18
|
|
agent_author: "claude"
|
|
tags: [data, finnhub, vendor, calendar, insider]
|
|
related_files: [tradingagents/dataflows/interface.py, tradingagents/dataflows/finnhub_scanner.py, tradingagents/agents/utils/scanner_tools.py]
|
|
---
|
|
|
|
## Context
|
|
|
|
Live integration testing of the Finnhub API (2026-03-18) confirmed free-tier availability
|
|
of 6 endpoints. Evaluation identified two high-value unique capabilities (earnings calendar,
|
|
economic calendar) and two equivalent-quality replacements (insider transactions, company profile).
|
|
|
|
## The Decision
|
|
|
|
- Add Finnhub as a third vendor alongside yfinance and Alpha Vantage.
|
|
- `get_insider_transactions` → Finnhub primary (free, same data + MSPR aggregate bonus signal)
|
|
- `get_earnings_calendar` → Finnhub only (new capability, not in AV at any tier)
|
|
- `get_economic_calendar` → Finnhub only (new capability, FOMC/CPI/NFP dates)
|
|
- AV remains primary for news (per-article sentiment scores irreplaceable), market movers (TOP_GAINERS_LOSERS full-market coverage), and financial statements (Finnhub requires paid)
|
|
|
|
## Paid-Tier Endpoints (do NOT use on free key)
|
|
|
|
- `/stock/candle` → HTTP 403 on free tier (use yfinance for OHLCV)
|
|
- `/financials-reported` → HTTP 403 on free tier (use AV for statements)
|
|
- `/indicator` → HTTP 403 on free tier (yfinance/stockstats already primary)
|
|
|
|
## Constraints
|
|
|
|
- `FINNHUB_API_KEY` env var required — `APIKeyInvalidError` raised if missing
|
|
- Free tier rate limit: 60 calls/min — enforced by `_rate_limited_request` in `finnhub_common.py`
|
|
- Calendar endpoints return empty list (not error) when no events exist in range — return formatted "no events" message, do NOT raise
|
|
|
|
## Actionable Rules
|
|
|
|
- Finnhub functions in `route_to_vendor` must raise `FinnhubError` (not return error strings) on total failure
|
|
- `route_to_vendor` fallback catch must include `FinnhubError` alongside `AlphaVantageError`
|
|
- Calendar functions return graceful empty-state strings (not raise) when API returns empty list — this is normal behaviour, not an error
|
|
- Never add Finnhub paid-tier endpoints (`/stock/candle`, `/financials-reported`, `/indicator`) to free-tier routing
|
|
- `get_insider_transactions` is excluded from `FALLBACK_ALLOWED` — Finnhub MSPR aggregate data has no equivalent in other vendors (ADR 011)
|