API v1

Developers

Public, read-only API over the same canonical data the site shows. Every response carries provenance metadata; values whose data rights forbid redistribution are withheld rather than silently omitted.

Base URL & envelope

https://www.market-atlas.co/v1

{ "data": …, "meta": { "request_id": "…", "timestamp": "2026-09-12T14:31:42.512Z", "data_status": "DELAYED" } }

Errors are structured: { "error": { "code": "INSTRUMENT_NOT_FOUND", "message": "instrument not found" } } with the matching HTTP status. No stack traces.

Rate limits

240 requests per minute sustained per IP (burst 60) on REST; 429 with Retry-After when exceeded. Streams are not counted. Higher limits and API keys will come with the developer accounts.

REST endpoints

Endpoint	Description
`GET /v1/stats`	Live telemetry (instruments, connectors, observations today, events, freshness).
`GET /v1/markets`	Global overview: featured indices, crypto, FX, rates, commodities, equities, movers, exchanges with state, breadth.
`GET /v1/instruments?asset_class=&exchange=&country=&q=&quoted=1&sort=&limit=&offset=`	Instrument master with canonical quotes. sort ∈ symbol \| change \| -change \| volume \| name.
`GET /v1/instruments/{id\|SYMBOL\|VENUE:SYMBOL}`	Instrument detail: company, exchange + status, quote, aliases, observing sources, related instruments.
`GET /v1/quotes/{id}`	One canonical quote.
`GET /v1/quotes?ids=a,b,c`	Up to 200 canonical quotes.
`GET /v1/quotes/{id}/provenance`	“Why this price?” — every contribution with weight, age, inclusion and reason.
`GET /v1/history/{id}?resolution=1m\|5m\|15m\|1h\|1d&from=&to=&limit=`	OHLCV bars (t, o, h, l, c, v, n sources, p producer).
`GET /v1/events?type=&instrument=&country=&asset_class=&severity=&since=&before=&limit=`	Canonical events; GET /v1/events/{id} for one.
`GET /v1/filings?form=&cik=&q=&limit=&offset=`	Regulatory filings observed on EDGAR.
`GET /v1/exchanges · GET /v1/exchanges/{id}`	Venues with session state, holidays, breadth, movers, events.
`GET /v1/countries · GET /v1/countries/{code}`	Country atlas: exchanges, indices, rates, FX, equities, events.
`GET /v1/search?q=`	Hybrid search grouped by asset class, exchange, country.
`GET /v1/compare?ids=&resolution=`	Rebased series, return/volatility/drawdown, pairwise correlation.
`GET /v1/changes?window=1m\|5m\|15m\|1h\|1d`	What changed: movers > 1 %, events, filings, by type.
`GET /v1/breadth?scope=world\|US\|xnas`	Advancers/decliners/highs/lows for a scope.
`GET /v1/sources · GET /v1/connectors · GET /v1/data-health · GET /v1/status · GET /v1/health · GET /v1/metrics`	Provenance directory, connector operations, health, public status, liveness, Prometheus metrics.

Example

curl https://www.market-atlas.co/v1/quotes/BTC-USD

{
  "data": {
    "instrument_id": "crypto_btc_usd", "symbol": "BTC-USD", "price": 77326.37, "change_percent": 0.0275,
    "bid": 77326.36, "ask": 77326.37, "currency": "USD",
    "source_count": 2, "dispersion_bps": 0.02, "confidence": 0.906, "freshness_ms": 1552,
    "data_status": "REALTIME", "market_state": null, "rights_status": "PUBLIC_ATTRIBUTED", "withheld": false,
    "updated_at": "2026-09-12T08:42:34.479Z", "source_timestamp": "2026-09-12T08:42:34.358Z"
  },
  "meta": { "request_id": "…", "timestamp": "…", "data_status": "REALTIME" }
}

Quote fields

data_status: REALTIME · DELAYED · AT_CLOSE · END_OF_DAY · STALE · WITHHELD. Never treat anything but REALTIME as live.
source_count = independent source families included; dispersion_bps = spread between included sources; confidence ∈ [0, 0.995].
freshness_ms = age of the newest included observation at response time; source_timestamp is the source's own time when published.

WebSocket stream

wss://www.market-atlas.co/v1/stream

→ { "action": "subscribe", "channels": ["quotes:BTC-USD", "quotes:AAPL", "events:*", "market:xnas"] }
← { "type": "hello", "version": 1, "server_seq": 1024, "ts": 1789202146812 }
← { "type": "subscriptions", "channels": ["quotes:crypto_btc_usd", "quotes:eq_us_xnas_aapl", "events:*", "market:xnas"] }
← { "type": "batch", "seq": 1, "ts": 1789202146921, "messages": [
      { "type": "quote", "instrument_id": "crypto_btc_usd", "symbol": "BTC-USD", "price": 77326.37, "change": 21.27, "change_pct": 0.0275,
        "bid": 77326.36, "ask": 77326.37, "volume": 6634.6, "currency": "USD", "timestamp": 1789202146563, "received": 1789202146819,
        "confidence": 0.906, "sources": 2, "status": "REALTIME" },
      { "type": "event", "event": { "id": "evt_…", "type": "TRADING_HALT", "title": "…", "severity": "WARNING", "confidence": 1, "source_count": 1, "sources": ["nasdaq-trader"], "instrument_ids": [], "data": { … } } },
      { "type": "market_state", "exchangeId": "xnas", "state": "OPEN", "at": 1789392600000 }
   ] }
← { "type": "heartbeat", "ts": …, "seq": 42 }     (every 25 s)
→ { "action": "ping", "id": 1 }  ←  { "type": "pong", "id": 1, "ts": … }
→ { "action": "unsubscribe", "channels": ["quotes:AAPL"] }

Channels:

quotes:<SYMBOL|id> one instrument · quotes:* everything (throttled to 2 updates/s per instrument) · quotes:class:CRYPTO one asset class · tape compact price changes.
events:* · events:<SYMBOL|id> · events:US (country) · events:type:TRADING_HALT.
market:<exchange> or market:* for session-state changes.

Frames are batched (≈ 10 per second per client) and carry a per-client seq; a gap means messages were dropped under backpressure. Up to 500 channels per connection.

Server-Sent Events

curl -N "https://www.market-atlas.co/v1/sse?channels=quotes:BTC-USD,events:*"

event: hello
data: {"version":1,"channels":["quotes:crypto_btc_usd","events:*"],"ts":…}

event: batch
id: 58
data: {"type":"batch","seq":1,"ts":…,"messages":[{"type":"quote",…}]}

Identifiers

Stable public ids: eq_us_xnas_aapl, etf_us_arcx_spy, index_us_spx, crypto_btc_usd, fx_eur_usd, rate_us_us10y, cmd_xcme_gc_f. Endpoints accepting {id} also accept a bare symbol (AAPL, BTC-USD) or VENUE:SYMBOL.

Attribution & terms

Data carries the rights status of its sources; see data rights. Cboe values are 15-minute delayed and must be displayed as such; venue and official-source attributions must be preserved when redistributing. Market Atlas is an informational platform, not investment advice.