MarketFeed API
MarketFeed serves live market prices scraped from Yahoo Finance, Google Finance and Investing.com. For each instrument it reports every source's price side by side, a cross-source consensus, a live tick stream, 30 days of 1-minute history that the server records itself, and long-term daily history back to each instrument's first trade (for example Bitcoin since September 2014).
- Base URL:
https://platform.rotan.app - Formats: JSON over HTTPS, Server-Sent Events, WebSocket, and MCP (Model Context Protocol).
- This guide is public. Machine-readable copies:
/docs.md(Markdown),/llms.txt(index),/openapi.json(OpenAPI 3 schema).
Prices carry whatever delay each website applies: US indices and stocks are usually realtime, while futures on Yahoo are often about 10 minutes behind. Nothing here is investment advice.
Quick start
# every tracked instrument, consensus + per-source quotes
curl https://platform.rotan.app/api/quotes -H "X-API-Key: $MARKETFEED_KEY"
# a few symbols, forcing a fresh check of every source
curl "https://platform.rotan.app/api/quotes?symbols=JKSE,BBCA,SPX&max_age=0" -H "X-API-Key: $MARKETFEED_KEY"
# start tracking a ticker: give its Yahoo id, the rest is looked up
curl -X POST https://platform.rotan.app/api/symbols -H "X-API-Key: $MARKETFEED_KEY" \
-H "Content-Type: application/json" -d '{"yahoo":"UNVR.JK"}'
# what the server recorded for JKSE over the last 7 days, as 15-minute candles
curl "https://platform.rotan.app/api/stored/JKSE?interval=15m&days=7" -H "X-API-Key: $MARKETFEED_KEY"
# Bitcoin's last 10 years of daily candles, as CSV
curl "https://platform.rotan.app/api/daily/BTC?range=10y&format=csv" -H "X-API-Key: $MARKETFEED_KEY"
# put Bank Mandiri and the IDX Composite in a group called "JKSE"
curl -X POST https://platform.rotan.app/api/groups/move -H "X-API-Key: $MARKETFEED_KEY" \
-H "Content-Type: application/json" -d '{"symbols":["BMRI","JKSE"],"group":"JKSE"}'
Authentication
Every /api/* route except /api/health, plus /mcp and /ws, needs an API key. There are two kinds:
- Client keys (
mfk_…), created by the owner in the console under API keys (orPOST /api/keys). Each has a name, an access level and an optional rate limit and expiry, and can be disabled or deleted on its own. Ask the owner for one. - The master key, set on the server (
MF_API_KEY, or the Worker'sAPI_KEYsecret). It can do everything, including managing client keys and switching sources.
Send the key one of three ways:
| Method | Example |
|---|---|
| Header | X-API-Key: <key> |
| Bearer token | Authorization: Bearer <key> (use this for MCP clients) |
| Query string | ?api_key=<key> (for EventSource and WebSocket, which can't set headers) |
| Access | Allows |
|---|---|
read |
Every GET route, /api/stream, /ws, and the read-only MCP tools |
write |
Also POST, PUT, PATCH and DELETE on instruments and groups, POST /api/refresh, and the MCP tools add_symbol, update_symbol, remove_symbol and move_to_group |
| master key or console | Also /api/keys and switching sources (PATCH /api/sources/{source}) |
Responses: 401 for a missing, unknown, disabled or expired key (the detail says which); 403 when the key's access level doesn't cover the request; 429 with a Retry-After header when a key passes its per-minute rate limit. The web console uses a separate PIN that only unlocks browsers. These docs, /llms.txt, /openapi.json and /api/health need no key.
Concepts
Instruments
An instrument is something MarketFeed tracks. Each one has a canonical symbol used everywhere in this API, plus its id on each website.
| Field | Meaning |
|---|---|
symbol |
Canonical symbol: SPX, JKSE, BBCA, WTI, GOLD, ... |
name |
Display name |
asset_class |
index, equity, commodity, fx, crypto, etf or other |
country |
ISO 3166 code (US, ID, JP, ...) or GL for global markets (commodities, FX, crypto) |
exchange |
Display exchange: IDX, NASDAQ, NYMEX, ... |
yahoo |
Yahoo ticker: ^JKSE, BBCA.JK, CL=F, AAPL |
google |
Google Finance id TICKER:EXCHANGE: COMPOSITE:IDX, BBCA:IDX, .INX:INDEXSP |
investing |
Investing.com pair id (number): 29049 for the IDX Composite |
compare |
true: poll all three sources. false: Yahoo only (live stream + batch), which is the default for most stocks |
rank |
Display order inside its group |
group |
Custom group name, or null for the automatic group of its type (see Groups) |
The default watchlist is the S&P 500, NASDAQ Composite, NASDAQ 100, IDX Composite (JKSE), WTI and Brent crude, Apple, Bitcoin (BTC), Ethereum (ETH), Solana (SOL), and the 45 largest IDX stocks by market cap. All 835 IDX-listed stocks are in a built-in catalog that /api/search draws on, and any ticker Yahoo knows can be added.
Sources and freshness
| Source | How it's read | Cadence |
|---|---|---|
| Yahoo Finance | Live WebSocket stream, plus a batched quote request (20 tickers per call) | Ticks as they trade; full refresh every poll (30 s by default) |
| Google Finance | Quote page, parsed from its embedded data | Every poll, only for instruments with compare: true |
| Investing.com | Chart-data endpoint | Every poll, one request at a time, only with compare: true. Its bot check sometimes blocks servers; the server then pauses Investing.com for 1 to 10 minutes and keeps the last good price, marked stale |
Yahoo is the master source and is always on. The owner can switch Google Finance or Investing.com off for every instrument (PATCH /api/sources/{source}); while a source is off it isn't polled, its quotes disappear from consensus results (sources_total shrinks), and requests for that source alone (/api/quotes/{symbol}/google, /api/history/{symbol}?source=google) return 409. Check sources_enabled in /api/health.
While someone watches the stream, instruments whose market is open but whose Yahoo stream has been quiet for 10 s are re-checked every 2 s. Pre-market and after-hours prints from the stream are ignored, so last always reflects the regular session.
Quote
One source's view of one instrument.
| Field | Meaning |
|---|---|
source |
yahoo, google or investing |
source_id |
The id used on that site |
price, change, change_pct |
Last price, change vs previous close, and that change in % |
prev_close, open, day_high, day_low, volume |
When the site provides them |
currency |
ISO currency code |
market_time |
Time of the last trade, per the site (UTC) |
fetched_at |
When this server got it (UTC) |
via |
stream (Yahoo tick), fast (2-second re-check), batch (Yahoo batch poll), poll (single request) |
market_open |
Whether the regular session is open now (Yahoo only) |
ok, error |
ok: false means the request failed. An error starting with stale: means the last good price is being kept after a failure |
Consensus
The cross-source view returned by /api/quotes.
| Field | Meaning |
|---|---|
last |
The freshest price: the live Yahoo tick when it is under 15 s old, otherwise the median. Use this for display |
last_change_pct |
Change % matching last |
last_source |
live or median |
price |
Median price across the sources that answered |
change_pct |
Median change % |
spread_pct |
(max - min) / median * 100 across sources. Under 0.02 means the sources agree; 1 or more means they disagree (for example different futures contracts) |
sources_ok, sources_total |
How many polled sources answered |
quotes |
Object keyed by source, each a Quote |
Example (GET /api/quotes/JKSE, shortened):
{
"symbol": "JKSE",
"name": "IDX Composite",
"last": 5098.057,
"last_change_pct": -3.3399,
"last_source": "median",
"price": 5098.057,
"change_pct": -3.3399,
"spread_pct": 0.0,
"sources_ok": 2,
"sources_total": 3,
"quotes": {
"yahoo": {
"source": "yahoo", "source_id": "^JKSE", "price": 5098.057, "change_pct": -3.1916,
"prev_close": 5266.13, "day_high": 5320.895, "day_low": 5098.057, "currency": "IDR",
"market_time": "2026-10-29T09:00:05Z", "via": "batch", "market_open": false, "ok": true, "error": null
},
"google": { "source": "google", "source_id": "COMPOSITE:IDX", "price": 5098.057, "ok": true },
"investing": { "source": "investing", "source_id": "29049", "ok": false, "error": "HTTP 403" }
}
}
Quotes
GET /api/quotes
Consensus for many instruments.
| Query | Default | Meaning |
|---|---|---|
symbols |
all tracked | Comma-separated symbols, e.g. JKSE,BBCA,SPX. Unknown symbols are looked up on Yahoo by ticker |
sources |
all | Comma-separated subset of yahoo,google,investing |
max_age |
15 | Accept cached quotes up to this many seconds old. 0 forces a fresh check |
Returns an array of Consensus.
GET /api/quotes/{symbol}
Consensus for one instrument. Same sources and max_age parameters. {symbol} can be a tracked symbol (BBCA) or any Yahoo ticker (MSFT, EURUSD=X, BTC-USD).
GET /api/quotes/{symbol}/{source}
One source's Quote. {source} is yahoo, google or investing.
GET /api/sparklines
Today's 5-minute closes from Yahoo for many instruments in one call.
| Query | Default | Meaning |
|---|---|---|
symbols |
all tracked | Comma-separated symbols |
Returns {"SPX": [[1793194200, 7721.4], ...], ...}, pairs of Unix seconds and close.
POST /api/refresh
Re-checks every tracked instrument now and pushes a snapshot to stream clients. Returns the Consensus array once Yahoo and Google have answered; Investing.com results follow in a later snapshot event.
Instruments
GET /api/symbols
Tracked instruments. Optional filters: asset_class (e.g. equity) and country (e.g. ID).
GET /api/search
Ticker suggestions for adding instruments: tracked matches first, then the IDX catalog (835 stocks), then Yahoo's worldwide search.
| Query | Default | Meaning |
|---|---|---|
q |
empty | Text: a code (TLKM), Yahoo ticker (TLKM.JK), or name (bank central). Empty returns popular instruments and the largest IDX stocks not yet tracked |
limit |
12 | 1 to 40 |
Each result: symbol, yahoo, name, asset_class, country, exchange, tracked (bool), origin (tracked, idx, yahoo or popular). Add one by posting its yahoo value to /api/symbols.
POST /api/symbols
Start tracking an instrument.
By Yahoo ticker (recommended). Name, type, country, exchange, currency and Google id are looked up; the Google id is kept only if Google's page actually parses.
{"yahoo": "TLKM.JK"}
Optional fields: symbol (override the canonical symbol), compare (default true for indices and commodities, false otherwise), investing (Investing.com pair id, which can't be looked up automatically).
By hand. Send a full Instrument with symbol, name and at least one of yahoo, google, investing.
Returns the Instrument: 201 when created, 200 when the ticker was already tracked, 404 when Yahoo has no quote for it.
PATCH /api/symbols/{symbol}
Change any of name, asset_class, country, exchange, google, investing, compare, note, rank, group. Example: {"compare": true} starts polling Google and Investing.com for that instrument; {"investing": 29049} sets its Investing.com pair id.
DELETE /api/symbols/{symbol}
Stops tracking the instrument and deletes its stored history. Returns {"deleted": "BBCA"}, or 404.
Groups
The console lists instruments in groups. Every instrument starts in the automatic group for its type: Indices, Stocks, Commodities, Currencies, Crypto, ETFs or Other. Move any instrument into a custom group (for example JKSE for the Jakarta index and its stocks) and it shows there instead. Groups only affect display and filtering; quotes and history don't change.
GET /api/groups
Groups in display order: [{"name": "JKSE", "count": 4, "custom": true, "symbols": ["JKSE", "BBCA", "BBRI", "BMRI"]}, ...].
POST /api/groups/move
Body: {"symbols": ["BMRI", "BBCA"], "group": "JKSE"}. A new name creates the group (placed right after the group the first instrument came from). "group": null (or "", or the type's own automatic name) puts the instruments back in their automatic group. Returns the moved instruments. 404 if a symbol isn't tracked.
PUT /api/groups
Body: {"order": ["JKSE", "Indices", "Crypto", "Stocks"]} sets the display order. Groups you leave out keep their default place.
PATCH /api/groups/{name}
Body: {"name": "IDX blue chips"} renames a group. Renaming an automatic group turns its members into a custom group of that name.
DELETE /api/groups/{name}
Dissolves a custom group; its instruments go back to their automatic groups (nothing is untracked). Returns {"group", "returned"}. Automatic groups can't be deleted (400).
History
There are three kinds of history:
- Remote: each website's own chart data, available immediately for any instrument (
/api/history). - Stored: what this server recorded from the stream and polls: one-minute bars per source, kept for 30 days, only for tracked instruments (
/api/stored). - Daily: long-term daily candles from Yahoo, back to the instrument's first trade (
/api/daily). For tracked instruments the full history is downloaded once and kept in the database; later requests only fetch the last few days.
GET /api/daily/{symbol}
| Query | Default | Meaning |
|---|---|---|
range |
1y |
1mo, 3mo, 6mo, ytd, 1y, 2y, 5y, 10y, 20y or max |
interval |
1d |
1d, 1wk (weeks start Monday) or 1mo |
start, end |
ISO dates; override range |
|
refresh |
false |
Fetch the latest days now instead of waiting for the hourly top-up |
format |
json |
json or csv (columns date,open,high,low,close,volume) |
Returns {"symbol", "source": "yahoo", "interval", "range", "start", "end", "candles": [{"t", "o", "h", "l", "c", "v"}], "first_available", "stored"}. first_available is the oldest day Yahoo has (BTC: 2014-09-17; S&P 500: 1927). stored is true when the data came from (and is kept in) this server's database; untracked tickers are fetched live and not stored. Prices are split-adjusted but not dividend-adjusted. Each candle's t is the trading day (midnight UTC of that date). 404 when Yahoo has no such ticker.
Examples: /api/daily/BTC?range=10y, /api/daily/SPX?range=max&interval=1mo, /api/daily/BBCA?range=5y&interval=1wk&format=csv.
GET /api/history/{symbol}
Remote candles from one source.
| Query | Default | Meaning |
|---|---|---|
source |
yahoo |
yahoo, google (today's intraday line only) or investing |
interval |
5m |
1m, 5m, 15m, 30m, 1h, 1d, 1w |
points |
78 | 2 to 500, most recent last |
Returns {"symbol", "source", "interval", "candles": [{"t", "o", "h", "l", "c", "v"}]}.
GET /api/stored/{symbol}
Stored bars, aggregated to the interval you ask for. Candles are aligned to UTC.
| Query | Default | Meaning |
|---|---|---|
source |
yahoo |
Which source's bars |
interval |
5m |
1m, 5m, 15m, 30m, 1h, 4h, 1d |
days |
Window ending now, 0 to 30. Overrides start/end |
|
start, end |
today (UTC) to now | ISO 8601 timestamps |
Add format=csv for a CSV download. Returns {"symbol", "source", "interval", "start", "end", "candles": [...], "first_stored", "minutes_stored"}. first_stored is the oldest minute kept for that series. minutes_stored is the number of 1-minute bars in your window. Gaps mean the market was closed or the server wasn't running. 404 if the instrument isn't tracked.
GET /api/storage
Database size and contents: bars, bars_by_source, oldest, newest, size_bytes, instruments, retention_days, daily_bars, daily_series.
Live stream
GET /api/stream (Server-Sent Events)
Two event types:
snapshot:{"type": "snapshot", "at": "<iso>", "data": [Consensus, ...]}for every tracked instrument. Sent on connect (from cache, with"cached": true), after every poll (30 s), and whenever instruments change.ticks:{"type": "ticks", "at": "<iso>", "items": [{"symbol", "q", "c"}, ...]}, at most 4 per second while prices move.qis the instrument's new Yahoo Quote.cholds the updated consensus fields (last,last_change_pct,last_source,price,change_pct,spread_pct,sources_ok,sources_total). Mergeqintoquotes.yahooandcinto the instrument's consensus.
A comment line : keep-alive is sent every 15 s.
const es = new EventSource("https://platform.rotan.app/api/stream?api_key=<key>");
es.addEventListener("snapshot", e => render(JSON.parse(e.data).data));
es.addEventListener("ticks", e => JSON.parse(e.data).items.forEach(update));
GET /ws (WebSocket)
The same messages as JSON text frames. Authenticate with ?api_key=<key>.
MCP (Model Context Protocol)
- Endpoint:
https://platform.rotan.app/mcp(Streamable HTTP, stateless, JSON responses) - Auth:
Authorization: Bearer <key>. Areadkey can call every tool exceptadd_symbol,update_symbol,remove_symbolandmove_to_group(those return403).
| Tool | Arguments | Returns |
|---|---|---|
list_symbols |
asset_class?, country? |
Tracked instruments |
search_symbols |
query, limit? |
Suggestions, as /api/search |
get_quote |
symbol, sources?, max_age_seconds? |
Consensus |
get_quotes |
symbols?, sources?, include_source_detail? |
Consensus list |
get_history |
symbol, source?, interval?, points? |
Remote candles |
get_stored_history |
symbol, source?, interval?, days? (up to 30) |
Stored candles |
get_daily_history |
symbol, range? (1mo … 10y, max), interval? (1d, 1wk, 1mo) |
Long-term daily candles |
list_groups |
Groups with their members | |
move_to_group |
symbols, group? (null = automatic) |
Moved instruments |
add_symbol |
yahoo, compare?, investing? |
{created, instrument} |
update_symbol |
symbol, compare?, google?, investing?, name?, group? |
Instrument |
remove_symbol |
symbol |
{removed} |
source_health |
Per source: switched on or off, success counts, latency | |
storage_stats |
As /api/storage |
Resource: marketfeed://snapshot, the cached consensus for all tracked instruments.
Claude Code:
claude mcp add --transport http marketfeed https://platform.rotan.app/mcp --header "Authorization: Bearer <key>"
Claude Desktop, Cursor and other clients (mcp.json):
{"mcpServers": {"marketfeed": {"url": "https://platform.rotan.app/mcp", "headers": {"Authorization": "Bearer <key>"}}}}
Sources
GET /api/sources
Each source with its switch, health and a diagnosis: source, enabled, master (true for Yahoo), instruments (how many instruments use it), ok, failed, avg_latency_ms, last_ok, last_error, last_error_at, plus:
| Field | Meaning |
|---|---|
state |
ok, or the kind of the latest failure (table below) |
state_label, advice |
The state in words, and what to do about it |
failing_since |
When the current run of failures began (null while working) |
recent_ok_pct |
Share of the last 50 requests that got a price |
errors_by_kind |
Failures since the server started, by kind, e.g. {"blocked": 12, "network": 1} |
recent_errors |
The last 20 failures, newest first: at, symbol, kind, error |
| Kind | Means | Typical message |
|---|---|---|
blocked |
The site refused this server (bot check) | HTTP 403 (bot challenge), google: blocked (captcha) |
rate_limited |
Too many requests | HTTP 429 (rate limited) |
paused |
MarketFeed stopped asking for 1 to 10 minutes after failures in a row; the message keeps the last one | paused for 120 s after 3 failed requests in a row (last: HTTP 403 (bot challenge)) |
not_found |
The site doesn't know the ticker or id | HTTP 404 |
site_error |
The site answered with a server error | HTTP 503 |
network |
No answer: timeout, DNS, connection or TLS failure | Timeout: … timed out |
no_data |
An answer without a price: wrong id, or the site changed its page | quote for X not found on page |
other |
Anything else |
POST /api/sources/{source}/test
Master key or console only. Makes one live request to the source now, ignoring the cache and any pause, for one of its instruments (or ?symbol=BTC), and returns ok, state, state_label, advice, symbol, price, error, latency_ms and tested_at. A successful test also ends a pause.
PATCH /api/sources/{source}
Master key or console only. {"enabled": false} switches Google (google) or Investing.com (investing) off for every instrument; {"enabled": true} switches it back on and checks it right away. Each instrument's own compare setting is kept. Yahoo can't be switched off (400). Returns the list as GET /api/sources.
API keys
Master key or console only. The console's API keys page does the same with a form.
GET /api/keys
Client keys, newest first: id, name, hint (e.g. mfk_Ab3x…9QzT), scope (read or write), rate_limit (requests per minute, 0 = none), created_at, expires_at, disabled_at, last_used_at, last_ip, requests, and status (active, disabled or expired).
POST /api/keys
curl -X POST https://platform.rotan.app/api/keys -H "X-API-Key: <master key>" -H "Content-Type: application/json" \
-d '{"name": "Trading bot", "scope": "read", "rate_limit": 120, "expires_days": 90}'
Returns 201 {"key": {...}, "secret": "mfk_..."}. The full key appears only in this response; the server keeps a hash of it.
PATCH /api/keys/{id}
Any of name, scope, rate_limit, and enabled (false disables the key at once, true re-enables it).
DELETE /api/keys/{id}
Deletes the key; apps using it get 401 from then on.
Status
GET /api/health (public)
status, version, poll_interval, cache_ttl, instruments, watching (open stream clients), last_poll, stream (Yahoo stream: connected, ticks, last_tick_at, last_error), fast_poll, sources_enabled ({"yahoo": true, "google": true, "investing": false}), retention_days, and sources (per-source health).
GET /api/bootstrap
Everything a dashboard's first screen needs in one response, served from memory without contacting any website: instruments, groups, snapshot (the cached consensus for every instrument, as /api/quotes but without refreshing), sparklines, health, session and at. The web console gets the same data embedded in its page, so prices show without any API call.
GET /api/sources/health
Per source: ok, failed, avg_latency_ms, last_ok, last_error, last_error_at.
Errors
| Status | Meaning |
|---|---|
| 400 | Bad parameter, e.g. an unknown source name |
| 401 | Missing, unknown, disabled or expired API key |
| 403 | The key's access level doesn't allow this (read-only key writing, or a client key managing keys or sources) |
| 409 | The request needs a source that's switched off |
| 429 | The key passed its rate limit; see Retry-After |
| 404 | Instrument not tracked, or unknown ticker on add |
| 422 | Validation error (FastAPI format: {"detail": [...]}) |
| 502 | The source website failed for a history request |
Errors are JSON: {"detail": "..."}.
Notes and limits
- Polling: every 30 s (
MF_POLL_INTERVAL). Cached quotes are reused for 15 s (MF_CACHE_TTL) unless you passmax_age=0. - Storage: one SQLite database, 1-minute OHLC bars per instrument and source, deleted after 30 days (
MF_RETENTION_DAYS). - Daily history is kept indefinitely; it is small (ten years of one instrument is about 2,500 rows). The first request for an instrument downloads its full history (BTC: ~4,400 days, S&P 500: ~14,000), later ones only the last ten days, at most hourly.
- Crypto trades around the clock, so BTC, ETH and SOL tick and record 24/7. Sources differ by a few tenths of a percent because each quotes a different exchange mix.
- Futures roll on different days per site, so small gaps between sources around expiry are normal. Google lists NYMEX Brent Last Day Financial (
BZW00), which trades about 3% above the front-month Brent the others show. - Investing.com ids can't be looked up automatically; find the pair id in the page source of the instrument on investing.com (
data-pair-id) and set it withPATCH. - Scraping these websites may conflict with their terms of use and can break when they change. For production trading, use a licensed data feed.