| name | finance |
| description | Stocks (multi-market index snapshot + daily summary via stock/summary, incl. TASI), funds (six-digit OHLCV vs NAV daily), precious metals (XAUUSD) — pick the matching REST path or MCP tool. |
Finance API — Stocks / Funds / Precious metals (agent-ready)
Taxonomy (same as sidebar)
| Major | Meaning |
|---|
| Stocks | Stock market: multi-market index snapshot (latest) and index daily summary (latest / date / range) — TASI constituent company daily is not supported (use index snapshot instead). |
| Funds | Six-digit daily data in two shapes: exchange daily bars (OHLCV) vs NAV disclosure (unit + daily %). |
| Precious metals | Spot XAUUSD daily OHLCV via GET /api/finance/fund/XAUUSD/ohlcv/daily (canonical; legacy market/daily?symbols=XAUUSD); Turso source=eastmoney-precious-spot. Only XAUUSD in scope today. |
When to use
- Stocks — index snapshot (all overview markets, including TASI) —
GET /api/finance/stock/summary?market=... or batch markets=.... TASI latest index → GET /api/finance/stock/summary?market=TASI (canonical; same as other markets).
- Stocks — index daily summary (all overview markets) —
GET /api/finance/stock/summary/daily?market=.... No date params → latest (same data as /stock/summary); optional date=YYYY-MM-DD (single historical day) or from+to (range, max 365 days → data.items). TASI history from the TASI Turso feed; other markets from finance_stock_summary_daily.
- Stocks — TASI constituents — not supported for latest/full list; use
/api/finance/stock/summary?market=TASI for the index.
- Funds / precious spot — exchange-style daily OHLCV (canonical) —
GET /api/finance/fund/{symbol}/ohlcv/daily?startDate=...&endDate=... ({symbol} six-digit or XAUUSD; optional withIndicators=true adds MACD fields using legacy window cold-start by default; optional indicatorWarmup=true uses 120 calendar days; optional indicatorWarmupDays=35..250 sets the lookback; optional forceSync=true refreshes allowlisted cached ranges). Multi-symbol batch legacy: GET /api/finance/market/daily?symbols=....
- Funds / precious — latest one OHLCV bar —
GET /api/finance/fund/{symbol}/ohlcv/daily/latest (same path shape as market/daily/latest). Legacy: GET /api/finance/market/daily/latest?symbols=....
- Funds — NAV disclosure daily series (canonical) —
GET /api/finance/fund/{symbol}/nav/daily?startDate=...&endDate=.... Legacy: GET /api/finance/fund/nav/daily?symbols=....
- Funds — latest one NAV row —
GET /api/finance/fund/{symbol}/nav/daily/latest. Legacy: GET /api/finance/fund/nav/daily/latest?symbols=....
- Funds — overview
stockList + MACD (latest bar per symbol, not full daily rows): GET /api/finance/overview/stock-list?symbols=...&startDate=...&endDate=... (optional syncIfEmpty).
- Do not use exchange
market= feed paths for non-TASI markets — they return 400; use /api/finance/stock/summary for other overview indices.
Hard boundaries (must check before call)
- TASI company list / latest constituents — not available. Use
GET /api/finance/stock/summary?market=TASI or MCP get_stock_summary.
- On
/api/finance/stock/summary/daily, non-TASI markets return historical rows only for dates the daily ingest has written (finance_stock_summary_daily); missing days come back as null (single) or are absent from items (range), not an error.
- Do not mix fund NAV and exchange OHLCV tools: NAV symbols/routes use
get_fund_nav_daily*, while OHLCV uses get_market_daily*.
- Current precious metals scope is XAUUSD only; do not imply support for other metals unless route/tool exists.
Pre-check (before tool call)
- Classify intent first: stock index latest snapshot vs stock index daily summary (date/range) vs fund NAV vs fund OHLCV vs precious metal.
- For TASI index latest →
get_stock_summary / /api/finance/stock/summary?market=TASI.
- For TASI company list → explain unsupported; offer index snapshot instead.
- Validate symbol/date requirements per endpoint mode before calling.
- For non-TASI index needs, route to
get_stock_summary directly.
Fallback (when not suitable)
- If symbol/market mapping is ambiguous, ask user to confirm instrument and market once.
- If request falls outside current scope (e.g. non-XAUUSD precious), explain unsupported scope and avoid fabricating output.
Retry policy
- Retry only on transient 5xx failures or temporary upstream sync gaps.
- Do not retry unchanged validation/mode mismatch errors (400) until parameters or route are corrected.
Multi-turn / Missing parameters
- Parse first:
market, date, from/to, code from natural language; dates YYYY-MM-DD.
- Index range summary: requires
from and to together. If only one date is given, treat it as date (single day) or ask for the range.
Parameters (canonical REST)
Stocks — index snapshot (all overview markets, including TASI)
GET /api/finance/stock/summary
| Mode | Query |
|---|
| Single | market=TASI (default) or market=S%26P%20500, Dow%20Jones, Nasdaq, … |
| Batch | markets=TASI,S%26P%20500,Dow%20Jones (comma-separated; same per-market cold-start as single) |
HTTP 200 body: { "code": 0, "message": "ok", "data": … } — single: data: { "market", "summary" }; batch: data: { "items": [...] }.
Stocks — index daily summary (all overview markets)
GET /api/finance/stock/summary/daily — one market per request via market= (default TASI).
| Mode | Query |
|---|
| Latest | market=TASI (default) — same data as /stock/summary |
| Single day | market=... date=YYYY-MM-DD |
| Range | market=... from=YYYY-MM-DD to=YYYY-MM-DD (max 365 days) |
HTTP 200 body: latest / single day → data: { "market", "summary" }; range → data: { "market", "items": [...] }. Do not send date together with from/to.
Steps
- Conversation cache: Same full URL already returned HTTP 200 with usable
data → reuse.
- Choose path: stocks latest snapshot (incl. TASI) → stock/summary; stocks historical / range summary → stock/summary/daily (
date or from+to); funds → fund/…/ohlcv vs fund/…/nav vs overview/stock-list.
- Validate required query parts for that mode.
- GET only (no body).
- Check HTTP then envelope
{ code, message, data } on 200.
- Summarize from
data — never invent numbers.
Request examples
GET /api/finance/stock/summary?market=TASI
GET /api/finance/stock/summary?market=Nasdaq
GET /api/finance/stock/summary/daily?market=TASI&date=2026-03-01
GET /api/finance/stock/summary/daily?market=TASI&from=2026-01-01&to=2026-03-01
MCP / function calling (same tool names as POST /api/mcp/finance)
Primary tools
| Tool | Role |
|---|
get_stock_summary | Latest index snapshot for all markets: market or markets (comma-separated). Same as GET /api/finance/stock/summary. |
get_stock_summary_daily | Daily index summary for one market: omit date/from/to for latest; optional date or from+to (max 365 days). Same as GET /api/finance/stock/summary/daily. |
get_market_daily | Exchange OHLCV only: symbols, startDate, endDate; optional withIndicators, indicatorWarmup, indicatorWarmupDays; optional syncIfEmpty (default true), optional forceSync. Fund NAV codes → get_fund_nav_daily. |
get_market_daily_latest | Latest one OHLCV bar per symbol: symbols only; optional withIndicators (default true); optional syncIfEmpty (default true). Returns { asOf, items, synced }. |
get_fund_nav_daily | Fund NAV only: same symbols / dates; optional syncIfEmpty (default true). Returns { items, synced } with unitNav + dailyChangePercent. |
get_fund_nav_daily_latest | Latest one NAV row per symbol: symbols only; optional syncIfEmpty (default true). Returns { asOf, items, synced }. |
get_overview_stock_list | Same date range + symbols; optional syncIfEmpty. Returns { stockList, synced } — one row per symbol (latest bar + MACD streak), not the full daily series (get_market_daily). |
Removed MCP tools
get_market_company_daily and get_market_company_daily_latest are unregistered. TASI constituents are not supported — use get_stock_summary for index data.
Known limitations & follow-up
- Latest
summary.date vs calendar today: Index markets return the last available trading session (e.g. TASI on weekends shows the prior Thursday). This is upstream session data, not a stale cache bug.
- Non-TASI historical range: Rows come from
finance_stock_summary_daily, populated only on finance-fmp-sync cron days. Range queries return sparse items until a backfill job is added.
- TASI historical range: Full ~1y history from the TASI Turso feed via
get_stock_summary_daily / GET /api/finance/stock/summary/daily.
- Legacy REST/MCP aliases: Old slug paths (
/api/finance/stock/tasi/summary/daily, get_market_summary_daily*) remain registered for migration; prefer /api/finance/stock/summary/daily and get_stock_summary_daily.
Response
Same envelope: { code: 0, message: "ok", data: … }. data may be [] or null on 200 — treat as no rows, not a transport error.
/api/finance/stock/summary: data is { market, summary } (single) or { items } (batch), not a bare ok flag. Use for TASI latest index./api/finance/fund/{symbol}/ohlcv/daily and legacy /api/finance/market/daily: data is { items, synced } with exchange OHLCV rows only (items[].open … turnoverRate; when withIndicators=true, ema12/ema26/dif/dea/macd plus macdUp/macdDown)./api/finance/fund/{symbol}/ohlcv/daily/latest and legacy /api/finance/market/daily/latest: data is { asOf, items, synced } — one latest bar; asOf is ISO-8601; items[].date is the bar’s calendar trade date./api/finance/fund/{symbol}/nav/daily and legacy /api/finance/fund/nav/daily: data is { items, synced } with fund NAV rows (items[].unitNav, items[].dailyChangePercent only)./api/finance/fund/{symbol}/nav/daily/latest and legacy /api/finance/fund/nav/daily/latest: data is { asOf, items, synced }./api/finance/stock/summary/daily: latest / single day → data is { market, summary }; range (from+to) → data is { market, items }. summary/items may be null/[] on 200 when no row exists for that date.
Examples
- User: “TASI summary today” →
GET /api/finance/stock/summary?market=TASI.
- User: “Nasdaq summary today” →
GET /api/finance/stock/summary?market=Nasdaq.
- User: “TASI index daily Jan–Mar 2026” →
GET /api/finance/stock/summary/daily?market=TASI&from=2026-01-01&to=2026-03-01 or MCP get_stock_summary_daily with the same params.
- User: “TASI all companies today” → explain constituents not supported; offer
GET /api/finance/stock/summary?market=TASI for index snapshot.
Agent rules
GET only; if TASI company feed path returns 400, read message and use /api/finance/stock/summary?market=TASI for index data.
