Early access is open. Free sample datasets are live now. Download a sample

API Reference: Stock Trades and Quotes

Details

Docs navigation

Two endpoints return tick-level US stock data: every trade print (time and sales) and every change to the best bid and offer. This page covers the stock trades API endpoint and the quotes endpoint, their parameters and fields, and the condition codes and ordering rules you need to build correct bars or measure spreads from ticks.

Early access. Planned v1 endpoints, not live yet. Trades: Pro ($79/mo) gets 15-minute delayed trades and 10 years of history; Business ($249/mo) real-time SIP and full history. Quotes: Pro gets live top of book from a single fee-light venue and 1 year of NBBO history; Business gets SIP NBBO and full history.

Details

Trades

GET https://api.marketdata.co/v1/stocks/trades

Parameters

Name Type Required Default Description
symbol string yes Ticker
date string one of date or start One trading day, YYYY-MM-DD
start string UTC timestamp, inclusive
end string no end of start day UTC timestamp, exclusive
exchange string no all Venue MIC filter, e.g. XNAS
include_off_exchange boolean no true Include TRF and dark pool prints
session string no all regular, extended, all
limit integer no 5,000 Max 50,000
cursor, format string no Paging and json or csv

Response fields

Field Type Description
symbol string Ticker
timestamp string SIP timestamp, ISO 8601 UTC, nanoseconds
participant_timestamp string Exchange's own timestamp (optional)
price number Trade price
size number Shares, odd lots included
exchange string Venue MIC
conditions array Sale condition codes, e.g. @, F, T, I
tape string A (NYSE), B (Arca and others), C (Nasdaq)
trade_id string Venue trade ID (optional)
sequence_number number SIP sequence number
is_off_exchange boolean True for TRF and dark pool prints
trf_id string Reporting facility ID for off-exchange prints (optional)
correction number Correction indicator (optional)
bid_price, ask_price number NBBO at trade time (optional)
aggressor_side string buy, sell, unknown (optional)
session string pre, regular, post, overnight

Example request and response

Example (curl):

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.marketdata.co/v1/stocks/trades?symbol=AAPL&date=2026-11-18&limit=50000"

Example response (illustrative values):

{
  "status": "ok",
  "count": 50000,
  "next_cursor": "eyJzIjoxMDQ4MjMxfQ",
  "results": [
    {
      "symbol": "AAPL",
      "timestamp": "2026-11-18T14:30:01.204518337Z",
      "participant_timestamp": "2026-11-18T14:30:01.204390112Z",
      "price": 228.43,
      "size": 100,
      "exchange": "XNAS",
      "conditions": ["@"],
      "tape": "C",
      "trade_id": "52983525029461",
      "sequence_number": 1048231,
      "is_off_exchange": false,
      "bid_price": 228.42,
      "ask_price": 228.44,
      "aggressor_side": "buy",
      "session": "regular"
    }
  ]
}

Details

Quotes (NBBO)

GET https://api.marketdata.co/v1/stocks/quotes

Parameters

Name Type Required Default Description
symbol string yes Ticker
date or start / end string yes As for trades
quote_type string no nbbo nbbo or exchange (single-venue BBO)
limit, cursor, format no As for trades

Response fields

Field Type Description
symbol string Ticker
timestamp string SIP timestamp, UTC, nanoseconds
participant_timestamp string Exchange timestamp (optional)
bid_price, ask_price number Best bid and ask
bid_size, ask_size number Shares at each side (shares, not round lots)
bid_exchange, ask_exchange string Venue of best bid and ask
quote_type string nbbo or exchange
conditions array Quote condition codes (optional)
tape string A, B, C
sequence_number number SIP sequence number

Example (Python), average quoted spread in cents for one day:

import os
import requests
import pandas as pd

r = requests.get(
    "https://api.marketdata.co/v1/stocks/quotes",
    headers={"Authorization": f"Bearer {os.environ['MARKETDATA_API_KEY']}"},
    params={"symbol": "SPY", "date": "2026-11-18", "limit": 50000},
)
q = pd.DataFrame(r.json()["results"])
print(((q["ask_price"] - q["bid_price"]) * 100).mean())

API

Errors for these endpoints

HTTP error.code When
400 missing_parameter Neither date nor start given
400 range_too_large start to end spans more than one trading day
403 plan_required Trades below Pro, real-time SIP below Business, or quotes older than 1 year on Pro
404 symbol_not_found Unknown ticker

Watch out

Notes and gotchas

  • Sort by timestamp, then sequence_number. Several prints can share a nanosecond.
  • Not every print should go into OHLC. Late reports, odd-lot and average-price conditions are excluded from official highs and lows. Filter on conditions if you build your own bars.
  • Drop rows where correction is non-zero if you want the final tape.
  • Off-exchange prints are reported to a TRF with a delay of up to a few seconds and can look out of sequence. Use is_off_exchange to split them out.
  • A busy stock can print several million trades a day. That is dozens of pages; write each to disk as it arrives.
  • For whole years of ticks, a file at $15 per symbol-year (trades) or $25 (NBBO) is cheaper than paging. See dataset downloads.

Keep reading

Next steps

Details

Was this page useful?

[Yes] [No]

Need a field we don't return? Tell us on the custom data form.