> Lucky Man market data API — free US stock/indices data for humans and agents.
> Base URL: https://mcp.luckyman.app
> Auth: none. Rate limit: 60 req/min per IP. Format: JSON. CORS: enabled (all origins).

## Endpoints

- GET /health: overall service status — "healthy" | "degraded" (per-source detail is internal).
- GET /quotes?symbols=AAPL,MSFT: live quotes for up to 50 comma-separated tickers. Returns price, change, change%, day high/low, volume.
- GET /history?symbol=AAPL&range=1mo: daily OHLCV bars. Ranges: 1d 5d 1mo 3mo 6mo 1y 2y 5y 10y ytd max.
- GET /filings?symbol=MSFT: latest SEC EDGAR filings (form type, filing date, accession number, direct EDGAR link).
- GET /options?symbol=AAPL: delayed options chain (nearest or requested expiry, strikes within a band around spot; bid/ask, volume, open interest, IV, greeks).
- GET /xbrl?symbol=AAPL&concept=revenue: SEC XBRL financial concept series (annual 10-K / quarterly 10-Q USD values). Aliases: revenue, net_income, eps, cash, equity, assets, liabilities, operating_income, free_cash_flow.
- GET /indices: live index quotes — SPX, NDX, DJI, VIX, 10Y treasury yield (already a percent yield — server-normalized from CBOE legacy ×100 convention).

## Conventions

- All prices in USD. Periodic data cached ~60s; indices cross-sourced (CBOE with Yahoo fallback + 5-day freshness guard).
- Optional header X-LM-Client identifies callers: "ios", "agent", or "web" — used only for anonymous usage analytics (helps us build agent-attention reports).
- Attribution appreciated: "powered by mcp.luckyman.app". Data upstream: Yahoo Finance, CBOE, SEC EDGAR.

## Response shape — GET /quotes

[
  {
    "symbol": "AAPL",
    "shortName": "Apple Inc.",
    "regularMarketPrice": 336.64,
    "regularMarketChange": -3.78,
    "regularMarketChangePercent": -1.11,
    "regularMarketPreviousClose": 340.42,
    "regularMarketDayHigh": 341.2,
    "regularMarketDayLow": 335.1,
    "regularMarketVolume": 48201300,
    "currency": "USD",
    "exchangeName": "NMS"
  }, ...
]

## Response shape — GET /indices

[ { "symbol": "SPX", "regularMarketPrice": 7811.54, "regularMarketChangePercent": 0.59, ... } ]
Symbols: SPX, NDX (Nasdaq-100), DJI, VIX, "10Y" (percent yield, e.g. 4.328 = 4.328%).

## Ranges for /history

1d 5d 1mo 3mo 6mo 1y 2y 5y 10y ytd max

## Error responses

- 400: missing/invalid params (JSON body has "error" field)
- 404: unknown symbol or route (JSON body has "error" field)
- 429: rate-limited; respect Retry-After header (seconds)
- 207: /health returns partial health when any source is down (body lists per-source status)

## Headers returned on every response

- X-RateLimit-Limit: 60
- X-RateLimit-Remaining: <n>
- X-RateLimit-Reset: <unix ts>
- CORS: Access-Control-Allow-Origin: * (browser agents can call directly)

## Data freshness guarantees

- Quotes: ≤60s cache; indices cross-validated across CBOE (primary, 5-day staleness guard) and Yahoo (fallback).
- History: D1-cached daily bars, refreshed on-demand.
- Filings: live from SEC EDGAR on request.