Market data

Discover exchanges, instruments, and historical market data through the REST API.

All market-data routes require a bearer JWT obtained from authentication. They expose the exchange catalogue and historical data that QTSurfer manages; they do not submit a backtest or create server-side state.

Discover exchanges and instruments

GET /exchanges lists the exchanges the platform knows, centralized and decentralized, each with its venueType and the segments it offers. Ids, venue types and segments are lower-case, written the same way wherever the API takes them:

[
  {"id": "binance", "name": "Binance", "venueType": "cex", "segments": ["spot", "futures"], "liveSegments": ["spot"]},
  {"id": "bybit", "name": "Bybit", "venueType": "cex", "segments": ["spot", "futures"], "liveSegments": ["spot"]},
  {"id": "robinhood", "name": "Robinhood Chain", "venueType": "dex", "segments": ["uniswap-v3"], "liveSegments": ["uniswap-v3"]}
]

venueType is cex for a centralized exchange and dex for a decentralized one. The segments of a cex exchange are the market segments its instruments are listed under; liveSegments are the ones among them a live run can read, because live data is published for them (spot today). For a dex exchange both are the protocols whose pools a live run can read (see DEX pools). A dex exchange has no hourly files, datasets or backtests, so its id is 400 in every route that takes an exchangeId except the two instrument routes, which list its pools. Use either instrument route with the id of any exchange GET /exchanges lists:

RouteMeaning
GET /exchange/{exchangeId}/instrumentsInstruments in the default spot segment
GET /exchange/{exchangeId}/{segment}/instrumentsInstruments in an explicit segment: spot or futures, or a protocol of a dex exchange (uniswap-v3)

An instrument response is a HAL envelope. Its data array contains id, symbol, base, quote, current lastPrice and volume24h, plus independent coverage.tickers and coverage.klines windows. meta.updatedAt identifies when the catalogue was assembled; meta.segment identifies the segment actually served and meta.venueType the venue type of the exchange (cex here, dex for a listing of pools). Treat coverage as live platform state rather than a promise that every timestamp is available forever.

Both kinds of listing, instruments and pools, can be read the same way: the fields below mean the same in each, and the rest belong to one kind only.

FieldMeaningIn
meta.venueTypecex or dex, as GET /exchanges lists the exchangeboth
idIdentifier to use in the other routes: the pair of an instrument (BTC/USDT), the address of a poolboth
symbolThe name of the instrument or pair, the way the signals of a run name it. The same as id for an instrumentboth
base, quoteSymbol of each sideboth
lastPricePrice of one base in the quote currency; absent when there is noneboth
volume24hVolume over the last 24 hours, in the quote currency; absent when there is noneboth
coverageTime range of the data held, per data typeinstruments only
settleSettlement currency of a futures instrumentfutures instruments only
baseAddress, quoteAddress, feePercent, tvlUsd, volume24hUsd, createdAtToken addresses, fee tier, liquidity and volume in US dollars, creation datepools only

lastPrice and volume24h of an instrument are refreshed every few minutes; those of a pool are as of meta.updatedAt, which is refreshed every hour, so a pool’s price can be up to one hour old.

A field with no data is left out of the entry, never sent as null: read an absent lastPrice, volume24h or createdAt as “not known”.

curl https://api.qtsurfer.net/v1/exchange/binance/spot/instruments 
  -H "Authorization: Bearer $QTSURFER_JWT"

The response’s _links provide self, spot, and futures discovery links. An exchange GET /exchanges does not list, and a segment the exchange does not have, return 400; a catalogue that is not available returns 404. The segment is written in lower-case.

Pools of a decentralized exchange

For a dex exchange the instruments are its pools, and this is where to find the address to put in instruments of a live run:

curl https://api.qtsurfer.net/v1/exchange/robinhood/uniswap-v3/instruments 
  -H "Authorization: Bearer $QTSURFER_JWT"
{
  "data": [
    {"id": "0x52e65b17fb6e5ba00ed806f37afcd2daa50271ca", "symbol": "WETH/USDG", "base": "WETH", "quote": "USDG",
     "baseAddress": "0x0bd7d308f8e1639fab988df18a8011f41eacad73", "quoteAddress": "0x5fc5360d0400a0fd4f2af552add042d716f1d168",
     "feePercent": 0.01, "lastPrice": 2411.285967, "volume24h": 274033077.4, "tvlUsd": 19857902.02,
     "volume24hUsd": 273876056.45, "createdAt": "2026-07-02T20:51:08Z"}
  ],
  "meta": {"updatedAt": "2026-10-14T22:32:34Z", "exchange": "robinhood", "segment": "uniswap-v3", "venueType": "dex", "minTvlUsd": 10000, "limit": 50},
  "_links": {"self": {"href": "/v1/exchange/robinhood/uniswap-v3/instruments"}, "uniswap-v3": {"href": "/v1/exchange/robinhood/uniswap-v3/instruments"}}
}

A pool’s id is its address, in lower case. symbol is the pair as the signals of a run name it, which is not always the order other sites show it in (the same pool can read USDG / WETH elsewhere), so identify a pool by its address. A protocol can have several pools of one pair, one per fee tier (feePercent).

lastPrice is the price of one base in the quote token (2411.285967 USDG for one WETH above) and volume24h is what traded over the last 24 hours in that quote token; volume24hUsd is the same volume in US dollars, and the listing is ranked by it. Either can be absent. They are as of meta.updatedAt, up to one hour old.

The listing has the 50 pools with the most volume over the last 24 hours (volume24hUsd) among those with at least 10,000 US dollars of liquidity (tvlUsd), and is refreshed every hour (meta.updatedAt); meta states both limits. It is a place to start, not the whole market: a live run can read any pool of the protocol, listed or not. 404 means the listing is not available at the moment.

Download hourly segments

Two routes return bytes rather than JSON:

RoutePayload
GET /exchange/{exchangeId}/tickers/{base}/{quote}Raw ticker events for one UTC hour
GET /exchange/{exchangeId}/klines/{base}/{quote}Aggregated exchange-native klines for one UTC hour

Both require the hour query parameter in YYYY-MM-DDTHH UTC form. For example, 2026-10-15T10 covers [2026-10-15T10:00:00Z, 2026-10-15T11:00:00Z) (the hour has to be one of the last 7 days, see below: read the example as the shape of the value). The default format=lastra is QTSurfer’s compact columnar format; format=parquet asks the service to convert the same segment on demand. The response is respectively application/vnd.qtsurfer.lastra or application/vnd.apache.parquet, and Content-Disposition supplies a useful filename.

# the hour has to be one of the last 7 days
curl --fail --remote-name 
  "https://api.qtsurfer.net/v1/exchange/binance/tickers/BTC/USDT?hour=2026-10-15T10&format=parquet" 
  -H "Authorization: Bearer $QTSURFER_JWT"

Use a kline segment when bar-level data is enough; tickers can be much larger. Download consumers should stream the response to disk or a compatible reader instead of buffering an hour in memory.

Which hours

The last 7 days: an hour that started no more than 7 days before the request and has ended. The routes give one hour of one instrument, fast; they are not how to get older history or a range. For those, import a dataset of the exchange’s history (POST /datasets/imports with type: "cex") and download it the way any dataset is downloaded.

The hour in progress and the last hours

The hour in progress, and an hour that has ended but is not stored yet, can be answered with what has been received so far: 200 with X-Data-Status: provisional and X-Data-Through, the instant of the last row (an ISO-8601 UTC time, whatever the unit of ts). Not every deployment of the service gives provisional answers: where it does not, those hours are 404 with NOT_YET_AVAILABLE and a Retry-After, and a client that needs them handles both. The columns, the time unit and the formats are those of any other hour. A provisional answer can still grow and the stored hour replaces it once there is one: use it for the tip of the market, not as the record of an hour. It takes seconds to build, longer the further the hour has gone, and the service limits how many it builds at once, so a 503 with Retry-After is a request to ask again, not a failure. When there is nothing to give, because the instrument has no rows in the hour yet or what has been received does not reach back to the start of the hour, the answer is also 404 with NOT_YET_AVAILABLE.

Timestamps

In a Lastra response the ts column holds microseconds since the epoch. The column’s metadata declares it (ts_unit: micros) and so does the response header X-Ts-Unit: micros, so a reader does not have to guess the unit from the magnitude. A Parquet response has its timestamp column as a TIMESTAMP in milliseconds.

Errors

A failed request answers ResponseError: code and message, and, when the cause has a stable name, reason, and when there is a request that gets past it, next. A client branches on reason, not on the text of message.

StatusreasonMeaningWhat to do
400nonehour missing or not YYYY-MM-DDTHH, format unknown, or an hour in the futurefix the request
400OUTSIDE_WINDOWthe hour is older than the last 7 dayssend next: the POST /datasets/imports request that imports exactly that hour (add a name)
404NOT_YET_AVAILABLEthe hour is not stored yet and no provisional answer was given for it; carries Retry-Afterask again after that many seconds
404NO_DATAthe hour is stored and holds nothing for this instrumentnone: there is no data to get
503TEMPORARILY_UNAVAILABLEreads are being limited (stored or provisional) and this one was not served; carries Retry-Afterask again after that many seconds
500noneunexpected failure; the message says nothing about its causeretry later
{
  "code": 400,
  "message": "Hour older than 7 days: import it as a dataset",
  "reason": "OUTSIDE_WINDOW",
  "next": {
    "method": "POST",
    "path": "/datasets/imports",
    "body": {
      "type": "cex",
      "instrument": "BTC/USDT",
      "from": "2026-09-01T10:00:00Z",
      "to": "2026-09-01T11:00:00Z",
      "cex": { "exchange": "binance", "segment": "spot", "dataType": "klines" }
    }
  }
}

next.path is relative to the server URL (the one that already ends in /v1). Whatever depends on you and cannot be known to the service, such as the name of the dataset, is left for you to add.

  • Backtests use managed exchange data after preparing a requested window.
  • Datasets covers caller-uploaded data — CSV or parquet — when managed exchange coverage is not the desired source.