# TickerLayer: Full API Reference for LLMs and AI Agents > TickerLayer is a developer-first market data API offering REST and WebSocket access to derived, indicative, non-exchange-sourced data across stocks, forex, crypto, indices, ETFs, commodities, and government bond yields. One API key, one consistent schema, all asset classes. This file is the complete, authoritative public API surface. If an endpoint is not listed here, it does not exist. Do not invent paths. ## Critical rules for AI agents (read first) 1. DO NOT invent endpoint paths. There is no `/api/v1/...`, no `/v2/...`, no `/quotes?symbol=...` query style. The exact paths are listed below and nothing else exists. 2. The REST base URL is `https://api.tickerlayer.com` (no path prefix, no version segment). 3. Authentication for REST is the `x-api-key` header. A legacy `?apiKey=` query parameter is still accepted for compatibility but must not be used in new integrations (it leaks the key into logs and browser history). There is no `Authorization: Bearer` on REST. 4. Symbol formats differ by asset class (see Symbol conventions). Stocks ALWAYS need an ISO alpha-2 country prefix: `US:KO`, never plain `KO`. 5. Timestamps are Unix epoch milliseconds unless a field name says otherwise. Market-status timestamps are ISO-8601 UTC. 6. A `403` response means the account plan does not include that data; the fix is upgrading the plan, not retrying other paths. 7. Prefer the MCP server for agent integrations: https://tickerlayer.com/docs/mcp 8. x402 is a separate accountless, REST-only pay-per-request surface. Production uses Base mainnet USDC; integration testing uses the isolated Base Sepolia sandbox. ## Base URLs - REST: `https://api.tickerlayer.com` - WebSocket: `wss://stream.tickerlayer.com/?apiKey=YOUR_API_KEY` - Hosted MCP (Streamable HTTP): `https://mcp.tickerlayer.com/mcp` with `x-api-key` header or OAuth 2.1 sign-in - x402 production: `https://x402.tickerlayer.com` (Base mainnet, USDC) - x402 sandbox: `https://x402-testnet.tickerlayer.com` (Base Sepolia, test USDC) - OpenAPI 3.1 spec of every REST endpoint: `https://tickerlayer.com/openapi.json` - Postman collection: https://www.postman.com/tickerlayer/tickerlayer-market-data-api - JavaScript and TypeScript client: `npm install tickerlayer` (https://www.npmjs.com/package/tickerlayer), REST and WebSocket, reconnects and resubscribes on its own - Python client: `pip install tickerlayer` (https://pypi.org/project/tickerlayer/), sync and async REST plus the WebSocket stream as an async iterator, Python 3.9+ ## Authentication REST: send the key on every request: curl "https://api.tickerlayer.com/crypto/quote/BTCUSD" -H "x-api-key: YOUR_API_KEY" WebSocket: the key goes in the upgrade URL query string: wss://stream.tickerlayer.com/?apiKey=YOUR_API_KEY Keys are issued in the dashboard: https://tickerlayer.com/dashboard (shown once on creation). ## Symbol conventions - Crypto: concatenated pair, e.g. `BTCUSD`, `ETHUSD`, `SOLUSD` - Forex: concatenated pair, e.g. `EURUSD`, `GBPJPY`, `USDTRY` - Commodities: reference codes, e.g. `XAUUSD` (gold), `XAGUSD` (silver), `WTIUSD`, `BRENTUSD`, `NGASUSD` (natural gas) - Indices: generic codes with NO market prefix, e.g. `US500`, `US100`, `US30`, `DE40`, `JP225`, `HK33`, `CN300`, `KR200`. A prefixed form like `HK:HK33` is INVALID. Indices are served ONLY by the indices endpoints: requesting an index through the stocks endpoints (`US:SP500`, `US:KOSPI`, `US:NYSE`) returns 404. The prefix rule applies to exchange-listed instruments (stocks, ETFs), not to indices. - ETFs: ETF-style codes, e.g. `US500ETF` - Stocks: `COUNTRYCODE:TICKER` with ISO alpha-2 country prefix, for example `US:KO`, `US:JPM`, `DE:BMW`, `TR:THYAO`, `SA:2222` (Saudi Arabia). A bare ticker like `KO` is INVALID. - Futures CFDs: a product base plus a suffix. `WTIUSD.DEC26` is one contract month, `WTIUSD.C1` to `WTIUSD.C3` the front-month chain, `WTIUSD.R5`, `.R5C`, `.CYCLE` and `.NOTICE` the roll series. Bases: `WTIUSD`, `BRENTUSD`, `NGASUSD`, `XAUUSD`, `XAUUSD247`, `XAGUSD`, `COPPERUSD`, `ALUMINUMUSD`, `XPDUSD`, `CORNUSD`, `WHEATUSD`, `SOYBEANUSD`, `LIVECATTLEUSD`, `UST2Y`, `UST5Y`, `UST30Y`, `SOFR3M`, `US500`, `US100`, `US2000`. Exchange root and month codes are INVALID: use the bases above. - Bonds: `COUNTRY:TENOR`, for example `US:10Y`, `US:2Y`, `US:3M`, `DE:10Y`, `FR:10Y`, `IT:10Y`, `ES:10Y`, `UK:10Y`. US supports 1M,3M,6M,1Y,2Y,3Y,5Y,7Y,10Y,20Y,30Y; DE/ES/FR/IT/UK support 1Y,2Y,3Y,5Y,10Y,30Y. Discover valid symbols at runtime with the symbols endpoints below, or browse https://tickerlayer.com/symbols ## REST endpoints The same uniform pattern applies to these asset segments: `crypto`, `forex`, `stocks`, `indices`, `etfs`, `commodities`, `perpetuals`. Replace `{asset}` with one of those exact segment names. Perpetuals additionally expose `GET /perpetuals/mark/:symbol` and need the Perpetuals plan. ### Latest quote GET /{asset}/quote/{symbol} Example response (crypto): {"symbol":"BTCUSD","bid":64361.86,"ask":64361.87,"bid_size":3.84,"ask_size":0.93,"timestamp":1783678921804} ### Last trade GET /{asset}/trade/last/{symbol} Returns the most recent trade: price, size, timestamp. ### Snapshot (best single call for "how is X doing") GET /{asset}/snapshot/{symbol} Example response: {"symbol":"BTCUSD","bid":64361.86,"ask":64361.87,"last_price":64361.86,"last_size":0.00029,"last_timestamp":1783678921804,"prev_close":63230,"change":1131.86,"change_percent":1.79} ### Previous completed bar GET /{asset}/agg/{symbol}/prev GET /{asset}/agg/{symbol}/prev?interval=1m Returns the previous completed daily OHLCV bar. - `interval` (optional): `1m|5m|15m|1h|4h|1d`. Returns the most recently *settled* bar at that interval instead of the daily bar. A bar counts as settled once it has closed and a short lag has passed, so the boundary sits away from the round minute and small clock differences between callers do not change which bar comes back. - With `interval`, the response also carries `interval`, `bar_start`, `bar_end` and `as_of`, and the `Cache-Control` / `ETag` headers mark exactly when the value can next change. Pin `bar_start` if you need several parties to agree on one specific bar. - The bar is the same one the historical range endpoint returns for that window, so an audit can re-fetch that exact window and compare against the same source. (Providers do occasionally revise a published bar; the `ETag` changes when they do.) While the market is closed the last real bar is returned, still labelled with its own `bar_start`. Example: `GET /stocks/agg/US:KO/prev?interval=1m` ### Historical aggregate bars GET /{asset}/agg/{symbol}/{multiplier}/{timespan}/{from}/{to} - `multiplier` + `timespan` valid pairs: `1|5|15` with `minute`; `1|4` with `hour`; `1` with `day` - `from`, `to`: UTC dates `YYYY-MM-DD`, inclusive, `to >= from` - Query params: `limit` (default 500, max 5000), `offset` (default 0), `sort` (`asc`|`desc`, default `desc`) - History depth is the same on every plan; it depends on the symbol and the bar size. Example: `GET /crypto/agg/BTCUSD/1/day/2026-06-01/2026-06-30?sort=asc` ### Symbol discovery GET /symbols/catalog # every symbol we cover, all asset classes, same for every key, paged GET /symbols # merged catalog across crypto, forex, commodities, ETFs, indices GET /{asset}/symbols # per asset class (also works for stocks and cfds) POST /symbols/coverage # resolve a pasted symbol list against the catalog `GET /symbols/catalog` answers "what do you cover" for any key, Free included; the per asset class lists answer "what can my key read" (`/stocks/symbols` lists only the stock markets the key includes, so `?market=IN` on a key without India is an empty list). Query params, all optional: `asset_class` (`stocks|forex|crypto|indices|etfs|commodities|perpetuals|bonds`), `market` (the `CC` of `CC:SYMBOL` codes, e.g. `US`, `IN`; stocks and bond yields have one, the bare classes have `market: null`), `q` (case-insensitive text in the symbol or name, up to 64 characters), `limit` (default 100, max 1000), `offset` (default 0). Response for `?asset_class=forex&q=eurusd`: `{"results":[{"symbol":"EURUSD","name":"Euro / United States Dollar","asset_class":"forex","market":null}],"results_count":1,"total_count":1,"next_offset":null}`; a stock row carries its market (`{"symbol":"US:KO","name":"The Coca-Cola Company","asset_class":"stocks","market":"US"}`), while forex, crypto, indices, commodities and perpetuals are not tied to one country and have `market: null`. `total_count` counts every match before paging (`?asset_class=stocks&market=DE&limit=1` gives the number of German stocks covered) and `next_offset` is the `offset` of the next page, null on the last. A symbol two classes serve (`XAUUSD`) appears under both. Listing a symbol is not access to its price: a symbol outside the key's plan answers 403. One request against the monthly quota; no market data is read. Response shape: `{"data":[{"symbol":"BTCUSD","name":"Bitcoin / US Dollar","type":"crypto"}],"count":1}` `POST /symbols/coverage` takes `{"text":"KO\nEUR/USD\n0700.HK"}` (one symbol per line or comma separated, at most 100 rows and 8000 characters) and returns, per line, how it resolved: `exact`, `normalized` or `alias` count as ready and carry the canonical API symbol plus a ready-to-call REST path; `closest` and `ambiguous` return candidates for a person to confirm; `uncovered` and `unrecognized` explain themselves. The summary counts and an `integration` block (canonical symbols, REST paths, WebSocket subscribe frames) come back in the same response. Covers every asset class above plus government bond yields. Costs one request against the monthly quota and touches no market data upstream. ### Market status, sessions, holidays Commodities calendar: broad metals/energy reference, Sun 18:00 to Fri 17:00 America/New_York with a daily 17:00 to 18:00 pause; UTC follows US DST. Individual contracts and holidays may differ. Calendar status is not feed health and must not be the sole gate for consuming ticks. GET /markets/status # global overview; optional query: asset, symbol, market, at, includeSessions, includeHoliday GET /markets/status/bulk # query: items (1 to 25 comma-separated asset:symbol pairs, e.g. stocks:US:KO), optional at GET /markets/sessions # optional query: asset, symbol, market, date GET /markets/holidays # optional query: asset, symbol, market, year, start, end Example: `GET /markets/status?asset=stocks&market=US&includeSessions=true` Status responses use ISO-8601 UTC timestamps and report open/closed/pre-market/post-market phases per region. ### Government bond yields GET /bond/last/{symbol} GET /bond/snapshot/{symbol} GET /bond/curve/{country} Note the singular `bond` segment. Example: `GET /bond/last/US:10Y` returns {"symbol":"US:10Y","rate":4.54,"unit":"percent","date":"2026-07-09","timestamp":1783555200000} `GET /bond/snapshot/US:10Y` adds the previous published observation and the change between them on top of the same fields: {"symbol":"US:10Y","rate":4.54,"unit":"percent","date":"2026-07-09","timestamp":1783555200000,"prev_rate":4.51,"prev_date":"2026-07-08","prev_timestamp":1783468800000,"change":0.03,"change_bps":3,"change_percent":0.6652} `prev_*` and change fields are null when only a single observation is available. `change` is in percentage points, `change_bps` in basis points, `change_percent` relative to `prev_rate`. Compare `date` with `prev_date` for the interval the change covers: consecutive business days for most curves, previous auction for the short-term Italy tenors, which publish monthly. `GET /bond/curve/{country}` returns a country's whole curve in one call, counted as one request: `US` (1M to 30Y, 11 tenors), or `DE`, `ES`, `FR`, `IT`, `UK` (1Y to 30Y, 6 tenors). `results` holds one `/bond/snapshot` object per tenor, shortest first, each with its own dates; a tenor with no observation yet is left out, and `count` says how many came back. `GET /bond/curve/DE` (first of six entries shown): {"country":"DE","unit":"percent","count":6,"results":[{"symbol":"DE:1Y","rate":2.87,"unit":"percent","date":"2026-11-06","timestamp":1793923200000,"prev_rate":2.91,"prev_date":"2026-11-05","prev_timestamp":1793836800000,"change":-0.04,"change_bps":-4,"change_percent":-1.3746},...]} The same observation streams on the WebSocket channel `bonds.quotes` (see the WebSocket section): latest value on subscribe, then one frame per new daily observation. ### US overnight session (add-on) GET /overnight/symbols GET /overnight/quote/{symbol} GET /overnight/snapshot?symbols=US:KO,US:JPM Derived, aggregated quotes for the most traded US stocks and ETFs while the listing markets are closed, Sunday to Thursday, 20:00 to 04:00 New York time. Needs a US Stocks plan plus the overnight add-on. `GET /overnight/quote/US:KO` returns {"symbol":"US:KO","bid":62.3914,"ask":62.4367,"mid":62.4141,"session":"overnight","dispersion_bps":5.25,"timestamp":1789808856800} and answers 404 `no overnight quote available` outside the session. `GET /overnight/symbols` lists the covered symbols with `session_open`; `GET /overnight/snapshot` returns several quotes in one call, or all of them when `symbols` is left out. `?spread=full` on the quote and snapshot routes widens bid and ask to the spread quoted at night around the same mid. Reference: https://tickerlayer.com/docs/products/stocks#overnight ### Perpetual futures (24/7) GET /perpetuals/symbols GET /perpetuals/quote/{symbol} GET /perpetuals/mark/{symbol} GET /perpetuals/trade/last/{symbol} GET /perpetuals/snapshot/{symbol} GET /perpetuals/agg/{symbol}/prev GET /perpetuals/agg/{symbol}/{multiplier}/{timespan}/{from}/{to} Perpetuals is its own product: it needs Perpetuals on the account (403 `perpetuals access not enabled for your account` otherwise); `GET /perpetuals/symbols` is open to any valid key. A perpetual is a futures contract with no expiry that trades around the clock, so these routes answer on nights, weekends and holidays when the underlying stock exchange is closed. 260+ contracts; symbols look like `XAUUSDT` (gold), `TSMUSDT`, `SPYUSDT`, `US500USDT`, `EURUSDUSDT`, `BTCUSDT`. Each symbol reports `instrument_type: "perpetual"` and an `underlying_asset_class` of `equity`, `etf`, `commodity`, `index`, `forex`, `pre_ipo` or `crypto`; filter the list with `?underlying=commodity`. Every price is a composite: the bid is the median of the live source bids and the ask is the median of the live source asks across multiple independent market sources, so the book is never crossed. `source_count` is the number of sources behind the value. Example: `GET /perpetuals/quote/XAUUSDT` returns {"symbol":"XAUUSDT","bid":4316.31,"ask":4316.36,"bid_size":118.049,"ask_size":51.115,"source_count":6,"timestamp":1789640504033} `GET /perpetuals/mark/XAUUSDT` returns the composite mark price, the reference a perpetual market uses to value positions: {"symbol":"XAUUSDT","mark_price":4316.244,"source_count":6,"timestamp":1789640505932} `GET /perpetuals/trade/last/{symbol}` returns `{"symbol","price","size","side","timestamp"}` with `side` of `buy`, `sell` or null. The trade tape runs on demand: the first call for a quiet contract can answer 404 `no trade available`, and the contract then stays on the tape for ten minutes. `GET /perpetuals/snapshot/{symbol}` returns quote, mark and last trade in one call (`bid`, `ask`, `bid_size`, `ask_size`, `mark_price`, `last_price`, `last_size`, `source_count`, `timestamp`, `mark_timestamp`, `last_timestamp`, `prev_close`, `change`, `change_percent`) and never starts the trade tape. `prev_close` is the close of the last completed UTC daily bar, and `change` / `change_percent` measure the composite mid price against it; a perpetual has no session, so the day turns at 00:00 UTC. The same values stream on `perpetuals.quotes`, `perpetuals.marks` and `perpetuals.trades` (see the WebSocket section). OHLCV bars follow the shared aggregates contract: `GET /perpetuals/agg/{symbol}/{multiplier}/{timespan}/{from}/{to}` with `1|5|15/minute`, `1|4/hour` or `1/day`, UTC dates `YYYY-MM-DD`, `?limit=` (default 500, max 5000), `?offset=`, `?sort=asc|desc`, and the response `{"symbol","results_count","total_count","results":[{"o","h","l","c","v","t"}],"next_offset"}`. `GET /perpetuals/agg/{symbol}/prev` returns the last completed UTC daily bar, or with `?interval=1m|5m|15m|1h|4h|1d` the most recently settled bar at that interval. Bars are built from traded prices on the contract's primary market source (one source per contract, so a series is never stitched); `v` is that source's volume in base units, not the whole market. Maximum span per request is 7 days for 1 minute bars, 31 for 5 minute, 90 for 15 minute, 365 for 1 hour and 730 for 4 hour; a few contracts carry shorter windows and the 400 message states the limit. History starts when the contract was first listed, which for many perpetuals is recent, and weekends are in the series because the contract traded through them. Source-level access (an operator-granted add-on for accounts that run their own aggregation) adds the raw per-source rows next to the composite: `?sources=true` on quote, mark and last trade returns a `sources` array whose rows carry `source_id`, `venue_symbol`, `native_currency` and `market_type` (`perpetual` or `spot`), and the stream adds `venue_quote` and `venue_mark` frames on the same channels. A source row's `timestamp` is the source's own event time, so a quiet book shows an old timestamp while the row is alive. A row is live while its book changed within 90 seconds; past that an unchanged book stays live only while the same source's mark keeps arriving, never longer than 30 minutes; after a source connection drops, goes silent or skips a sequence its rows are withdrawn 5 seconds later. A withdrawn row leaves REST at once, and on the stream it is announced by `{"type":"venue_status","channel":"perpetuals.quotes","asset":"perpetuals","symbol":"XAUUSDT","source_id":"pv_02","venue_symbol":"XAUUSDT","native_currency":"USDT","market_type":"perpetual","status":"withdrawn","ts":}`; the next `venue_quote` or `venue_mark` for that source and symbol means it is back. `GET /perpetuals/sources/status` returns `{"timestamp","thresholds":{"withdraw_after_lane_loss_ms","fresh_book_ms","quiet_book_max_ms"},"sources":[{"source_id","role","status","symbols_listed","symbols_live","last_update","oldest_live_update"}]}` with `status` of `up` (at least 90% of listed symbols live), `degraded` or `down`, computed on every request. `GET /perpetuals/symbols?sources=true` lists, per symbol, every deliverable source row with `in_composite`; rows with `in_composite: false` (spot reference books, and a source that prices a contract in a different unit) are delivered raw and never enter the composite. `source_id` values are permanent. Without the add-on these answer 403 `source-level access not enabled for your account`. USD values are opt-in: `usd=true` next to `sources=true` on REST, or `"usd": true` in a perpetuals subscribe message, adds `usd_bid` and `usd_ask` (quote rows), `usd_mark_price` (mark rows) or `usd_price` (trades with source fields), plus `usd_rate`, the rate applied from `native_currency` to USD (the mid of a USD-quoted spot market for that stablecoin); every USD field is the native value times `usd_rate`, and the native fields never change. With no fresh rate the USD fields are `null`, never an assumed 1; the USDTARS reference book always carries `null`. The most recent subscribe for a symbol decides; composite frames never carry USD fields. `usd` on any other channel fails with `UNSUPPORTED_USD`, a value that is not `true` or `false` with `INVALID_USD`. With source-level access, `"quote_mode": "tick_by_tick"` in a subscribe with `perpetuals.quotes` sends every change to the top of book of each source (price or size) as its own `venue_quote` frame, in the order the source published it, instead of the conflated rows; `"conflated"` (the default) or a later subscribe without `quote_mode` goes back, and the most recent subscribe for a symbol decides. It changes `venue_quote` frames only: composite quotes, marks and trades are unchanged. Tick-by-tick frames add `seq`, an integer that starts at a large arbitrary value (it needs 64 bits and fits a JSON number exactly), goes up by one with every change of that source's book and never goes down; compare it only within one source and symbol: a bigger step means changes were missed (frames a connection could not take, which are skipped rather than queued; a source that dropped; a restart on our side), the same value again means the same book (for example back after a withdrawal); resync with `?sources=true` on REST or a new subscribe. When a symbol starts tick by tick, the current book of each source comes first, flagged `"snapshot": true`, then every change after it; a symbol already streamed gets that restatement whenever it switches mode, either way, even with `"snapshot": false`, and so does every tick-by-tick symbol after a restart on our side or when source-level access comes back, while a new symbol with `"snapshot": false` gets no rows and starts with the next change. A withdrawal still arrives as `venue_status`, and the next `venue_quote` means the book is back even when its values did not change. A symbol streams tick by tick on a limited number of connections per account and across the service; past that, or without source-level access, the subscribe still succeeds, those symbols come conflated, and a system message `{"type":"system","event":"quote_mode","channel":"perpetuals.quotes","quote_mode":"conflated","code":"QUOTE_MODE_LIMIT","message":"...","symbols":[...],"scope":"account"|"service","limit":}` (or `code` `QUOTE_MODE_UNAVAILABLE`, no `scope` or `limit`) follows the acknowledgement. A capped symbol switches to tick by tick by itself once a connection frees up, announced by `{"type":"system","event":"quote_mode","channel":"perpetuals.quotes","quote_mode":"tick_by_tick","symbols":[...]}`. Every tick-by-tick subscribe is answered with `{"type":"system","event":"quote_mode","channel":"perpetuals.quotes","quote_mode":"tick_by_tick","symbols":[...]}` for the symbols that got it, plus the conflated message for any that did not; a `quote_mode` message can also arrive on its own (a capped symbol switching, source-level access ending, a reconnect on our side); the latest one for a symbol is its mode, and a `venue_quote` with `seq` is a tick-by-tick frame. `quote_mode` without `perpetuals.quotes` or next to a non-perpetuals channel fails with `UNSUPPORTED_QUOTE_MODE`; any other value with `INVALID_QUOTE_MODE`. Normalized rows: with source-level access, `"format": "normalized"` in a subscribe with `perpetuals.quotes` and/or `perpetuals.marks` renders every source row as one flat row priced in USD instead of `venue_quote` / `venue_mark` (composite frames and trades unchanged): `{"exchange":"pv_01","symbol":"XAUUSD","type":"top_of_book","bid":"4314.595062","mid":"4314.635046","ask":"4314.67503","timestamp":"2026-10-10T12:00:03.477Z","quote":"USD","quote_source":"USDT","venue_symbol":"XAUUSDT","fx_rate":"0.999605","fx_sources":["fx_01","fx_02"],"fx_timestamp":"2026-10-10T12:00:00.012Z","contract":"XAUUSDT","channel":"perpetuals.quotes"}`. `exchange` is the source id, `symbol` the source's base with USD (`MSFTUSD`, `xyz:MSFTUSD`, `MSFT-USD-SWAP`; USD/JPY as `USDJPYUSD`, `xyz:USDJPYUSD`), `type` `top_of_book`, `mark_price` (a mark carries its price as bid, mid and ask) or `impact_price`, prices are USD strings with bid <= mid <= ask, `timestamp` is the source's event time in ISO 8601 with milliseconds, `quote_source` the stablecoin the source quotes in, `fx_rate` the stablecoin/USD rate applied, `fx_sources` the ids of the reference markets behind it and `fx_timestamp` the oldest reading behind it. A new row goes out only while the reference markets agree on the rate and every reading behind it is at most 60 seconds old; otherwise nothing is sent. A repeat is an exact copy of a row the connection was sent, its rate included. Options: `exchanges` (source ids to keep), `heartbeat_ms` (5000 by default, 1000 to 60000, 0 for none), `heartbeat_cap_ms` (300000 by default, 10000 to 1800000), and `impact` / `impact_usd` for impact prices (below). A top of book with no real update for `heartbeat_ms` is sent again exactly as it was plus `heartbeat_at` (send time); `timestamp` never moves, so `heartbeat_at` minus `timestamp` is the price age, and repeats stop once it reaches `heartbeat_cap_ms`, or at once when the row is withdrawn or the subscription changes; without a rate, or while the source is not delivering, they pause and resume inside the cap; marks are never repeated, `heartbeat_at` never appears on a new update, and the format has no status rows (a withdrawn row, a source that is down and a lost rate are silence). The snapshot on subscribe, restatements and a book seen again after a withdrawal or a restart on our side are repeats too (`heartbeat_at` and `"snapshot": true`; a top of book older than the cap is not sent). A repeat with `"snapshot": true` may hold prices the connection was not sent yet (a book that moved during a pause): take its values; a repeat without it is always an exact copy of the last row sent. With `"snapshot": false`, quiet books start repeating one interval after the subscribe, the first time with `"snapshot": true`. Spot reference books have no normalized rows. A source that quotes a contract in another unit (`in_composite: false`) is delivered in that unit. Impact prices: `"impact": true` in a normalized subscribe with `perpetuals.quotes` adds, per source, `type: "impact_price"` rows with `impact_usd`: `bid` is the average price of selling `impact_usd` US dollars (one of 1000, 5000, 10000, 25000, 50000, 100000; 10000 by default) walked through that source's own book best level first, `ask` the average price of buying it, fees not included, sized in US dollars at the same agreed rate the prices are converted with; a side the book cannot fill at that size gives no row (never extrapolated), bid is at or below the best bid and ask at or above the best ask, `timestamp` is the source's time of the book it was computed from, a row goes out when the impact price moves, a quiet impact price is repeated like the top of book (`heartbeat_at` every `heartbeat_ms`, until `heartbeat_cap_ms` after its `timestamp`; the snapshot on subscribe carries them as repeats), and a book that is lost, stops following the source or no longer fills the size is silence (its repeats stop). Impact prices are kept for a set of source instruments, flagged `impact: true` in the listing below; for a symbol without one the subscribe goes on and `{"type":"system","event":"format","code":"IMPACT_UNAVAILABLE","message":"...","symbols":[...]}` names it. Full view: `"view": "full"` next to `"format": "normalized"` keeps every field of those rows with the same meaning and adds `bid_size` and `ask_size` (top of book, source units), `mark_price` (mark rows), two new row types on `perpetuals.marks`, `index_price` (the source's index of the contract in `index_price`, repeated in bid, mid and ask; an index published in US dollars has `quote_source` `USD` and no rate fields) and `funding_rate` (`{"exchange","symbol","type":"funding_rate","funding_rate","funding_time","funding_interval","timestamp","venue_symbol","contract","channel"}`: `funding_rate` a decimal per 8 hours whatever the source's interval, `funding_time` the next settlement in ISO 8601, `funding_interval` the source's own such as `"1h"`, `"4h"`, `"8h"`; no prices or quote fields), and on impact rows `impact_price_bid`, `impact_price_ask`, `notional_usd`, `filled_usd_bid`, `filled_usd_ask`, with bid, mid and ask the best levels the sweep started from; a side the visible book cannot fill is priced on what it holds and its `filled_usd_*` says how much that was (without the view such a row is not sent), always `impact_price_bid` <= bid < ask <= `impact_price_ask`. Every row type repeats like the top of book in the full view; an index price or funding rate that stops arriving is silence. `"usd": false` with the view sends the same rows in the source's own symbol and quote currency, unconverted, without rate fields and without waiting for a rate; impact prices are USD rows, so with `impact` the rows stay in USD and the `format` message does not carry `"usd":false`. The `format` message adds `"view":"full"` (and `"usd":false` for native rows); a message without `view` means the plain normalized rows, and any other `view` value gets those and never fails the subscribe. The subscribe is answered with `{"type":"system","event":"format","format":"normalized","symbols":[...]}` (plus `impact_usd` when impact prices were asked for); without source-level access it still succeeds on the composite frames with `code` `FORMAT_UNAVAILABLE`. Errors: `INVALID_FORMAT`, `INVALID_EXCHANGES`, `INVALID_HEARTBEAT`, `INVALID_IMPACT` (`impact` not a boolean, `impact_usd` not one of the sizes or without `"impact": true`), `UNSUPPORTED_FORMAT` (non-perpetuals channel), `UNSUPPORTED_FORMAT_OPTION` (options without `format`). REST: `GET /perpetuals/quote/{symbol}?format=normalized` and the same on `/perpetuals/mark/{symbol}` return `{"symbol","format":"normalized","rows":[...]}` with the same rows (no `heartbeat_at`), `&exchange=pv_01` for one source; `GET /perpetuals/symbols?format=normalized` lists every source instrument as `{"exchange","symbol","venue_symbol","contract","base","quote":"USD","quote_source","instrument_type":"perpetual","underlying_asset_class","in_composite","impact"}` (`impact`: whether impact prices are kept for it; impact prices are on the stream only). `GET /perpetuals/sources/status` also returns `fx` (per stablecoin, the rate in use: `rate`, `fx_sources`, `fx_timestamp` in ISO 8601, or `unavailable` with a `reason`) and `normalization` (the share of source prices that had an agreed USD rate when they happened, per source, since our last restart and month to date). Data notice for perpetuals: TickerLayer is a data provider and does not list, offer, broker or trade any contract. A perpetual is a leveraged derivative, not the underlying: it carries no ownership or shareholder rights, and its price can differ materially from the underlying, most of all while the underlying market is closed. Composite quotes and mark prices are calculated reference values, not executable prices, not any venue's official mark, index, funding or settlement price, and not a regulated benchmark; do not settle, margin, liquidate or value positions on them without your own validation and a written agreement. Names and tickers identify what a contract references and imply no affiliation. Perpetual futures are restricted in some jurisdictions; compliance is the user's responsibility. Full text: https://tickerlayer.com/market-data-disclaimer#perpetuals ### Futures CFDs (contract months, chain and roll series) GET /futures/products GET /futures/contracts?base={base} GET /futures/roll-calendar/{base}?months={1-36} GET /futures/quote/{symbol}?rolls={methods} GET /futures/quotes?symbols={symbol},{symbol} GET /futures/curve/{base} GET /futures/agg/{symbol}/{multiplier}/{timespan}/{from}/{to} Futures CFDs are reference prices that TickerLayer calculates with its own methodology for listed futures markets in energy, metals, agriculture, rates and US equity indices: one price per contract month, chain position or roll series. Products, contracts and the roll calendar answer any valid key; quote, quotes, curve and bars need Futures CFDs on the account (403 `futures access not enabled for your account` otherwise). Futures CFDs is sold self-service: Individual 219 USD and Business 849 USD a month (https://tickerlayer.com/pricing?feed=futures). Symbols: `WTIUSD.DEC26` is one delivery month, listed while carried (`GET /futures/contracts` lists them). `WTIUSD.C1`, `.C2` and `.C3` are the three nearest months of the product's cycle (`chain_months`), raw prices, never adjusted; a month leaves `C1` when the session of its roll date opens, 18:00 New York the evening before. Four roll series blend the chain front and the next month as `(1 - weight) * front + weight * next`: `.R5` steps 0.2 at each of five window session closes (business days 5 to 9 of the roll month), `.R5C` rises continuously through the same window, `.CYCLE` grows by 1/n each weekday across the whole cycle since the previous front's roll date, `.NOTICE` switches from 0 to 1 on the first notice date (the last weekday of the month before the contract month). Unknown base or form: 404 `unknown symbol`. A known product without a price: 404 `no price for this symbol`. Prices: the bid is the median of the live input bids and the ask the median of the live input asks, `price` is the mid. A month whose own book is empty or wider than 1% of its mid is never priced at that mid: it is carried from the nearest month of the same product with a usable book, at their spread the last time both had one (none when never seen), kept inside its own bid and ask, and flagged `estimated: true` with `estimated_from` naming that month, `live: false` and that month's `timestamp`; every other quote has `estimated: false`. `live: false` means the last price is held (daily break, weekend); read `timestamp`. `unit` is the product's quoting unit (`USD per barrel`, `US cents per bushel`, `points of par`, `100 minus the rate` for `SOFR3M`, `index points`); prices are never converted. `transaction_time_us`, `ingress_time_us` and `publish_time_us` are microsecond times of the event, our receipt and the response. Example: `GET /futures/quote/XAUUSD.C2` returns {"symbol":"XAUUSD.C2","kind":"chain","base":"XAUUSD","name":"Gold","unit":"USD per troy ounce","contract":"XAUUSD.DEC26","contract_month":"2026-12","rank":2,"last_trade_date":"2026-12-29","roll_date":"2026-12-29","first_notice_date":"2026-11-30","market_status":"open","trading_day_of_month":17,"trading_days_in_month":22,"bid":4012.8,"ask":4013.1,"price":4012.95,"spread":0.3,"bid_size":1,"ask_size":2,"volume":839,"live":true,"estimated":false,"timestamp":1792778642388,"transaction_time_us":1792778642388000,"ingress_time_us":1792778642624000,"publish_time_us":1792778642819000} A roll series (`GET /futures/quote/US500.R5`) adds `method`, `weight` (share of the next month, 0 to 1), `front`, `next`, `front_price`, `next_price`, `front_estimated` (true when the front leg was carried from a neighbouring month) and `next_estimated` (true when the next leg was carried as the front plus the last spread), and on `.R5`/`.R5C` `roll_window_start` and `roll_window_end`; its `bid_size` and `ask_size` are null. Opt-in `?rolls=r5,cycle` (values `r5`, `r5c`, `cycle`, `notice`, `all`; anything else is 400) adds `"rolls":{"r5":{"price","bid","ask","weight"},"cycle":{...}}` to every `.C1` in the answer; without it the payload is unchanged. `GET /futures/quotes?symbols=` takes 1 to 50 symbols and lists those without a price in `missing`. `GET /futures/curve/{base}` returns every month with a usable book of its own (never an estimated one) nearest first with `carry_annualized` (annualized log carry from the previous month; null on the first month and on `SOFR3M`). `GET /futures/roll-calendar/{base}` returns each upcoming rotation with `front`, `next`, `roll_window_start`, `roll_window_end`, `roll_window_days`, `cycle_start`, `first_notice_date`, `last_trade_date` and `rotation_at`. `GET /futures/products` returns `base`, `name`, `group`, `unit`, `chain_months`, `market_hours`, `chain`, `rolls` and `contracts` per product, and `term_rates` where the product has one. One-month term SOFR: `SOFR1M.TERM` (on `GET /futures/quote`, `/futures/quotes` and `futures.quotes`) is the one-month term SOFR rate implied by the SOFR futures, in percent per annum, calculated by TickerLayer (not an official benchmark fixing): `price` is the live rate and `fixing` the day's value, ready at 15:00 New York on US bond market days; `kind: "term"`, no bid, ask or bars. Historical bars: `GET /futures/agg/{symbol}/{multiplier}/{timespan}/{from}/{to}` takes any symbol form with `1|5|15/minute`, `1|4/hour` or `1/day`, `?limit=` (default 500, max 5000), `?offset=`, `?sort=asc|desc` (default desc), and returns `{"symbol","results_count","total_count","results":[{"o","h","l","c","v","t"}],"next_offset"}` with `v` always null. A contract month returns its own bars. A chain bar is on the month the chain held at that bar and adds `contract`. A roll bar blends the front and next month the way the live series does and adds `weight` (the next month's share at the bar's close), `front` and `next`; on a roll window day the daily bar opens with the session's weight and closes with the weight once the session closed, so `.R5` and `.R5C` close level while `.R5C` moves through the session. Intraday bars and their `from`/`to` are UTC; a daily bar is a trade date's session (18:00 to 17:00 New York) stamped at the trade date's 00:00 UTC, and `from`/`to` are trade dates. Bars come from each month's own prices: the mid of a usable book, or the traded price where no book was recorded. 1-minute bars cover each product's three chain months from 2026-09-29 and are kept for 13 months; daily bars cover every listed month up to two years back. A chain or roll bar is left out where a month it needs has no bar. Maximum span per request: 31 days for 1, 5 and 15 minute bars, 62 for 1 hour, 92 for 4 hour and 5000 for daily; longer is 400 with the limit in the message. A range without bars is 200 with empty `results`. Example: `GET /futures/agg/WTIUSD.R5C/4/hour/2026-10-08/2026-10-08?sort=asc&limit=2` returns {"symbol":"WTIUSD.R5C","results_count":2,"total_count":6,"results":[{"o":88.8252173913,"h":89.8135710145,"l":88.570915942,"c":89.6507347826,"v":null,"t":1791417600000,"weight":0.25202898550724634,"front":"WTIUSD.NOV26","next":"WTIUSD.DEC26"},{"o":89.6556521739,"h":91.5207130435,"l":89.5546826087,"c":91.3815652174,"v":null,"t":1791432000000,"weight":0.28695652173913044,"front":"WTIUSD.NOV26","next":"WTIUSD.DEC26"}],"next_offset":2} Data notice for Futures CFDs: they are calculated reference prices, not futures contracts, not executable, and not the official settlement, closing or index price of any market. TickerLayer does not list, offer, broker or clear any contract and is not affiliated with any trading venue, index provider or benchmark administrator. Full text: https://tickerlayer.com/market-data-disclaimer#futures ## Stock fundamentals (REST only) Company reference and share-structure data for US and EU stocks (markets: US, DE, ES, FR). Requires the Fundamentals permission on the account, which is separate from the market-data products. GET /fundamentals/stocks/{symbol} GET /fundamentals/stocks?symbols=US:KO,US:PG GET /fundamentals/stocks?market=US&cursor={symbol}&limit={n} (market: US, DE, ES or FR) `GET /fundamentals/stocks/US:KO` returns one item with everything in a single call: {"symbol":"US:KO","base_symbol":"KO","market":"US","company":"The Coca-Cola Company","exchange":"NYSE","mic":"XNYS","country":"United States","country_code":"US","sector":"Consumer Defensive","industry":"Beverages - Non-Alcoholic","security_type":"Common Stock","employees":65900,"market_cap":388735324105,"shares_total":4303000000,"free_float":3874015338,"float_ratio":0.9003,"short_interest":44821363,"short_float_ratio":0.0116,"days_to_cover":2.56,"insider_ownership":0.099,"institutional_ownership":0.686,"adv_10d":12690023,"adv_90d":15906204,"beta":0.342,"as_of":"2026-08-20T11:56:49.392Z"} Fields are omitted, never null, when a value is not reliably known. Ownership fields and the two ratios are fractions between 0 and 1, not percentages. `float_ratio` is `free_float / shares_total` and `short_float_ratio` is `short_interest / free_float`, both derived from the counts in the same item. `as_of` is the vintage of the share-structure figures; it only advances when those numbers are genuinely refreshed. Depositary receipts get an extra safeguard: the reported share count and the reported float are each cross-checked against the listing's market cap and live traded price, and each is served only in the units that trade on the listing. A figure on the wrong share base (or a stale vintage) is withheld and replaced by an ESTIMATE: `shares_listed_est` (market cap over live price) or `free_float_est` (the reported float fraction applied to the listing when the float came on the ordinary-share base, otherwise the listing count less insider ownership). A symbol never carries both a reported figure and an estimate of the same quantity, so a receipt can carry a validated `free_float` without `shares_total`, and then no `float_ratio`. Use the estimates for order-of-magnitude work such as low-float screening. When a reported float runs up to 5% above `shares_total` (two reporting dates, typically a buyback in between), `free_float` is rebuilt as `shares_total` less insider holdings instead of being withheld. Ordinary listings get the same cross-check with a wider band: when the reported share count and market cap jointly contradict the live traded price by a wide margin (a stale pair, common on micro caps that reverse-split and re-dilute), both are withheld with no substitute, because for a single-base listing neither half of a stale pair can anchor an estimate. With `?symbols=` (at most 100 per request) the response is `{"count":N,"items":[...],"missing":[...]}`, where `missing` lists requested symbols with no fundamentals coverage. Without `?symbols=` the endpoint pages one market ordered by symbol (default `US`; pick another with `?market=`): `{"market":"US","count":N,"items":[...],"next_cursor":"US:KO"}`. Pass `next_cursor` back as `cursor` to continue; the last page omits it. `limit` defaults to 500, maximum 1000. Use this for screening a market's full universe rather than calling the single-symbol endpoint per ticker. Coverage is US, DE, ES and FR stocks; page one market at a time with `?market=`. Share-structure figures refresh daily, company profile fields monthly. Short-interest fields are a US reporting concept and are typically omitted on EU items. ## Economic calendar (REST only, Fundamentals add-on) GET /fundamentals/economic-events Scheduled and released economic indicators, central bank rate decisions, government bond and bill auctions, central bank speeches and market holidays, for the US and economies worldwide (about 90 countries in a typical week). It needs the Fundamentals add-on, the same entitlement as `/fundamentals/stocks`; without it the API answers 403 `fundamentals access not enabled for your account`. Each request counts as one Fundamentals request. Served from our own store, so a request never waits on anything upstream. Query parameters, all optional: - `from`, `to`: UTC dates `YYYY-MM-DD`, `to` inclusive. Default: today through today + 7 days. With only `from` the window runs 7 days forward from it; with only `to`, 7 days back. At most 366 days per request; page longer history by date. A bad or reversed date answers 400. - `country`: comma-separated two-letter codes, e.g. `US,GB,EU`. `EU` is the euro area; `UK` is accepted for `GB`. Global events (for example world food prices) use `WW`. - `importance`: minimum level, `low` (default, everything), `medium` or `high`. - `category`: comma list of `indicator`, `rate_decision`, `auction`, `speech`, `holiday`, `other`. - `comparison`: `mom`, `qoq` or `yoy`. - `event`: exact event name, case-insensitive, e.g. `Retail Sales`. - `status`: comma list of `scheduled`, `released`, `cancelled`. Default `scheduled,released` (in sync mode, all three). - `updated_since`: unix milliseconds. Sync mode: returns entries whose served fields changed after that time, ordered by `updated_at`, cancelled entries included, with no default date window (`from`/`to` still narrow it when given). A value in seconds answers 400. - `limit`: 1 to 1000, default 500. - `cursor`: the `next_cursor` from the previous page, sent with the same parameters. Example: `GET /fundamentals/economic-events?country=US&from=2026-10-15&to=2026-10-15&importance=medium` returns {"count":2,"items":[{"id":"5a380e1d3b3e43c8","event":"Initial Jobless Claims","country":"US","currency":"USD","category":"indicator","importance":"medium","date":"2026-10-15T12:30:00Z","timestamp":1792067400000,"period":"Oct/10","reference_date":"2026-10-10","actual":199,"consensus":200,"previous":198,"previous_revised_from":197,"change":1,"change_percent":0.505,"scale":"K","status":"released","updated_at":1792067409311},{"id":"de953eb2399967f8","event":"Retail Sales","country":"US","currency":"USD","category":"indicator","importance":"high","date":"2026-10-15T12:30:00Z","timestamp":1792067400000,"period":"Sep","reference_date":"2026-09-30","comparison":"mom","actual":0.8,"consensus":0.3,"previous":1.3,"previous_revised_from":1.2,"change":-0.5,"change_percent":-38.462,"unit":"%","status":"released","updated_at":1792067408874}]} The response is `{"count":n,"items":[...],"next_cursor":"..."}`; `next_cursor` is present only when more rows exist. Items are ordered by release time (then `id`); in sync mode by `updated_at` (then `id`). Fields are omitted, never null, when there is no value. Item fields: - `id` (string): our stable id for this calendar entry; it does not change when the entry is rescheduled or its figures are revised. - `event` (string): the published name without the comparison or stage suffix, e.g. `Retail Sales`, `GDP Growth Rate`, `Initial Jobless Claims`. - `country` (string): two-letter code (`EU` euro area, `WW` global). - `currency` (string): ISO 4217 currency of the economy. - `category` (string): `indicator`, `rate_decision`, `auction`, `speech`, `holiday` or `other`. - `importance` (string): `low`, `medium` or `high`. - `date` (string): scheduled release time, ISO 8601 UTC, e.g. `2026-10-15T12:30:00Z`. - `timestamp` (number): the same time in unix milliseconds. - `all_day` (true): present on all-day entries such as market holidays. - `period` (string): the period as published, e.g. `Sep`, `Q3`, `Oct/10` (week ending Oct 10). - `reference_date` (string): end date of that period, `YYYY-MM-DD`; it carries the year the period label leaves out. - `comparison` (string): `mom`, `qoq` or `yoy` when the figure is a change over a prior period. - `release_stage` (string): `advance`, `preliminary`, `flash`, `second`, `third` or `final` for multi-stage releases such as GDP. - `actual` (number): the released figure; absent until released. - `consensus` (number): the economists' consensus forecast, when there is one. - `previous` (number): the prior period's figure as it stands at this release (already revised when this release revised it). - `previous_revised_from` (number): when this release revised the prior period, the figure before the revision. - `change` (number): `actual - previous`. For figures already in percent, `change` is in percentage points. - `change_percent` (number): `change / |previous| * 100`, rounded to 3 decimals, so its sign follows the direction of the move; omitted when `previous` is 0. - `unit` (string): `%`, an ISO 4217 currency code for money amounts, or `cf` (cubic feet). - `scale` (string): `K`, `M`, `B` or `T`; the figures are in thousands, millions, billions or trillions of `unit`. - `status` (string): `scheduled`, `released` or `cancelled` (an entry withdrawn from the calendar). Entries that carry no released figure (speeches, holidays, category `other` and some survey releases) keep `status: "scheduled"` after their time passes; use `date` to tell past from upcoming. A figure withdrawn after release returns its entry to `scheduled`. - `updated_at` (number): unix milliseconds of the last change to any field above. Incremental sync: keep the newest `updated_at` you stored, ask again with `updated_since` set to it minus 60000 (a small overlap), and page with `next_cursor`; upsert by `id` and remove entries whose `status` is `cancelled`. For a complete copy, sync without filters: an entry that stops matching a filter (a new date outside the window, a lower importance) is not reported to that filtered sync. Besides the routes listed here, the API answers unauthenticated `GET /` (identity), `GET /health` and `GET /health/live` (liveness). Everything else returns 404. ## Errors - `400`: malformed symbol, invalid interval pair, or invalid date range - `401`: missing or invalid API key - `403`: the plan does not include the requested data or feature. On stocks, ETFs, indices, commodities and bond routes the body says what is missing: `{"statusCode":403,"message":"unauthorized","error":"NOT_IN_PLAN","product":"bonds"}`, plus `market` (for example `"DE"`) on a stock; the other products name themselves in `message`. On those five, a 403 with no `error` field is an inactive key or a key not allowed REST - `404`: unknown symbol or nonexistent route - `429`: rate limit exceeded; slow down or upgrade ## WebSocket streaming Connect: `wss://stream.tickerlayer.com/?apiKey=YOUR_API_KEY` First frame after connect is always: `{"type":"system","event":"ready","ts":}` Subscribe after `ready` with a UTF-8 JSON text frame: {"action":"subscribe","channels":["crypto.quotes"],"symbols":["BTCUSD"],"snapshot":true} - Channels: `{asset}.quotes` and `{asset}.trades` for each of `crypto`, `forex`, `stocks`, `indices`, `etfs`, `commodities`, plus `stocks.agg`, `etfs.agg`, `stocks.status`, `bonds.quotes`, the three perpetuals channels `perpetuals.quotes`, `perpetuals.marks` and `perpetuals.trades`, `futures.quotes` for Futures CFDs, and `overnight.quotes` for the US overnight session add-on (21 channels total). - `bonds.quotes`: government bond yields by `CC:TENOR` symbol (`US:10Y`, `DE:10Y`). Yields are daily official observations, not ticks: the channel replays the latest observation on subscribe (`"snapshot":true`) and then sends one frame per symbol per new observation, in practice once per business day; a quiet hour is normal. Frames: `{"type":"rate","channel":"bonds.quotes","asset":"bonds","symbol":"US:10Y","rate":4.79,"unit":"percent","date":"2026-09-02","prev_rate":4.76,"prev_date":"2026-09-01","change":0.03,"change_bps":3,"change_percent":0.6303,"ts":,"timestamp":}` with the same fields as `GET /bond/snapshot`; `ts`/`timestamp` are the observation date, never the send time. - `perpetuals.quotes`, `perpetuals.marks`, `perpetuals.trades`: perpetual futures, 24/7, by contract symbol (`XAUUSDT`, `TSMUSDT`). Part of the Perpetuals Business plan. Frames use the stream dialect (string numerics, `ts`): `{"type":"quote","channel":"perpetuals.quotes","asset":"perpetuals","symbol":"XAUUSDT","bid":"4316.31","ask":"4316.36","bid_size":"118.049","ask_size":"51.115","source_count":6,"ts":}`, `{"type":"mark","channel":"perpetuals.marks","asset":"perpetuals","symbol":"XAUUSDT","mark_price":"4316.244","source_count":6,"ts":}`, `{"type":"trade","channel":"perpetuals.trades","asset":"perpetuals","symbol":"TSMUSDT","price":"423.36","size":"1.5","side":"buy","ts":}` (`side` omitted when unknown). Quotes and marks are conflated to the latest value ten times a second and replay the last known value on subscribe (`"snapshot":true`); trades never replay. Source-level accounts can take every book change of each source instead, with `"quote_mode": "tick_by_tick"`. - `futures.quotes`: Futures CFDs by contract month, chain position or roll series (`WTIUSD.DEC26`, `WTIUSD.C1`, `US500.R5`), for accounts with Futures CFDs. Frames carry the REST quote fields without `base`, `name` and `unit`, in the stream dialect (string numerics, `ts`), plus a per-symbol `seq`: `{"type":"quote","channel":"futures.quotes","asset":"futures","symbol":"WTIUSD.C1","kind":"chain","contract":"WTIUSD.DEC26","bid":"102.99","ask":"103.01","price":"103","live":true,"market_status":"open","seq":1842,"ts":,...}`. The last price is replayed on subscribe with `"snapshot":true` whatever its age. Subscribe option `rolls` (`["r5","cycle"]`, `"all"`) adds the roll fields to every `.C1` frame; the latest futures subscribe on the connection sets it, and a bad value fails with `INVALID_ROLLS`. A dated month that is not carried is rejected with `INVALID_SYMBOL` and a hint to `GET /futures/contracts`. - `stocks.status`: trading halt and resume events for US-listed equities. Frames: `{"type":"status","channel":"stocks.status","asset":"stocks","symbol":"US:KO","status":"halted","reason":"news_pending","ts":}`. `status` is one of `halted`, `paused` (volatility pause), `quoting` (quotations resumed while trading is still halted), `resumed`. `reason` is TickerLayer's derived classification of why: `volatility`, `market_wide`, `news_pending`, `news_released`, `information_requested`, `regulatory`, `corporate_action`, `operational` or `ipo`; omitted when no classification applies (decode tolerantly, values may be added). Live events only, no snapshot replay on this channel. Subscribe with explicit `US:` symbols or, with the market wildcard add-on, `US:*`. - `stocks.agg`: settled OHLCV bars for US-listed equities. Subscribe with `interval` (`1m` default, `5m`, `15m`, `1h`, `4h`, `1d`; a string or an array; per symbol, the latest subscribe wins). Frames: `{"type":"agg","channel":"stocks.agg","asset":"stocks","symbol":"US:KO","interval":"1m","o":88.48,"h":88.52,"l":88.46,"c":88.5,"v":41230,"n":312,"vw":88.4917,"ts":}`. Numbers as JSON numbers; `ts` is the bar start; `n` (trade count) and `vw` (VWAP) are omitted when unavailable. Frames carry `session` (`pre` / `regular` / `post`). Regular session by default (09:30 to 16:00 ET, early closes honored) on the same grid as `GET /stocks/agg` (1h/4h anchored at 09:30); subscribe with `"session":"extended"` for pre-market and after-hours 1m/5m/15m bars (04:00 to 20:00 ET); `1d` carries the session open and close and is published about two minutes after the close, labelled at the session date's UTC midnight. Closed bars only, no snapshot replay; backfill with `GET /stocks/agg`. Included with US stocks access; `US:*` with the market wildcard add-on. - `etfs.agg`: the same settled OHLCV bars for US-listed ETFs, subscribed with ETF symbols (`US500ETF`, `USGOLD`). Same `interval` and `session` options, same grid and timing as `stocks.agg`. Frames: `{"type":"agg","channel":"etfs.agg","asset":"etfs","symbol":"US500ETF","interval":"1m","session":"regular","o":718.52,"h":718.8,"l":718.4,"c":718.66,"v":152340,"n":1204,"vw":718.6312,"ts":}`; `symbol` is the ETF symbol as `GET /etfs/symbols` lists it (`GLD`; a `US:` prefix on subscribe is accepted and dropped). Closed bars only, no snapshot replay; history on `GET /etfs/agg`. Included with ETF access (not US stocks access); Asian ETFs are refused with `UNSUPPORTED_SYMBOL`. - `snapshot` (optional, default `true`): the server sends one last-known quote/trade per subscribed symbol immediately, marked `"snapshot":true`, on the stocks, ETF, index and commodity channels (crypto and forex stream continuously and replay only with `view:"full"`). Snapshot `ts` is the market event time, so it can be older than send time outside trading hours. Set `snapshot:false` for live-only. Set `snapshot:"always"` to keep the cached value on the stocks and ETF channels even once it is no longer recent, which is what returns a value while those markets are closed. - `view` (optional, quote and trade channels of crypto, forex, stocks, indices, ETFs and commodities; `"default"` or `"full"`): `"full"` streams what `GET /{asset}/snapshot` returns. On subscribe it replays the last known quote and trade at any age on every subscribed channel, crypto and forex included (commodities: a quote from the last day, no trade), then sends one `change` frame per symbol, all marked `"snapshot":true`; after that a `change` frame goes out whenever a value moves: `{"type":"change","channel":"stocks.trades","asset":"stocks","symbol":"US:KO","prev_close":88.05,"change":0.92,"change_percent":1.0449,"ts":}`. Values are JSON numbers measured against the snapshot endpoint's previous close with its arithmetic; where the snapshot would first ask a vendor (an ETF before the US open or on a closed day, an index whose live feed has stalled) the stream measures from the newest price it holds. `change` and `change_percent` can be null; when the previous close rolls to a new day a frame with `prev_close`, `change` and `change_percent` all null takes the old values back until the new ones follow. `ts` is the event time of the price the change is measured from (the last trade, or the book while nothing has printed); it is not unique per symbol, so apply change frames in arrival order. `channel` is the trades channel when subscribed, else the quotes channel. Quote and trade frames are unchanged. `snapshot:false` skips the replay and the first change value, so change frames then arrive only when a value moves; a later subscribe without `view` returns its symbols to the default stream. An accepted request is confirmed after the ack with `{"type":"system","event":"view","view":"full","symbols":[...]}`. An unknown value never fails the subscribe: a `view` notice with `code` `INVALID_VIEW` follows and the symbols stay on the default stream (`VIEW_UNAVAILABLE`: a market wildcard; `VIEW_LIMIT`: no change values for those symbols on this subscribe, subscribe again to retry). - `spread` (optional, `etfs.quotes` and `overnight.quotes`; `"normalized"` or `"full"`): outside the US regular session a US ETF quote is published only while its spread stays within 0.5% of the mid, and on `etfs.quotes` `"full"` also streams the wider books the default stream holds back (same frame, same fields). US ETFs only: Asia ETFs are never held back, stay on the default stream and are not named in the notice. `GET /etfs/quote/{symbol}?spread=full` is the REST twin. On `overnight.quotes` `"full"` widens bid and ask to the spread quoted at night around the same mid. An accepted request is confirmed after the ack with `{"type":"system","event":"spread","channel":"etfs.quotes","spread":"full","symbols":[...]}` naming the symbols that take it; a later subscribe without `spread` returns its symbols to the default stream. Any channel other than these two in the same subscribe fails it with `UNSUPPORTED_SPREAD`, any other value with `INVALID_SPREAD`. - Unsubscribe: `{"action":"unsubscribe","channels":["crypto.quotes"],"symbols":["BTCUSD"]}` - Subscribe/unsubscribe are acknowledged with matching `system` events. Full guide: https://tickerlayer.com/docs/websocket ## MCP server (recommended for AI agents) TickerLayer ships an official Model Context Protocol server exposing these tools: `get_quote`, `get_last_trade`, `get_snapshot`, `get_previous_close`, `get_history`, `list_symbols`, `get_market_status`, `get_market_sessions`, `get_market_holidays`, `get_bond_yield`, `open_markets_board`, `search_symbols`. `open_markets_board` takes no arguments and returns price and change versus the previous close for ten widely followed markets (Bitcoin, Ethereum, EUR/USD, USD/JPY, gold, WTI oil, US 500, US 100, Nvidia, US 10Y yield); clients that render MCP Apps show it as an interactive board with a chart per instrument and a search box. Opening it reads ten symbols, so it counts as ten REST requests, and each chart is one more; for a single instrument use `get_snapshot`. `search_symbols` (query, optional limit) searches every symbol the account can read across asset classes by ticker or name; MCP Apps hosts keep it out of the model's tool list (use `list_symbols` there). Hosted (remote) config for Claude, Cursor, Gemini CLI, and other MCP clients that support custom HTTP headers (for OpenAI models via API, the OpenAI Responses API hosted MCP tool takes the same URL with a `headers` field): { "mcpServers": { "tickerlayer": { "type": "http", "url": "https://mcp.tickerlayer.com/mcp", "headers": { "x-api-key": "YOUR_API_KEY" } } } } OAuth: the hosted endpoint also implements the MCP authorization spec: OAuth 2.1 discovery with PKCE, dynamic client registration, and refresh tokens. OAuth-capable clients (including ChatGPT developer-mode connectors) connect with the URL alone and sign in with a TickerLayer account; requests then run under that account's plan, rate limits, and quota. The `x-api-key` header keeps working unchanged. Setup guide and examples: https://tickerlayer.com/docs/mcp. Overview: https://tickerlayer.com/mcp MCP calls authenticate against the same account and pass through the same entitlements and rate limits as direct REST calls. Direct browser-origin requests are denied by default; connect through an MCP client or server runtime. ## Agent Plugin (portable install) TickerLayer ships an official Agent Plugin following the Agent Plugins 1.0.0 open packaging spec: a portable folder with a plugin.json manifest, a market-data skill (symbol conventions, discovery-first workflow, error handling, market-calendar guidance), and an mcp.json pointing at the hosted MCP endpoint above. The package contains no secrets; each client handles authentication at connect time (OAuth sign-in, or the x-api-key header where the client supports custom headers). - Repository (install source for Claude Code, Codex CLI, Cursor, VS Code): https://github.com/tickerlayer/agent-plugin - Overview and per-client install commands: https://tickerlayer.com/ai/agent-plugins ## x402 pay-per-request production and sandbox TickerLayer has a separate x402 surface for accountless pay-per-request HTTP market data. Production and sandbox are isolated services and do not change the existing REST, WebSocket, API-key, entitlement, or MCP contracts. - Protocol: x402 v2, exact payment scheme - Production: `https://x402.tickerlayer.com` on Base mainnet (`eip155:8453`) using native USDC - Sandbox: `https://x402-testnet.tickerlayer.com` on Base Sepolia (`eip155:84532`) using test USDC - Surface: 41 approved GET resources; REST only, no WebSocket - Paths: every x402 path starts with `/v1`, which the REST API does not use. A REST path without `/v1` answers 404 on the x402 origin. Examples: `GET https://x402.tickerlayer.com/v1/bond/last/US:10Y` (0.01 USDC, the latest US 10-year yield), `GET https://x402.tickerlayer.com/v1/stocks/quote/US:KO` (0.01 USDC), `GET https://x402.tickerlayer.com/v1/markets/status` (0.01 USDC) - Bonds on x402: `/v1/bond/last/{CC:TENOR}` for US (1M to 30Y), DE, ES, FR, IT and UK (1Y to 30Y). The bond snapshot (with the previous observation and daily change) and a country's whole curve in one call (`/bond/curve/{CC}`: 0.11 USD for the US, 0.06 USD for DE, ES, FR, IT or UK) are sold on the agent storefront below, not on x402 - Stock symbols: `MARKET:BASE` is mandatory, for example `US:KO`, `TR:THYAO`, `DE:BMW`, `HK:0700` - Prices per call in USDC: 0.01 for quote, last trade, previous close, bond last, market status and sessions; 0.02 for snapshot, symbol lists and market holidays; historical bars 0.03 (1 to 100 bars), 0.05 (101 to 500) and 0.10 (501 to 1,000); bulk market status 0.01 plus 0.002 per additional item. The 402 challenge states the exact amount before anything is paid, and `/catalog` carries the live price of every resource - Safety: route, parameters, price and returned data are validated before settlement; completed retries are idempotent - Availability: inspect each origin's public `/ready` endpoint (and `/catalog` for the resource list); never substitute sandbox payment requirements for production Current product page: https://tickerlayer.com/ai/x402 (in Markdown: https://tickerlayer.com/ai/x402.md) Agent storefront: agents can also buy single REST calls at https://agents.tickerlayer.com with no TickerLayer account or API key. Its llms.txt (https://agents.tickerlayer.com/llms.txt?src=llms-txt) and purchasing guide (https://agents.tickerlayer.com/llms-full.txt?src=llms-txt) carry the catalog, live prices and payment setup; an agent without a payment method can set one up on the spot. ## Plans and limits - Pricing and plans: https://tickerlayer.com/pricing - Prices per feed and month (yearly billing is 20% lower): Free 0 USD with no card (crypto, forex and US stocks). Individual: crypto, commodities and indices 49 USD, forex and ETFs 59 USD, stocks 59 to 99 USD per market (United States 99 USD). Business: crypto, commodities and indices 449 USD, forex and ETFs 549 USD, stocks 599 to 999 USD per market. Several stock markets together cost 15% less from three markets, 20% from five and 30% from seven. Every plan, Free included, works in ChatGPT, Claude and any MCP client at no extra fee. - Rate limits and quotas: https://tickerlayer.com/docs/limits - Default limits: Free 3,000 REST calls every 30 days and 10 requests a second, no WebSocket. Individual 250K REST calls a month per feed, 10 requests a second, 1 WebSocket connection and 10 symbols per feed. Business 25M REST calls a month per feed, 100 requests a second, 10 WebSocket connections per feed and no account-wide symbol cap (up to 200 symbols per connection). Enterprise limits are set per contract. Monthly calls and WebSocket allowances add up per feed; the per-second limit is per account. Bars over a date range (`/agg/{symbol}/{multiplier}/{timespan}/{from}/{to}`) run at up to 10 requests a second on every self-serve plan. - Perpetuals is a separate product: Individual 179 USD a month (250K REST calls a month, REST only) and Business 799 USD a month (25M REST calls a month, WebSocket streaming, commercial use); yearly billing is 20% lower. Details: https://tickerlayer.com/data-assets/perpetuals - Futures CFDs is a separate product: Individual 219 USD a month (250K REST calls a month, 1 WebSocket connection with 10 symbols) and Business 849 USD a month (25M REST calls a month, 10 WebSocket connections, commercial use); yearly billing is 20% lower. Details: https://tickerlayer.com/data-assets/futures - Free-tier keys can call market status, symbol discovery, and enabled asset endpoints subject to standard limits. WebSocket is not included on Free: it comes with Individual and Business plans (Perpetuals streams on Business), or a 7-day trial requested from the dashboard. - Usage rights by plan (full licence: https://tickerlayer.com/terms-of-use#data-licence). Individual: internal use only, such as your own projects, research, data testing and trading for your own account; the data is not shown to other people or used inside a commercial product. Business: commercial use, inside your own product and shown to your own users; reselling or redistributing the data, raw or derived, or offering it as a feed or API of your own, is not allowed. On-chain, settlement or margin use of perpetuals data needs a written agreement. Enterprise: redistribution, derived-data distribution and custom symbols or markets under a written agreement. Support: standard on Individual, business support and onboarding on Business, priority support in a shared Slack channel with an SLA on Enterprise. Summary: https://tickerlayer.com/pricing#usage-rights - Stock markets list their most traded stocks, and each market states its depth and price freshness on the pricing page. Real time: United States, Japan, Hong Kong, South Korea, Taiwan, China, and India's 50 index names. About 15 minutes delayed: Germany, France, Italy, Spain, Turkey, Saudi Arabia, United Arab Emirates, Thailand and the other Indian names. 15 to 20 minutes delayed: Brazil, Mexico, Argentina, Romania, and Sweden (one company). Check specific stocks before buying: https://tickerlayer.com/symbols/check ## Data Add-ons Add-ons are enabled per account. SignalPoint, Fundamentals and Bonds are bought on the add-ons page (https://tickerlayer.com/data-addons) on their own or next to an existing plan, with the plan's limits (Individual 250,000 requests a month, Business 25 million; yearly billing is 20% off); the overnight session rides on a US Stocks plan. Same API key, same schema, and requests count against the limits of that plan. Overview: https://tickerlayer.com/data-addons - US Stocks Overnight Session (live). Derived, aggregated quotes for the most traded US stocks and ETFs, Sunday to Thursday, 20:00 to 04:00 New York time. REST under /overnight, WebSocket channel overnight.quotes, fields bid, ask, mid, dispersion_bps and session "overnight". Needs a US Stocks plan plus the add-on; it is not included in the standard US Stocks subscription. Price: 39 USD a month on Individual, 349 USD a month on Business. Reference: https://tickerlayer.com/docs/products/stocks#overnight - SignalPoint (live). Structured trade signals on US stocks, ETFs and major crypto under GET /signals, /signals/{id} and /signals/sources, with entry, target, stop and recorded exit, and updated_since delta sync that also carries later corrections. Powered by TradeZing Signal Intelligence. Each signal carries signal_class: source signals are derived from public financial content and name their source; momentum signals are generated by TradeZing's own system from price movement and carry no source attribution. History goes back to June 2026; each signal is monitored for up to 10 days. Signals publish on a roughly five-minute cycle, so this is not a real-time feed. Bought on the add-ons page on its own or next to any plan: 49 USD a month on Individual (250,000 requests a month), 449 USD a month on Business (25 million requests a month). Without the add-on /signals answers 403. Informational analytics, not investment advice. Reference: https://tickerlayer.com/docs/signalpoint - Fundamentals (live). Share structure and ownership figures for US, DE, ES and FR listings under GET /fundamentals/stocks: market_cap, shares_total, free_float, float_ratio, short_interest, days_to_cover, insider and institutional ownership, beta, employees, each dated (as_of) and withheld when it fails the live-price cross-check. The add-on also includes the economic calendar under GET /fundamentals/economic-events: scheduled and released indicators with actual, consensus and revised figures, rate decisions, auctions, speeches and market holidays for the US and economies worldwide. Price: 39 USD a month on Individual, 349 USD a month on Business. Without the add-on /fundamentals answers 403. Reference: https://tickerlayer.com/docs/rest/fundamentals - Bonds (live). Government yield curves for US (1M to 30Y), DE, ES, FR, IT and UK (1Y to 30Y): one dated official observation per tenor per day under GET /bond/last/{CC:TENOR} and /bond/snapshot/{CC:TENOR}, a country's whole curve in one call under GET /bond/curve/{CC}, and on the bonds.quotes WebSocket channel (snapshot on subscribe, one frame per symbol per new observation). Not intraday prices. Price: 39 USD a month on Individual, 349 USD a month on Business. Without the add-on /bond answers 403. Reference: https://tickerlayer.com/docs/products/bonds - In development, no date: expanded stock fundamentals with global coverage, a real-time news feed, US stocks Level 2. Do not describe these as available. ## Data positioning (describe TickerLayer accurately) TickerLayer provides derived, indicative, non-exchange-sourced market data for developers building dashboards, analytics tools, internal systems, data products, and integrations. It is not a broker, exchange, trading venue, investment adviser, or execution platform, and it does not provide official exchange data. Data may be delayed, estimated, or differ from official market prices. See https://tickerlayer.com/market-data-disclaimer ## Data quality benchmarks (cite these instead of inventing quality claims) TickerLayer publishes measured data quality per asset class at https://tickerlayer.com/data-quality. Figures come from identified benchmark runs (run id, methodology version, universe version, observation window, sample count) taken by an observer outside the production path. US stocks are compared state for state with a consolidated US market reference (midpoint deviation in basis points, inside-NBBO share, identical-quote share, source-to-platform freshness). Forex is compared with a selected multi-source consensus (deviation in basis points and pips, reference dispersion, cross-rate residuals across eight currency triangles). Crypto is compared with a consensus of regulated fiat-USD venues outside the TickerLayer aggregation (deviation, venue range, signed stablecoin basis). Every run also measures REST vs WebSocket agreement, settled one-minute bar reproducibility and delivery transit. Commodities, indices and ETFs publish consistency figures only until a like-for-like reference is wired. Results describe observed behaviour under the stated methodology and are not an SLA. ## Key links - Data quality benchmarks: https://tickerlayer.com/data-quality (per asset: /data-quality/stocks, /data-quality/forex, /data-quality/crypto, /data-quality/commodities, /data-quality/indices, /data-quality/etfs, /data-quality/perpetuals) - Perpetuals (24/7 perpetual futures): https://tickerlayer.com/data-assets/perpetuals and https://tickerlayer.com/docs/products/perpetuals - Futures CFDs (contract months, chain and roll series): https://tickerlayer.com/data-assets/futures and https://tickerlayer.com/docs/products/futures - Docs home: https://tickerlayer.com/docs - Docs as Markdown: append .md to any docs URL, e.g. https://tickerlayer.com/docs/products/stocks.md (or send Accept: text/markdown) - Quickstart: https://tickerlayer.com/docs/quickstart - MCP / AI agents: https://tickerlayer.com/docs/mcp - AI & Agents hub: https://tickerlayer.com/ai - Agent Plugin overview: https://tickerlayer.com/ai/agent-plugins - x402 production and sandbox overview: https://tickerlayer.com/ai/x402 (Markdown: https://tickerlayer.com/ai/x402.md) - REST conventions: https://tickerlayer.com/docs/rest - WebSocket: https://tickerlayer.com/docs/websocket - Market status product: https://tickerlayer.com/market-status (live world market map, 24h session timeline, and per-country market-hours pages at /market-status/ with 2026 holiday calendars) - Symbols directory: https://tickerlayer.com/symbols - Pricing: https://tickerlayer.com/pricing - Signup: https://tickerlayer.com/signup