canonical: https://jentic.com/apis/marketdata.app/marketdata

# Marketdata App Market Data API

Market Data is a real-time and historical US equities and options data API. The 14 endpoints expose stock quotes, candle bars, prices, earnings, and news, plus an options chain, expirations list, options lookup, options strikes, and option-symbol quotes, alongside a global market status endpoint. Data is returned at second-level resolution for quotes and configurable resolutions (1-minute, daily, weekly, etc.) for candles. Authentication is a bearer-style API key passed as the `token` query parameter.

## For AI agents

Pull real-time and historical US stock quotes, options chains, candle bars, earnings, and news through 14 endpoints. Authentication is an API key in the `token` query parameter.

## Scope

Does not handle order placement, brokerage account management, fundamentals, or non-US markets - use for US stocks and options market data only.

## Capabilities

- Pull a real-time quote for a stock symbol via `/v1/stocks/quotes/{symbol}`/ or many symbols at once via `/v1/stocks/bulkquotes`/
- Read historical candle bars at any resolution from `/v1/stocks/candles/{resolution}/{symbol}`/ or in bulk via `/v1/stocks/bulkcandles/{resolution}`/
- Fetch the upcoming and historical earnings calendar for a symbol via `/v1/stocks/earnings/{symbol}`/
- Read the latest news for a stock symbol with `/v1/stocks/news/{symbol}`/
- Look up an option chain, expirations, strikes, or per-option quote under `/v1/options`/*
- Resolve a free-form option description into the canonical option symbol with `/v1/options/lookup/{userInput}`/
- Check whether US equity, options, or other markets are open via `/v1/markets/status`/

## Use cases

### Real-Time Watchlist Quotes

Trading dashboards and Slack bots call `/v1/stocks/bulkquotes`/ on a polling interval to refresh prices for a user's watchlist in a single round trip rather than one HTTP call per symbol. The response includes bid, ask, last, and volume so a UI can render full ticker rows. Polling integration is straightforward in a few hours.

Example prompt: Call `/v1/stocks/bulkquotes`/ with the symbols AAPL, MSFT, NVDA, AMZN, TSLA and return a JSON map of symbol to last price.

### Options Chain Discovery

Options-focused tools call `/v1/options/expirations/{underlying}`/ and `/v1/options/chain/{underlying}`/ to load the full chain for an underlying and let traders pick a strike and expiry. The `/v1/options/lookup/{userInput}`/ endpoint resolves a free-form input like 'AAPL Sep 15 2025 200 call' into the canonical option symbol that `/v1/options/quotes/{optionSymbol}`/ accepts.

Example prompt: Call `/v1/options/expirations/AAPL`/ for the next available expiry, then `/v1/options/chain/AAPL`/ for that expiry and return only the call options with strikes within 5% of spot.

### Back-Testing Candle Pulls

Quant research notebooks call `/v1/stocks/candles/{resolution}/{symbol}`/ at daily resolution to pull multi-year candle history for back-testing strategies on a single name. `/v1/stocks/bulkcandles/{resolution}`/ returns the same data across many symbols in one call, which is faster and cheaper for portfolio-level studies.

Example prompt: Call `/v1/stocks/candles/D/SPY`/ for a one-year window and return a list of dictionaries with date, open, high, low, close, and volume.

### Earnings and News Aggregator

Market-news products call `/v1/stocks/earnings/{symbol}`/ to surface upcoming earnings dates and `/v1/stocks/news/{symbol}`/ to pull recent headlines for a watchlist. Combined they power an at-a-glance card per symbol showing the next earnings event and the latest two or three news items.

Example prompt: Call `/v1/stocks/earnings/MSFT`/ and `/v1/stocks/news/MSFT`/ in parallel and return a single JSON document with the next earnings date and the three most recent headlines.

### AI Agent for Trading and Research

An AI research assistant calls Market Data through Jentic to answer quote, candle, options-chain, and earnings questions without bespoke client code. Jentic exposes each endpoint as a typed tool with a discoverable input schema so the agent picks `/v1/stocks/quotes` vs `/v1/options/chain` based on the user's question. Setup runs through search, load, and execute in under an hour.

Example prompt: Search Jentic for 'get a real-time stock quote', load the schema for `/v1/stocks/quotes/{symbol}`/, and execute the call for symbol NVDA.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v1/stocks/quotes/{symbol}/` | Real-time quote for a single stock |
| GET | `/v1/stocks/bulkquotes/` | Bulk quotes for many symbols |
| GET | `/v1/stocks/candles/{resolution}/{symbol}/` | Historical candle bars for one symbol |
| GET | `/v1/stocks/earnings/{symbol}/` | Earnings calendar for a symbol |
| GET | `/v1/stocks/news/{symbol}/` | Recent news for a symbol |
| GET | `/v1/options/chain/{underlying}/` | Options chain for an underlying |
| GET | `/v1/options/quotes/{optionSymbol}/` | Quote for a specific option contract |
| GET | `/v1/markets/status/` | Market open/closed status |

## Key resources

- **Stocks** — Quotes, bulk quotes, candles, bulk candles, prices, earnings, and news under `/v1/stocks`
- **Options** — Chain, expirations, strikes, lookup, and per-symbol quote under `/v1/options`
- **Markets** — Market open/close status via `/v1/markets/status`

## Why Jentic

- **Setup:** Wiring Market Data by hand means appending its token query parameter, learning the separate `/v1/stocks` and `/v1/options` paths, and handling the per-symbol path segments yourself. Through Jentic you install once, import the Market Data API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** The Market Data endpoints are read-only quote and history lookups, so scoping is by operation: you limit the agent to the operations it needs, such as fetching a stock quote, candles, or an options chain, and leave out the rest. Every operation you allow is one you have chosen, so the agent stays inside that set.
- **Credential handling:** Your Market Data token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'real-time stock quote' or 'options chain for an underlying', and Jentic returns the matching Market Data operation with its query schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Polygon.io** — Polygon offers tick-level US equities and options market data with WebSocket streams; Market Data covers REST quotes, candles, and options.
- **Finnhub** — Finnhub provides equities, fundamentals, and alternative data; Market Data is more focused on real-time quotes and options.
- **Tradier** — Tradier offers brokerage and order-routing endpoints that pair with Market Data's quote and options chain feeds.
- **Alpha Vantage** — Alpha Vantage provides FX, crypto, and macro indicators that complement Market Data's US equities and options coverage.

## FAQ

### What authentication does the Market Data API use?

Market Data uses an API key passed as the `token` query parameter on every request. Jentic stores the key encrypted in your Jentic One instance and appends it at execution time so the raw token never enters the agent context.

### Can I pull intraday 1-minute candles for a stock?

Yes. GET `/v1/stocks/candles/{resolution}/{symbol}`/ accepts the resolution as a path parameter - `1` returns 1-minute bars, `D` returns daily bars, and so on. Use `/v1/stocks/bulkcandles/{resolution}`/ to pull the same resolution across many symbols in one call.

### Does Market Data offer options data?

Yes. The `/v1/options/chain/{underlying}`/, `/v1/options/expirations/{underlying}`/, `/v1/options/strikes/{underlying}`/, `/v1/options/lookup/{userInput}`/, and `/v1/options/quotes/{optionSymbol}`/ endpoints together cover chain discovery and per-option quoting.

### What are the rate limits for the Market Data API?

Rate limits are tier-based and not declared in the spec. Each plan exposes a daily request budget visible on the marketdata.app dashboard; over-quota requests return HTTP 429 so callers should respect the response code and back off.

### How do I get a real-time stock quote through Jentic?

Run `pip install jentic`, search for 'get a real-time stock quote', load the schema for GET `/v1/stocks/quotes/{symbol}`/, and execute it with the desired symbol. Jentic supplies the API key and returns parsed JSON.

### How do I check whether the US market is open before placing trades?

GET `/v1/markets/status`/ returns the current open/closed status of supported markets. Call it before kicking off any quote or order workflow so a research notebook does not interpret a stale closing price as live.

### Can I limit what my agent is allowed to do with the Market Data API?

Yes. Because Jentic One is self-hosted, your own rules decide which Market Data operations the agent may call, so you can allow only the read-only lookups it needs, such as GET `/v1/stocks/quotes/{symbol}`/ for a stock quote, GET `/v1/stocks/candles/{resolution}/{symbol}`/ for candle history, or GET `/v1/options/chain/{underlying}`/ for an options chain, and leave out the rest. Every operation the agent can reach is one you have explicitly permitted, and it stays inside that set. Your Market Data token is held encrypted by your own instance and injected only at execution time, so it never enters the agent's prompt or context.