Market data API explained: REST, WebSocket, symbols and timestamps

A market data API is a web service that hands your code the prices of traded instruments and the reference data around them: the current bid and ask, the last trade, historical OHLCV bars, symbol lists and market hours. You call it over REST when you want one answer now, and you hold a WebSocket open when you want every change pushed to you as it happens.

That definition fits every provider. What separates a pleasant integration from a month of quiet bugs is everything around the endpoint, so this guide walks through the parts in the order they tend to break, using TickerLayer for the examples. One request first:

curl -sS "https://api.tickerlayer.com/stocks/snapshot/US:KO" \
  -H "x-api-key: $TICKERLAYER_API_KEY"

{
  "symbol": "US:KO",1
  "bid": 88.11,
  "ask": 88.24,
  "bid_size": 400,
  "ask_size": 1000,
  "last_price": 88.24,3
  "last_timestamp": 1790589160160,4
  "prev_close": 87.81,5
  "change": 0.43,
  "change_percent": 0.4897,6
  "last_size": 150
}

What a market data API actually returns

Market data is the record of what buyers and sellers are doing: the prices they quote, the trades they complete, and summaries of both over time. Around it sits reference data that tells you how to read those prices: which instruments exist, when their markets open, what unit a number is in. A financial data API usually adds slower-moving data such as company fundamentals.

Quotes here are Level 1 data: the best bid and the best ask, with their sizes. Level 2 adds the queue of orders waiting behind them at every price. Most developer APIs, TickerLayer included, serve Level 1, and it is what charts, alerts, dashboards and most trading logic actually consume.

How prices travel from the market to your code

Every price starts as an event somewhere else: an order resting on an exchange, a dealer quote, a trade printed on a venue. A market data feed is the continuous stream of those events from one source. The API sits at the other end and turns many feeds into one consistent interface. What happens in between decides how far you can trust the number.

Providers differ most in the bottom two layers. An exchange-direct feed gives you one venue's raw messages, fast and official, with that venue's licence attached. An aggregated API such as TickerLayer combines sources into derived, indicative prices: not official exchange data, but one format across asset classes and markets, which is what most applications need. If you are weighing those trade-offs, the guide to choosing financial data providers lists the questions to ask, and our data quality benchmarks show how our prices compare with independent references.

Symbols: the first thing that breaks

A symbol looks like a trivial string until you add a second market. KO is unambiguous in New York, but tickers are unique only inside one market, and the same company can list in several. That is why TickerLayer stock symbols carry a market prefix, US:KO or DE:SAP, and why a bare KO returns 400 invalid symbol instead of a guess.

Two habits prevent most symbol bugs: normalize user input before it reaches your code (EUR/USD becomes EURUSD, BTC-USD becomes BTCUSD), and validate against the provider's symbol list instead of guessing. The ticker symbol guide covers formats across markets, including numeric codes in Asia and share-class suffixes.

Units and number types

A price is a number plus a unit, and the unit is usually implied. Currency pairs are priced in the second currency, so USDJPY at 157.10 means yen per dollar. Stocks are priced in the currency of their listing. Commodities are where implied units bite: SUGARUSD is quoted in US cents per pound, so 18.54 means 18.54 cents, not dollars. Bond yields come with an explicit "unit": "percent", and the bond snapshot reports the daily move twice, as change in percentage points and as change_bps in basis points.

Number types matter too. REST responses send JSON numbers. The WebSocket stream sends crypto, forex and stock prices as strings ("bid":"82849.99"), which keeps the exact digits but makes float() or Number() your job. And JSON numbers are binary floating point: one captured index snapshot carried prev_close as 7753.800020000001. Round for display, and use a decimal type when you add up money.

Timestamps: which clock is this?

Every TickerLayer price carries a Unix timestamp in milliseconds, UTC: a 13-digit integer such as 1790591112968, which is 10:25:12.968 UTC on 28 September 2026. The format is the easy part. The question to ask of every timestamp is which event it marks.

The daily bar convention catches everyone once. The US:KO bar for Friday 25 September 2026 has t = 1790294400000, which is midnight UTC, although the session ran from 13:30 to 20:00 UTC. Nothing is wrong: the stamp names the session date, not the closing bell. The guide to Unix timestamps in milliseconds has conversion code for every language and the time-zone traps that come with it.

Real-time, delayed and end-of-day data

Real-time data is delivered as soon as practical after the market event, with no deliberate hold. Delayed data is held back on purpose, commonly by 15 minutes, because many licences price live display far above delayed display. End-of-day data arrives once, after the close. A real-time market data API means the first category; the rest of the latency conversation is about how far below a second you truly need to be.

TickerLayer's API is real-time, with two qualifications worth stating. The prices are derived and indicative rather than official exchange data. And for stocks, latency varies by market, so a few markets are delayed. The public symbol pages on this website show prices 15 minutes delayed; the API does not.

REST or WebSocket: pick per job

A WebSocket session is short to set up. Connect to wss://stream.tickerlayer.com/?apiKey=..., wait for the ready frame, and send one message:

{"action": "subscribe", "channels": ["crypto.quotes", "crypto.trades"], "symbols": ["BTCUSD"]}

The server confirms with a subscribed frame and starts pushing quotes and trades. For symbols with a recent value it first sends that last-known value marked "snapshot": true, so a screen is not blank while it waits for the first tick; add "snapshot": false for live ticks only. The trade-offs, with the request arithmetic worked through, are in WebSocket vs REST.

Authentication, limits and errors

Send the key in the x-api-key header

Market data APIs authenticate with a key, and the key has to travel somewhere. TickerLayer REST expects it in the x-api-key header on every request. A custom header keeps the key out of URLs, which end up in server logs, browser history and proxy caches; that is also why the older ?apiKey= query form is accepted on REST only as a legacy fallback. The WebSocket upgrade is the exception: browsers cannot set custom headers on a WebSocket, so the stream takes the key as ?apiKey= on the connection URL.

import os

import requests

resp = requests.get(
    "https://api.tickerlayer.com/stocks/snapshot/US:KO",
    headers={"x-api-key": os.environ["TICKERLAYER_API_KEY"]},
    timeout=10,
)
resp.raise_for_status()
snap = resp.json()
print(f'{snap["symbol"]} last {snap["last_price"]} ({snap["change_percent"]:+.2f}% vs {snap["prev_close"]})')

const res = await fetch("https://api.tickerlayer.com/stocks/snapshot/US:KO", {
  headers: { "x-api-key": process.env.TICKERLAYER_API_KEY },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const snap = await res.json();
console.log(`${snap.symbol} bid ${snap.bid} ask ${snap.ask} last ${snap.last_price}`);

US:KO last 88.16 (+0.40% vs 87.81)
US:KO bid 88.15 ask 88.2 last 88.16

Keep the key on a server. A key embedded in a web page is visible to anyone who opens the developer tools, and browser calls to the REST API are accepted only from approved origins anyway.

Errors and limits to handle on day one

Every authenticated response carries X-RateLimit-Limit and X-RateLimit-Remaining for the current one-second window, so a well-behaved client can pace itself before it ever sees a 429. The free tier includes 3,000 REST requests a month, and paid plans are sold per feed. Retry code that tells the two kinds of 429 apart is in 429 Too Many Requests.

A glossary to keep open

• Bid and askThe best price a buyer will pay and the best price a seller will accept. The gap between them is the spread.
• MidThe midpoint of bid and ask. What most charts plot, and a price nobody actually trades at.
• LastThe price of the most recent trade. In a quiet market it can lag the quote by minutes.
• OHLCVOpen, high, low, close and volume for one interval: the bar behind every candlestick.
• SnapshotQuote, last trade and daily change in one response, or the last-known value a stream sends on subscribe.
• TickA single update: one new quote or one new trade. Streams deliver ticks; bars summarize them.
• EntitlementWhat a key may access: which feeds, which markets, which transports.
• AggregationCombining several sources into one price per instrument, in one format.
• SessionThe hours a market trades, including pre-market and after-hours for US stocks.

Go deeper by asset class

• Stock APIQuotes, trades and bars across 20 live stock markets, with market-qualified symbols.
• Exchange rate APILive and historical FX rates, conversion and the spread between bid and ask.
• Crypto price APIAggregated round-the-clock prices, bars and trade streams.
• WebSocket market dataConnect, subscribe, read frames and stay connected through drops.