A read-only HTTP, WebSocket, and MCP interface over a 2.77 TB financial dataset — symbols, OHLC bars, fundamentals, short interest, SEC filings, news with sentiment, ownership, regulatory, macro, BTC options, plus a 34.8 M-row KOL tweet archive with 11.5 M mirrored images. Refreshed continuously, streamed live.
Every endpoint is a plain GET that returns JSON. A Lumid PAT is
required — pass it as Authorization: Bearer <pat>.
Anonymous requests get 401. Every response carries your current
budget in the x-ratelimit-limit / -remaining /
-reset headers — read those rather than assuming a number,
the tier differs per deployment.
curl https://lum.id/findata/symbols/AAPL
1d, 7 d for 5min, 1 d for 1min.curl "https://lum.id/findata/ohlc/AAPL?interval=1d"
curl "https://lum.id/findata/quotes?symbols=AAPL,BTCUSD"
websocat -H="Authorization: Bearer $TOKEN" \ wss://lum.id/findata/ws/quotes
curl "https://lum.id/findata/screener?sector=Technology&market_cap_min=1e12"
curl "https://lum.id/findata/kols/tweets/search?q=earnings+beat"
curl "https://lum.id/findata/news/latest?category=general&limit=20"
by-url falls through to pbs.twimg.com if not cached.curl -L "https://lum.id/findata/kols/media/by-url?u=<twitter-cdn-url>"
Endpoints are grouped by data domain. Open any group in the OpenAPI spec or the guide for schemas and example payloads.
SSE /prediction-markets/stream.expiry, strike, otype (C/P), and price = option premium. Bars compute open/high/low/close from the observations; volume_traded is the vendor's (the observations carry no trade size). Empty buckets are omitted, not filled. 8.76M observations (2025-08 → 2026-07). Filter by otype / strike / expiry / time window./kols/media/.
Streams over the same hub: tick prices, news articles, KOL tweets.
Both WSS /ws/quotes (bidirectional, subscribe-by-symbol) and
GET /quotes/stream (SSE) are supported; WSS /ws/news
is a news-only variant. Authentication via Lumid PAT (or X-API-Key).
| Stream | Transport | Source tier |
|---|---|---|
| tick:<sym> | /ws/quotes • /quotes/stream | A — WS feed for US equities + crypto / forex. Multiple sources: crypto & forex run a primary + hot-standby WSS pair; US equities additionally have a secondary quote feed that auto-covers within seconds if the primary goes quiet. No manual intervention needed on any gap. |
| news:<sym> | /ws/news | B — news firehose poller (60 s) |
| pm:events | /prediction-markets/stream (SSE) | A — 1st-hand Polymarket CLOB WSS (~240 active markets) |
| last:tick:<sym> | /quotes?symbols=… | C — Tier-C Redis snapshot, evictable on memory pressure |
Tier and lag are exposed live at GET /freshness
(green/amber/red/gray per-endpoint SLA counts).
Routes are PAT-authenticated — an invalid token returns
401 (anonymous requests ride an anon-read tier). Auth goes through Lumid identity introspection;
bring a Lumid PAT (lm_pat_live_… / rm_pat_live_…)
or an RS256 JWT. Your per-minute budget comes back on every response in
x-ratelimit-limit / -remaining / -reset.
# Bring your Lumid PAT (lm_pat_live_… / rm_pat_live_…) or JWT. curl -H "Authorization: Bearer $LUMID_TOKEN" \ https://lum.id/findata/symbols/AAPL # Or via X-API-Key header — same effect. curl -H "X-API-Key: $LUMID_TOKEN" \ "https://lum.id/findata/quotes?symbols=AAPL"
Most warehouse queries are also a Model Context Protocol tool, so an agent
can pull fundamentals, holdings, filings, or the KOL archive without
learning a separate HTTP shape. 90 tools, generated from the same
endpoint definitions the HTTP API is built from — so the tool list is
never out of date. Call tools/list for the authoritative set.
# Streamable-HTTP transport (MCP 2025-03-26, recommended): curl -X POST https://lum.id/findata/mcp \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
Tool names are <group>_<endpoint>. The groups, with one
example each:
fundamentals_latest,
estimates_price_target,
valuation_dcf,
analysis_key_metrics,
technical_indicators,
earnings_calendar,
transcripts_one,
events_ipos,
corpactions_dividends,
news_search,
kols_tweets_search,
prediction-markets_trades_kalshi,
investors_insider_transactions,
institutional_holder_analytics,
gov_trades_for_symbol,
etf_info,
reference_executives,
macro_treasury_rates,
regulatory_filings,
marketextras_market_movers.
Not on MCP: symbols/universe/screener, OHLC bars, realtime quotes and streams, the catalog, and the ingress write surface are HTTP-only. They are high-cardinality or streaming shapes that don't fit a tool call — use the REST routes above for those.
The read API is paired with an ingress surface. Partners and agents
push data with a Lumid PAT (per-role allowlist); the server stamps
provenance and exposes the lineage chain back at
/catalog/lineage/*.
Discover what you may write with
GET /catalog/ingress/writable,
and the exact column shape of a target with
GET /catalog/tables/{schema}/{table}/schema.json.
| Mode | Endpoint | When |
|---|---|---|
| Typed | POST /ingest/{schema}/{table} |
JSON body with records in target-column shape. Idempotent. |
| Stream | POST /ingest/{schema}/{table}/stream |
NDJSON, chunked transfer; one run row spans the whole stream. Gzip/zstd accepted. |
| File | POST /ingest/{schema}/{table}/file |
Multipart upload — JSON / NDJSON / CSV / TSV / XML / YAML / Parquet / Arrow. |
| Blob | POST /ingest/blob |
Images / PDFs / opaque binary. sha256 dedup; bytes land in sibling object storage, metadata in raw.blobs. |
| Webhook | POST /webhook/{webhook_id} |
HMAC-SHA256 signed, no PAT. Provisioned by the operator (ask for one); rate-limited per webhook. |
Writing to a table you don't yet have on the allowlist starts with an
ingress proposal — the schema change is reviewed, not applied
ad hoc (/catalog/ingress/proposals). The ingress routes are
deliberately absent from the OpenAPI spec: they are operator-gated,
not self-serve. Ask before you build against them.
| Source | Cadence |
|---|---|
| Realtime tick stream | Continuous — WS feed across asset classes (stocks, crypto, forex, indices) + secondary quote feed with live 1-min OHLC aggregation as a backup layer |
| Prediction-markets trades + orderbook | Continuous WSS recorder; live trade prints + L2 deltas land in <1 s |
| Kalshi trades (incremental) | Every 30 min |
| Non-stock 1-min OHLC | Every 30 minutes (etf / crypto / forex / index / commodity) |
| Stock 1-min OHLC | Daily at 04:30 UTC (primary feed lags ~3 days) + real-time secondary feed writes live bars continuously |
| Stock daily-adjusted EOD | Daily at 05:15 UTC (dividend + non-split adjusted) |
| Analyst estimates | Every 4 hours — grades, price-target, recommendation, ratings |
| Fundamentals statements | Daily at 06:00 UTC — income / balance / cashflow + ratios + key-metrics + scores + earnings + growth + enterprise-values |
| Ownership (13F + insider + gov-trades) | Daily at 07:00 UTC |
| Events + macro | Daily at 07:30 UTC — earnings calendar, IPOs, treasury rates, economic indicators, COT, FDA |
| Market metadata | Daily at 08:00 UTC — dividends, splits, market_cap |
| Social + news sentiment | Daily at 09:00 UTC |
| Reference (profile, executives, ETF metadata) | Weekly Sun 03:00 UTC + ETF holdings refresh |
| Regulatory (ESG, SEC filings, patents, lobbying) | Weekly Sun 04:30 UTC |
| News articles (6 sources) | Every 15 min — company-news, general, stock, crypto, forex, press releases + sentiment-enhanced feed every 4 h (structured per-ticker sentiment) |
| Short interest + short volume | Weekly Sun 03:00 UTC — FINRA bi-weekly short interest + daily off-exchange short volume |
| Risk factors + 10-K sections | Weekly Sun 05:00 UTC — machine-readable SEC risk-factor taxonomy + plain-text 10-K sections |
| Fundamentals (secondary source) | Weekly Sun 07:00 UTC — income / balance / cash-flow (second provider, for cross-validation) |
| KOL tweets | 3h / 12h / 24h tiers by tweet frequency (3,846-handle roster) |
| News firehose → SSE | Polled every 60 s — event-driven WS fan-out |
| Times | UTC ISO-8601. Dates are YYYY-MM-DD. |
| Symbols | Upper-cased server-side. Crypto / forex use the upstream shape (e.g. BTCUSD, EURUSD). |
| Lineage | The fields source, source_endpoint, source_run_id, ingest_ts, raw are intentionally stripped from responses. The API picks the canonical provider per surface. |
| Errors | JSON {"detail": "…"} on 4xx / 5xx. 429 carries a Retry-After header. |
| Pagination | Endpoints that return lists accept limit (max 1000) and offset; /ohlc uses a server-side row cap instead. |
| Failure mode | Lumid unreachable while validating a presented token → 503 fail-closed. |
Every endpoint is an authenticated GET returning JSON, so anything that can
set an Authorization header can query the warehouse directly
— no SDK, no export step. There is also a read-only Postgres wire
endpoint (below) for tools that would rather speak SQL than HTTP. Two response shapes, so check once per
endpoint: most list routes (/news/*, /kols/*,
/prediction-markets/trades/*) return a bare JSON array of
rows; a few wrap the rows in an envelope alongside a count
(/ohlc → bars, /screener →
hits). Unwrap that key and you have a table.
curl -O https://lum.id/findata/sql-ca.pem
psql "host=sql.lum.id port=5432 dbname=findata user=lumid_reader \
sslmode=verify-full sslrootcert=sql-ca.pem"
Use verify-full, not require — require
encrypts but accepts any certificate, so it does not stop an active
man-in-the-middle. The CA above is the one that signs this endpoint, published
over lum.id’s own TLS, and that is what anchors the trust. Credentials are
issued per requester — ask for the password.
22 schemas, ~9990 tables. The session is read-only, capped at a two-minute
statement_timeout and 40 shared connections, and refuses plaintext
outright. market carries the OHLC hypertables
(ohlc_1min, ohlc_5min, ohlc_daily);
prediction_markets carries 34 tables of Polymarket and Kalshi
markets, trades, per-interval candles, orderbook snapshots and wallet analytics;
then fundamentals, news, macro,
estimates, ownership, reference,
instrument, events, regulatory,
md.
SELECT symbol, date, close, volume FROM market.ohlc_daily WHERE symbol = 'AAPL' ORDER BY date DESC LIMIT 5; -- DuckDB can attach it directly, too. INSTALL postgres; LOAD postgres; ATTACH 'host=sql.lum.id port=5432 dbname=findata user=lumid_reader password=... sslmode=verify-full sslrootcert=sql-ca.pem' AS fd (TYPE postgres, READ_ONLY);
httpfs fetches, DuckDB does the SQL.INSTALL httpfs; LOAD httpfs; -- Attach your PAT once per session. CREATE SECRET findata ( TYPE http, EXTRA_HTTP_HEADERS MAP {'Authorization': 'Bearer ' || getenv('LUMID_TOKEN')} ); -- Envelope route: unwrap the `bars` key to get one row per bar. SELECT unnest(bars) AS b FROM read_json_auto('https://lum.id/findata/ohlc/AAPL?interval=1d'); -- Bare-array route: already one row per record, no unnest. SELECT published_at, publisher, headline FROM read_json_auto('https://lum.id/findata/news/search?q=guidance+cut&limit=500'); -- Join two endpoints in one query. WITH tech AS ( SELECT unnest(hits) AS h FROM read_json_auto('https://lum.id/findata/screener?sector=Technology&limit=50') ) SELECT h.symbol, h.market_cap FROM tech ORDER BY h.market_cap DESC;
import os, requests, pandas as pd S = requests.Session() S.headers["Authorization"] = f"Bearer {os.environ['LUMID_TOKEN']}" BASE = "https://lum.id/findata" def table(path, key=None, **params): r = S.get(f"{BASE}{path}", params=params, timeout=60) r.raise_for_status() body = r.json() # bare array, or an envelope whose rows live under `key` return pd.DataFrame(body if key is None else body[key]) bars = table("/ohlc/AAPL", "bars", interval="1d") news = table("/news/search", q="guidance cut", limit=500) # 429 → back off; the budget is in r.headers["x-ratelimit-remaining"].
jq for the envelope, then feed whatever you like —
duckdb, csvkit, R's jsonlite,
Excel's Get Data → From Web (add the header under
Advanced), or a Grafana JSON datasource.
curl -sH "Authorization: Bearer $LUMID_TOKEN" \ "https://lum.id/findata/prediction-markets/trades/kalshi/<ticker>?limit=1000" \ | jq -r '.[] | [.ts,.price,.size] | @csv' > trades.csv
Working within the limits. List endpoints take limit
(max 1000) and offset — page rather than asking for
everything. /ohlc ignores limit and applies a
server-side row cap; narrow with from / to instead.
Watch x-ratelimit-remaining and honour Retry-After
on a 429. For bulk or recurring pulls, or a direct Postgres
connection for a BI tool, ask — those are provisioned per-account
rather than open to anonymous scraping.