@qtsurfer/api-client 0.23.1 → 0.25.0

package/src/generated/types.gen.ts

@@ -12,6 +12,38 @@ export type ResponseError = {
    * Error description
    */
   message: string;
+  /**
+   * A stable token naming the cause, for a client to branch on without reading `message`.
+   * Present only on an error that has one, and each operation that can return one lists
+   * the values it uses. A client treats a value it does not know like an absent `reason`.
+   *
+   */
+  reason?: string;
+  next?: ErrorNextCall;
+};
+
+/**
+ * The call that gets past an error, ready to send: a client that wants the same thing by
+ * another route makes this request. Present only on an error that has one.
+ *
+ */
+export type ErrorNextCall = {
+  /**
+   * HTTP method of the call.
+   */
+  method: "GET" | "POST" | "PUT" | "DELETE";
+  /**
+   * Path of the call, relative to the server URL (the one that already ends in `/v1`).
+   */
+  path: string;
+  /**
+   * JSON body of the call, when it has one. Whatever depends on the caller and cannot be
+   * known here (such as the `name` of a dataset) is left for the client to add.
+   *
+   */
+  body?: {
+    [key: string]: unknown;
+  };
 };
 
 /**
@@ -24,6 +56,15 @@ export type ScalarStrategyParamValue = number | string | boolean;
  */
 export type Instrument = string;
 
+/**
+ * An exchange's instrument catalogue: centralized-exchange instruments or decentralized-exchange
+ * pools. Read `meta.venueType` to distinguish `cex` from `dex`, including when `data` is empty.
+ *
+ */
+export type InstrumentCatalogueResponse =
+  | InstrumentListResponse
+  | PoolListResponse;
+
 /**
  * HAL-style response envelope for the instruments listing
  */
@@ -52,6 +93,10 @@ export type InstrumentListMeta = {
    * The market segment served in `data`
    */
   segment: "spot" | "futures";
+  /**
+   * The venue type of the exchange, as `GET /exchanges` lists it. Always `cex` here; a listing of pools says `dex`.
+   */
+  venueType: "cex";
 };
 
 /**
@@ -72,6 +117,115 @@ export type InstrumentLinks = {
   futures?: HalLink;
 };
 
+/**
+ * HAL-style response envelope for the instruments listing of a decentralized exchange, whose instruments are pools
+ */
+export type PoolListResponse = {
+  /**
+   * The pools worth running, the most traded in the last 24 hours first
+   */
+  data: Array<PoolDetail>;
+  meta: PoolListMeta;
+  _links: PoolLinks;
+};
+
+/**
+ * Metadata describing the pools listing of a decentralized exchange
+ */
+export type PoolListMeta = {
+  /**
+   * When this listing was last refreshed. It is refreshed every hour, and the `lastPrice` of each pool is as of this time.
+   */
+  updatedAt: string;
+  /**
+   * The exchange the pools belong to
+   */
+  exchange: string;
+  /**
+   * The protocol served in `data`, one of the exchange's `segments`
+   */
+  segment: string;
+  /**
+   * The venue type of the exchange, as `GET /exchanges` lists it. Always `dex` here; a listing of instruments of a centralized exchange says `cex`.
+   */
+  venueType: "dex";
+  /**
+   * A pool with less liquidity than this (in US dollars) is not listed
+   */
+  minTvlUsd: number;
+  /**
+   * The most pools the listing has
+   */
+  limit: number;
+};
+
+/**
+ * HAL `_links` — protocol discovery for the pools listing of a decentralized exchange
+ */
+export type PoolLinks = {
+  /**
+   * Link to this listing
+   */
+  self: HalLink;
+  [key: string]: HalLink;
+};
+
+/**
+ * A pool of a decentralized exchange that a live run can read. The listing is a place to start, not the
+ * whole market: a live run can read any pool of the protocol, listed or not.
+ *
+ */
+export type PoolDetail = {
+  /**
+   * The pool's address, in lower case. It is the value to put in `instruments` of a live run's source.
+   */
+  id: string;
+  /**
+   * The pair written `BASE/QUOTE`, the way the signals of a run on this pool name it (`instrument`)
+   */
+  symbol: string;
+  /**
+   * Symbol of the base token
+   */
+  base: string;
+  /**
+   * Symbol of the quote token
+   */
+  quote: string;
+  /**
+   * Address of the base token, in lower case
+   */
+  baseAddress: string;
+  /**
+   * Address of the quote token, in lower case
+   */
+  quoteAddress: string;
+  /**
+   * The pool's fee tier, in percent (`0.05` is a 0.05 % fee). A protocol can have several pools of the same pair, one per fee tier.
+   */
+  feePercent: number;
+  /**
+   * The price of one base token in the quote token, as the signals of a run on this pool name the pair. It is as of `meta.updatedAt`, so up to one hour old. Absent when there is no price for the pool.
+   */
+  lastPrice?: number;
+  /**
+   * What traded in the pool over the last 24 hours, in the quote token, the same meaning as `volume24h` of an instrument of a centralized exchange. Absent when the quote token has no dollar price to convert from.
+   */
+  volume24h?: number;
+  /**
+   * The liquidity held by the pool, in US dollars
+   */
+  tvlUsd: number;
+  /**
+   * What traded in the pool over the last 24 hours, in US dollars
+   */
+  volume24hUsd: number;
+  /**
+   * When the pool was created. Absent when it is not known
+   */
+  createdAt?: string;
+};
+
 /**
  * HAL `_links` for a strategy — present on a full `StrategyState` body (`GET
  * /strategy/{strategyId}`, and `POST /strategy/{strategyId}/validate`'s already-validated
@@ -119,6 +273,7 @@ export type Account = {
    * Your current subscription tier.
    */
   tier: string;
+  scopes: KeyScopes;
   /**
    * Maximum number of strategy executions (and sweeps) you can have running at the same time
    * through the API. Starting one past this number is answered with `429`, whose message
@@ -238,6 +393,10 @@ export type InstrumentDetail = {
    * Instrument identifier (e.g. currency pair)
    */
   id: string;
+  /**
+   * The instrument's name, the same as `id`. A pool of a decentralized exchange has the same field (`PoolDetail`), so both listings are read alike.
+   */
+  symbol: string;
   /**
    * Base currency
    */
@@ -246,13 +405,17 @@ export type InstrumentDetail = {
    * Quote currency
    */
   quote: string;
+  /**
+   * Settlement currency. Present on a futures instrument only.
+   */
+  settle?: string;
   coverage?: InstrumentCoverage;
   /**
-   * Last traded price
+   * Last traded price. Absent for an instrument with no recent price.
    */
   lastPrice?: number;
   /**
-   * Trading volume in the last 24 hours (in quote currency)
+   * Trading volume in the last 24 hours (in quote currency). Absent for an instrument with no recent volume.
    */
   volume24h?: number;
 };
@@ -305,6 +468,18 @@ export type Exchange = {
    * Description of the exchange
    */
   description?: string;
+  /**
+   * Venue category, written as the `venueType` of a live run's source: `cex` is a centralized exchange and `dex` a decentralized one. A `dex` exchange has no market data to prepare or backtest, so its id is not valid in the routes that take an `exchangeId`, except the two instruments routes, which list its pools (the instrument of a run on it is a pool's address).
+   */
+  venueType: "cex" | "dex";
+  /**
+   * The segments the exchange offers, written as in the path of `GET /exchange/{exchangeId}/{segment}/instruments` and as the `segment` of a live run's source. For a `cex` exchange, its market segments (`spot`, `futures`: the ones its instrument catalogues are served under); for a `dex` exchange, the protocols whose pools a run can read.
+   */
+  segments: Array<string>;
+  /**
+   * The segments among `segments` for which live data is published, so the ones a live run can read: a live run on any other segment of the exchange is refused with `400`. It can be empty (an exchange whose live data is not published yet).
+   */
+  liveSegments: Array<string>;
 };
 
 /**
@@ -372,11 +547,10 @@ export type PrepareRequest = {
    * * Managed exchange, `ticker` or `funding` — one of `1s`, `5s`, `1m`, `3m`, `5m`, `15m`,
    * `30m`, `1h`, `2h`, `4h`, `8h`, `12h`, `1d`, `1w`, `1q`; any other label returns `400`.
    * Omitted = `1s`, the publisher's native cadence.
-   * * Managed exchange, `kline` — one of `1s`, `1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `1d`;
-   * any other label, including `5s`, `3m` and `8h`, returns `400` and names the accepted
-   * ones. Omitted = `1s`. This is the width of the bars a run reads: it is chosen here,
-   * once, and the same strategy can be run at several cadences by preparing the range at
-   * each.
+   * * Managed exchange, `kline` — the same labels as above, `1s` to `1q`; a label that is
+   * not a whole number of seconds returns `400`. Omitted = `1s`. This is the width of the
+   * bars a run reads: it is chosen here, once, and the same strategy can be run at
+   * several cadences by preparing the range at each.
    * * Dataset (`exchangeId: user`) — omitted = the dataset version's own discovered
    * `cadence` (see `DatasetVersion.cadence`), served as-is. Any cadence equal to or
    * coarser than it and an exact multiple of it is accepted, including ones outside the
@@ -1340,9 +1514,11 @@ export type Dataset = {
    */
   name: string;
   /**
-   * `ticker` for an upload or a `dex` import with no `cadence` requested (native per-trade
-   * data). `klines` for a `dex` import that requested a candle `cadence` — pre-aggregated
-   * bars rather than raw ticks. Purely informational; both shapes are read the same way.
+   * `ticker` for an upload, a `dex` import with no `cadence` requested (native per-trade
+   * data) or a `cex` import with `dataType: ticker`. `klines` for a `dex` import that
+   * requested a candle `cadence` — pre-aggregated bars rather than raw ticks — or a `cex`
+   * import with `dataType: klines`. Purely informational; both shapes are read the same
+   * way.
    *
    */
   type: "ticker" | "klines";
@@ -1534,11 +1710,12 @@ export type DatasetVersion = {
   rows?: number;
   /**
    * The cadence discovered from the data's own timestamps. Either a fixed grid — `1s`,
-   * `5s`, `15s`, `1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `1d` — when at least half the
-   * intervals between consecutive rows fall on that step (small clock jitter tolerated), or
-   * `rt`: native data at the rate it was captured, each row at its own timestamp with no
-   * fixed step — per-trade on-chain swaps, block-spaced or sub-second ticks, irregular
-   * intervals. An `rt` dataset can be resampled to any fixed cadence at prepare time.
+   * `5s`, `15s`, `1m`, `3m`, `5m`, `15m`, `30m`, `1h`, `2h`, `4h`, `8h`, `12h`, `1d`,
+   * `1w` — when at least half the intervals between consecutive rows fall on that step
+   * (small clock jitter tolerated), or `rt`: native data at the rate it was captured, each
+   * row at its own timestamp with no fixed step — per-trade on-chain swaps, block-spaced
+   * or sub-second ticks, irregular intervals. An `rt` dataset can be resampled to any
+   * fixed cadence at prepare time.
    *
    */
   cadence?: string;
@@ -1613,7 +1790,8 @@ export type DatasetUploadState = {
 
 /**
  * `POST /datasets/imports`'s request body. A common block plus one type-specific block,
- * selected by `type` — `dex` is the only value today.
+ * selected by `type`: `dex` (block `dex`) or `cex` (block `cex`), the two `venueType`s of
+ * `GET /exchanges`.
  *
  */
 export type DatasetImportRequest = {
@@ -1633,21 +1811,54 @@ export type DatasetImportRequest = {
    */
   to: string;
   /**
-   * Optional. Omitted/blank keeps native per-trade event cadence — each swap at its own
-   * timestamp, so the resulting version's `cadence` is `rt` unless the swaps happen to sit
-   * on a fixed grid (see `DatasetVersion.cadence`). Set to `1s`, `1m` or
-   * `5m` instead to get pre-aggregated candles at that width rather than raw trades (the
-   * resulting dataset's `type` becomes `klines`); any other value is `400`. Not every
-   * network supports every cadence — an unsupported combination fails asynchronously, not
-   * at request time (see `DatasetImportState.error`).
+   * Optional; what it means, and what it accepts, depends on `type`. Any other value is
+   * `400`.
+   *
+   * * `dex` — omitted/blank keeps native per-trade event cadence: each swap at its own
+   * timestamp, so the resulting version's `cadence` is `rt` unless the swaps happen to
+   * sit on a fixed grid (see `DatasetVersion.cadence`). Set to `1s`, `1m` or `5m`
+   * instead to get pre-aggregated candles at that width rather than raw trades (the
+   * resulting dataset's `type` becomes `klines`). Not every network supports every
+   * cadence — an unsupported combination fails asynchronously, not at request time (see
+   * `DatasetImportState.error`).
+   * * `cex` — one of `1s`, `5s`, `1m`, `3m`, `5m`, `15m`, `30m`, `1h`, `2h`, `4h`, `8h`,
+   * `12h`, `1d`, `1w`, `1q`, whether `dataType` is `ticker` or `klines`. Omitted = the
+   * finest cadence every part of the range holds.
+   *
+   * For `cex` the bars are built from the finest data every part of the range holds. A
+   * `cadence` finer than that, or not an exact multiple of it, fails the import
+   * asynchronously (`failed`; the `error` names the finest cadence the range holds) rather
+   * than returning a dataset with a different cadence from the one asked for. So a range
+   * whose history changes cadence part-way (from `1m` to `1s`, say) comes out entirely at
+   * the coarser one when `cadence` is omitted: the dataset has no gap that is only a
+   * change of cadence.
    *
    */
-  cadence?: "1s" | "1m" | "5m";
-  /**
-   * The source to fetch from. `dex` is the only value today.
+  cadence?:
+    | "1s"
+    | "5s"
+    | "1m"
+    | "3m"
+    | "5m"
+    | "15m"
+    | "30m"
+    | "1h"
+    | "2h"
+    | "4h"
+    | "8h"
+    | "12h"
+    | "1d"
+    | "1w"
+    | "1q";
+  /**
+   * The kind of venue to import from, the same two values as the `venueType` of
+   * `GET /exchanges`: `dex` — a pool/pair's own on-chain market (block `dex`) — or `cex` —
+   * a centralized exchange's market history (block `cex`).
+   *
    */
-  type: "dex";
+  type: "dex" | "cex";
   dex?: DatasetImportDexRequest;
+  cex?: DatasetImportCexRequest;
 };
 
 /**
@@ -1691,6 +1902,33 @@ export type DatasetImportDexRequest = {
   factory?: string;
 };
 
+/**
+ * The `cex` source's own fields — required when `type` is `cex`. They name a market the way
+ * `GET /exchanges` and the instruments routes do: `exchange` is the `id` of a centralized
+ * exchange, `segment` one of its `segments`.
+ *
+ */
+export type DatasetImportCexRequest = {
+  /**
+   * The id of a centralized exchange (`venueType` `cex`) of `GET /exchanges`, lower-case.
+   * A decentralized exchange's id is `400`: import its pools with `type: dex`.
+   *
+   */
+  exchange: string;
+  /**
+   * The market segment, one of the exchange's `segments`. `spot` is the only segment a
+   * `cex` import takes today, which matches `instrument` being a plain spot pair.
+   *
+   */
+  segment: "spot";
+  /**
+   * What to import, and the resulting dataset's `type`: `ticker` — the exchange's ticker
+   * series — or `klines` — its aggregated bars (open, high, low, close and volume).
+   *
+   */
+  dataType: "ticker" | "klines";
+};
+
 /**
  * The response to `POST /datasets/imports` — the dataset now exists, and its fetch has started.
  */
@@ -1739,7 +1977,8 @@ export type DatasetImportState = {
   /**
    * A human-readable reason, present when `status` is `failed` — an unresolvable
    * pool/pair, no data in the requested range, a range older than the configured source
-   * retains, the fetch exceeding your tier's time ceiling, or any of
+   * retains, a `cex` `cadence` finer than the range holds (the message names the finest
+   * one), the fetch exceeding your tier's time ceiling, or any of
    * `DatasetUploadState.error`'s own ingest-side reasons once fetching hands off to it.
    * Durably recorded, same as on the upload path.
    *
@@ -1751,6 +1990,19 @@ export type DatasetImportState = {
   version?: DatasetVersion;
 };
 
+/**
+ * What your API key may do, as a map from a resource to the actions allowed on it. Names are
+ * lower case: `{ "backtests": ["read", "write", "execute"], "exchanges": ["read"] }`. A scope
+ * is a resource and an action: a resource is listed only with at least one action, and a key
+ * with no scope is `{}`. `GET /account` and `POST /auth/token` return the same map for the
+ * same key. The API reports the scopes of a key; it does not yet refuse an operation because
+ * a scope is missing.
+ *
+ */
+export type KeyScopes = {
+  [key: string]: Array<string>;
+};
+
 export type AuthTokenResponse = {
   /**
    * Short-lived HS256 JWT. Send as `Authorization: Bearer <token>` on all other endpoints.
@@ -1764,10 +2016,7 @@ export type AuthTokenResponse = {
    * Seconds until the JWT expires (typically 3600).
    */
   expires_in: number;
-  /**
-   * Scopes granted to this token. Reserved for future use; currently always empty.
-   */
-  scopes?: Array<string>;
+  scopes?: KeyScopes;
   /**
    * Subscription tier this token was issued for. Drives rate limits and feature flags on downstream endpoints.
    */
@@ -1775,13 +2024,17 @@ export type AuthTokenResponse = {
 };
 
 /**
- * Error envelope returned by `POST /auth/token` when the API key is rejected.
+ * Error envelope returned by `POST /auth/token` when the API key is rejected (`401`) or carries no scopes where scopes are required (`403`).
  */
 export type AuthTokenError = {
   /**
    * Machine-readable error reason.
    */
-  code: "invalid_apikey" | "apikey_revoked" | "apikey_expired";
+  code:
+    | "invalid_apikey"
+    | "apikey_revoked"
+    | "apikey_expired"
+    | "apikey_without_scopes";
   /**
    * Human-readable description of the failure.
    */
@@ -1793,17 +2046,23 @@ export type AuthTokenError = {
  */
 export type LiveSource = {
   /**
-   * Venue category. `cx` (centralized exchange) is the only one live runs support today.
+   * Venue category. `cex` is a centralized exchange and `dex` is one pool on a decentralized exchange, which takes its own `exchange`, `segment`, `type` and `instruments` (see "Sources" in the Live execution guide). `cx` and `dx`, the spellings used before, are still read as `cex` and `dex`; the run always reports the new ones.
+   */
+  venueType: "cex" | "dex";
+  /**
+   * The exchange id, as `GET /exchanges` lists it. For a `dex` source, the chain the pool is on; `robinhood` is the only one today.
    */
-  venueType: string;
   exchange: string;
+  /**
+   * The segment, as `GET /exchanges` lists it for that exchange, among its `liveSegments` (a segment with no live data is refused with `400`). For a `cex` source, the market segment (`spot` today); for a `dex` source, the protocol of the pool, `uniswap-v3` the only one today.
+   */
   segment: string;
   /**
-   * Both `ticker` and `kline` connect to the lightest (fastest) cadence available for the exchange — today, 1 tick/second on every supported exchange. Choosing a specific cadence is not offered yet.
+   * Both `ticker` and `kline` connect to the lightest (fastest) cadence available for the exchange — today, 1 tick/second on every supported exchange. Choosing a specific cadence is not offered yet. A `dex` source supports only `kline`: one candle per second of the pool's trades.
    */
   type: "ticker" | "kline";
   /**
-   * The instruments the run reads. For a run started with a list, that list as sent; for one started without `instruments`, or with `["*"]`, what the start resolved: the list of pairs the compilation of the strategy records as the instruments it accepts, when it records one, or `["*"]` for every instrument the exchange/segment offers (tier-gated). An entry is written `BASE/QUOTE` and either side can be `*` to mean any, such as any base paired with USDT. Symbols are not case-sensitive and spaces around them are ignored, so `btc/usdt` and `BTC/USDT` are the same instrument.
+   * The instruments the run reads. For a run started with a list, that list as sent; for one started without `instruments`, or with `["*"]`, what the start resolved: the list of pairs the compilation of the strategy records as the instruments it accepts, when it records one, or `["*"]` for every instrument the exchange/segment offers (tier-gated). An entry is written `BASE/QUOTE` and either side can be `*` to mean any, such as any base paired with USDT. Symbols are not case-sensitive and spaces around them are ignored, so `btc/usdt` and `BTC/USDT` are the same instrument. A `dex` source holds exactly one entry, the address of its pool.
    */
   instruments: Array<string>;
 };
@@ -1813,17 +2072,23 @@ export type LiveSource = {
  */
 export type LiveSourceRequest = {
   /**
-   * Venue category. `cx` (centralized exchange) is the only one live runs support today.
+   * Venue category. `cex` is a centralized exchange and `dex` is one pool on a decentralized exchange, which takes its own `exchange`, `segment`, `type` and `instruments` (see "Sources" in the Live execution guide). `cx` and `dx`, the spellings used before, are still read as `cex` and `dex`; the run always reports the new ones.
+   */
+  venueType: "cex" | "dex";
+  /**
+   * The exchange id, as `GET /exchanges` lists it. For a `dex` source, the chain the pool is on; `robinhood` is the only one today.
    */
-  venueType: string;
   exchange: string;
+  /**
+   * The segment, as `GET /exchanges` lists it for that exchange, among its `liveSegments` (a segment with no live data is refused with `400`). For a `cex` source, the market segment (`spot` today); for a `dex` source, the protocol of the pool, `uniswap-v3` the only one today.
+   */
   segment: string;
   /**
-   * Both `ticker` and `kline` connect to the lightest (fastest) cadence available for the exchange — today, 1 tick/second on every supported exchange. Choosing a specific cadence is not offered yet.
+   * Both `ticker` and `kline` connect to the lightest (fastest) cadence available for the exchange — today, 1 tick/second on every supported exchange. Choosing a specific cadence is not offered yet. A `dex` source supports only `kline`: one candle per second of the pool's trades.
    */
   type: "ticker" | "kline";
   /**
-   * Which instruments the run reads. A QTScript strategy can declare which instruments it accepts with an `instruments` line in its source. When the compilation of the strategy records that selection as a list of pairs, leaving `instruments` out, or sending `["*"]`, takes that list; otherwise the run reads every instrument the exchange/segment offers. A list of instruments is taken as sent, and `[]` and `null` are refused with `400`. An entry is written `BASE/QUOTE`; either side can be `*` to mean any: any base can be paired with USDT, and BTC can be paired with any quote. Entries are not case-sensitive and spaces around them are ignored, so `btc/usdt` and `BTC/USDT` are the same instrument. An entry that is not of that form (no `/`, an empty side, a `.` or a space inside a side, or a `*` mixed with other characters of a side) makes the run fail when it starts. Plan limits: a list with an entry that has a `*` on a side counts like `["*"]` and only plans that include the wildcard accept it; the other entries are counted one by one. The instruments the run actually reads come back in the run's `sources`.
+   * Which instruments the run reads. A QTScript strategy can declare which instruments it accepts with an `instruments` line in its source. When the compilation of the strategy records that selection as a list of pairs, leaving `instruments` out, or sending `["*"]`, takes that list; otherwise the run reads every instrument the exchange/segment offers. A list of instruments is taken as sent, and `[]` and `null` are refused with `400`. An entry is written `BASE/QUOTE`; either side can be `*` to mean any: any base can be paired with USDT, and BTC can be paired with any quote. Entries are not case-sensitive and spaces around them are ignored, so `btc/usdt` and `BTC/USDT` are the same instrument. An entry that is not of that form (no `/`, an empty side, a `.` or a space inside a side, or a `*` mixed with other characters of a side) makes the run fail when it starts. Plan limits: a list with an entry that has a `*` on a side counts like `["*"]` and only plans that include the wildcard accept it; the other entries are counted one by one. The instruments the run actually reads come back in the run's `sources`. A `dex` source needs exactly one entry, the address of its pool (`0x` and 40 hexadecimal digits, not case-sensitive): it cannot be left out and `*` is not accepted.
    */
   instruments?: Array<string>;
 };
@@ -1837,13 +2102,22 @@ export type StartLiveRequest = {
     [key: string]: unknown;
   };
   /**
-   * A `public` run appears in `GET /live/public` and its signal channel accepts subscriptions from anyone, not only you — from the moment it is promoted to `live`. While it is a `sandbox` trial, `public` is only what you asked for, and only you can read it.
+   * A `public` run appears in `GET /live/public` and its signal channel accepts subscriptions from anyone, not only you — from the moment it is in the `live` stage, which is when it is promoted or, for a run that starts there, at once. While it is a `sandbox` trial, `public` is only what you asked for, and only you can read it.
    */
   visibility?: "private" | "public";
   /**
    * Request that this run's signals be relayed over its WebSocket channel, from its first signal — in the `sandbox` stage too, where only you can subscribe to it. See the "Live execution" guide.
    */
   relay?: boolean;
+  /**
+   * Start in the `sandbox` stage even though an earlier run of yours already took this compiled strategy
+   * through it. Without it, such a strategy starts in `LIVE` at once; with `true` it starts in `SANDBOX` like
+   * a first run, which is how to read its signals back over the connection (`history`, kept for the
+   * `sandbox` stage only) while you debug it. For a strategy that has not been through the sandbox it
+   * changes nothing: it always starts there. Anything other than `true` or `false` is `400`.
+   *
+   */
+  sandbox?: boolean;
   /**
    * Ask for a **stream URL**: a secret address that a simple client, or a service that passes your signals
    * on to others, can open as a plain WebSocket to receive this run's signals as they are produced, one JSON
@@ -1955,7 +2229,7 @@ export type LiveRun = {
   description?: string;
   visibility: "private" | "public";
   /**
-   * A new run always starts `SANDBOX`, a 24-hour trial in which it is compared against a second execution and checked for resource use and stability. A run that passes moves to `LIVE` automatically when the 24 hours are up.
+   * A new run starts `SANDBOX`, a 24-hour trial in which it is compared against a second execution and checked for resource use and stability. A run that passes moves to `LIVE` automatically when the 24 hours are up. A run of a strategy that an earlier run of yours already took through the trial starts `LIVE`, unless you started it with `sandbox: true`.
    */
   stage: "SANDBOX" | "LIVE";
   /**
@@ -1971,12 +2245,15 @@ export type LiveRun = {
    * stack trace or an internal message. Either `resource: ...` (the platform stopped the run for
    * exceeding its resource allowance; the text says which limit) or one of a fixed set of sentences for
    * a `FAILED` run: the strategy cannot consume the source type the run was started with, the run's
-   * definition was refused, the run could not start after several attempts, the strategy failed while
-   * processing data, the run lost its data feed, or the generic `The run failed.`. The set may grow:
+   * definition was refused, the pool address of a `dex` run is not a pool of its protocol on its chain,
+   * the platform has no room to follow the pool of a `dex` run, the run could not start after several
+   * attempts, the strategy failed while processing data, the run lost its data feed, or the generic
+   * `The run failed.`. The set may grow:
    * read an unrecognised sentence as a failure and do not parse it. A `FAILED` run usually stays
    * `desired: RUNNING` until you stop it, and counts as active (`409` on a new start, and toward your
-   * live-run limit) until then; one that can never run because its strategy cannot consume its source
-   * type is stopped by the platform itself (`desired: STOPPED`), so it holds no place.
+   * live-run limit) until then; one that cannot run, and will not by waiting, because its strategy cannot
+   * consume its source type or because the pool of a `dex` run is not a pool or has no room to be followed,
+   * is stopped by the platform itself (`desired: STOPPED`), so it holds no place.
    *
    */
   reason?: string;
@@ -1997,7 +2274,7 @@ export type LiveRun = {
    */
   startedAtMs: number;
   /**
-   * The sandbox trial's promotion verdict. Absent for the whole 24-hour trial and present once it ends, so an absent `gate` means the trial has not finished. `passed` is the verdict; the rest is diagnostic detail whose shape is not yet stabilized as public API: treat it as opaque.
+   * The sandbox trial's promotion verdict. Absent for the whole 24-hour trial and present once it ends, so an absent `gate` means the trial has not finished. A run that started in `LIVE` without a trial has it from the start: the verdict of the earlier run it relies on, with `inheritedFrom` naming that run. `passed` is the verdict; the rest is diagnostic detail whose shape is not yet stabilized as public API: treat it as opaque.
    */
   gate?: {
     [key: string]: unknown;
@@ -2137,7 +2414,7 @@ export type LiveRunSummary = {
   description?: string;
   visibility: "private" | "public";
   /**
-   * A new run always starts `SANDBOX`, a 24-hour trial in which it is compared against a second execution and checked for resource use and stability. A run that passes moves to `LIVE` automatically when the 24 hours are up.
+   * A new run starts `SANDBOX`, a 24-hour trial in which it is compared against a second execution and checked for resource use and stability. A run that passes moves to `LIVE` automatically when the 24 hours are up. A run of a strategy that an earlier run of yours already took through the trial starts `LIVE`, unless you started it with `sandbox: true`.
    */
   stage: "SANDBOX" | "LIVE";
   /**
@@ -2153,12 +2430,15 @@ export type LiveRunSummary = {
    * stack trace or an internal message. Either `resource: ...` (the platform stopped the run for
    * exceeding its resource allowance; the text says which limit) or one of a fixed set of sentences for
    * a `FAILED` run: the strategy cannot consume the source type the run was started with, the run's
-   * definition was refused, the run could not start after several attempts, the strategy failed while
-   * processing data, the run lost its data feed, or the generic `The run failed.`. The set may grow:
+   * definition was refused, the pool address of a `dex` run is not a pool of its protocol on its chain,
+   * the platform has no room to follow the pool of a `dex` run, the run could not start after several
+   * attempts, the strategy failed while processing data, the run lost its data feed, or the generic
+   * `The run failed.`. The set may grow:
    * read an unrecognised sentence as a failure and do not parse it. A `FAILED` run usually stays
    * `desired: RUNNING` until you stop it, and counts as active (`409` on a new start, and toward your
-   * live-run limit) until then; one that can never run because its strategy cannot consume its source
-   * type is stopped by the platform itself (`desired: STOPPED`), so it holds no place.
+   * live-run limit) until then; one that cannot run, and will not by waiting, because its strategy cannot
+   * consume its source type or because the pool of a `dex` run is not a pool or has no room to be followed,
+   * is stopped by the platform itself (`desired: STOPPED`), so it holds no place.
    *
    */
   reason?: string;
@@ -2443,6 +2723,10 @@ export type AuthenticateErrors = {
    * API key is invalid, revoked, or expired.
    */
   401: AuthTokenError;
+  /**
+   * The API key is valid but carries no scopes, and this deployment requires them.
+   */
+  403: AuthTokenError;
   /**
    * Rate limit exceeded for this API key.
    */
@@ -2525,7 +2809,11 @@ export type ListInstrumentsData = {
 
 export type ListInstrumentsErrors = {
   /**
-   * Exchange not found or instrument catalog not available
+   * The exchange is not one `GET /exchanges` lists
+   */
+  400: ResponseError;
+  /**
+   * The instrument catalog is not available
    */
   404: ResponseError;
 };
@@ -2535,9 +2823,9 @@ export type ListInstrumentsError =
 
 export type ListInstrumentsResponses = {
   /**
-   * The default (spot) segment's instruments in `data`, `meta`, and HAL `_links` (self + spot/futures segment discovery)
+   * The default (spot) segment's instruments in `data`, `meta`, and HAL `_links` (self + spot/futures segment discovery); for a decentralized exchange, its pools
    */
-  200: InstrumentListResponse;
+  200: InstrumentCatalogueResponse;
 };
 
 export type ListInstrumentsResponse =
@@ -2551,9 +2839,9 @@ export type ListSegmentInstrumentsData = {
      */
     exchangeId: string;
     /**
-     * Market segment to list instruments for
+     * The segment to list instruments for, one of the exchange's `segments` in `GET /exchanges`; `spot` or `futures` for a centralized exchange, a protocol (`uniswap-v3`) for a decentralized one
      */
-    segment: "spot" | "futures";
+    segment: string;
   };
   query?: never;
   url: "/exchange/{exchangeId}/{segment}/instruments";
@@ -2561,7 +2849,11 @@ export type ListSegmentInstrumentsData = {
 
 export type ListSegmentInstrumentsErrors = {
   /**
-   * Exchange, segment, or instrument catalog not found
+   * The exchange is not one `GET /exchanges` lists, or the segment is not one the exchange has (`spot` or `futures` for a centralized exchange, a protocol for a decentralized one)
+   */
+  400: ResponseError;
+  /**
+   * The instrument catalog is not available
    */
   404: ResponseError;
 };
@@ -2573,7 +2865,7 @@ export type ListSegmentInstrumentsResponses = {
   /**
    * An object with a `data` array of instrument details (each with per-data-type coverage) and a `meta` block
    */
-  200: InstrumentListResponse;
+  200: InstrumentCatalogueResponse;
 };
 
 export type ListSegmentInstrumentsResponse =
@@ -2615,17 +2907,29 @@ export type DownloadTickersData = {
 
 export type DownloadTickersErrors = {
   /**
-   * Missing or malformed parameters (e.g. `hour` not `YYYY-MM-DDTHH`).
+   * Missing or malformed parameters (e.g. `hour` not `YYYY-MM-DDTHH`), an `hour` in the
+   * future, or an hour older than the last 7 days (`reason: OUTSIDE_WINDOW`, with `next`).
+   *
    */
   400: ResponseError;
   /**
-   * No Lastra segment exists for the requested instrument/hour.
+   * No segment for the requested instrument/hour. `reason: NOT_YET_AVAILABLE` — the hour
+   * is not stored yet and no provisional answer was given for it (the answer carries
+   * `Retry-After`); `reason: NO_DATA` — the hour is stored and holds nothing for this
+   * instrument.
+   *
    */
   404: ResponseError;
   /**
    * Unexpected I/O error serving the file.
    */
   500: ResponseError;
+  /**
+   * Reads are being limited (of stored or of provisional data) and this one was not served
+   * (`reason: TEMPORARILY_UNAVAILABLE`). Ask again after the `Retry-After` delay.
+   *
+   */
+  503: ResponseError;
 };
 
 export type DownloadTickersError =
@@ -2634,9 +2938,10 @@ export type DownloadTickersError =
 export type DownloadTickersResponses = {
   /**
    * One hour of tickers for the instrument. `Content-Type` is
-   * `application/vnd.lastra` by default or
+   * `application/vnd.qtsurfer.lastra` by default or
    * `application/vnd.apache.parquet` when `format=parquet` was
-   * requested.
+   * requested. The hour in progress, or one that has ended and is not stored yet, may be
+   * provisional where the service gives provisional answers: see `X-Data-Status`.
    *
    */
   200: Blob | File;
@@ -2680,17 +2985,29 @@ export type DownloadKlinesData = {
 
 export type DownloadKlinesErrors = {
   /**
-   * Missing or malformed parameters (e.g. `hour` not `YYYY-MM-DDTHH`).
+   * Missing or malformed parameters (e.g. `hour` not `YYYY-MM-DDTHH`), an `hour` in the
+   * future, or an hour older than the last 7 days (`reason: OUTSIDE_WINDOW`, with `next`).
+   *
    */
   400: ResponseError;
   /**
-   * No Lastra segment exists for the requested instrument/hour.
+   * No segment for the requested instrument/hour. `reason: NOT_YET_AVAILABLE` — the hour
+   * is not stored yet and no provisional answer was given for it (the answer carries
+   * `Retry-After`); `reason: NO_DATA` — the hour is stored and holds nothing for this
+   * instrument.
+   *
    */
   404: ResponseError;
   /**
    * Unexpected I/O error serving the file.
    */
   500: ResponseError;
+  /**
+   * Reads are being limited (of stored or of provisional data) and this one was not served
+   * (`reason: TEMPORARILY_UNAVAILABLE`). Ask again after the `Retry-After` delay.
+   *
+   */
+  503: ResponseError;
 };
 
 export type DownloadKlinesError =
@@ -2699,8 +3016,10 @@ export type DownloadKlinesError =
 export type DownloadKlinesResponses = {
   /**
    * One hour of klines for the instrument. `Content-Type` is
-   * `application/vnd.lastra` by default or
-   * `application/vnd.apache.parquet` when `format=parquet`.
+   * `application/vnd.qtsurfer.lastra` by default or
+   * `application/vnd.apache.parquet` when `format=parquet` was
+   * requested. The hour in progress, or one that has ended and is not stored yet, may be
+   * provisional where the service gives provisional answers: see `X-Data-Status`.
    *
    */
   200: Blob | File;
@@ -3732,6 +4051,15 @@ export type ImportDatasetErrors = {
    * `cadence`, whether that combination is actually servable on the requested `network` —
    * is checked later, asynchronously — see the `failed` status on the poll endpoint below.
    *
+   * For `type: cex`: no `cex` block, or its `exchange` is not a centralized exchange of
+   * `GET /exchanges` (a decentralized one is `400` too — use `type: dex`), `segment` is not
+   * `spot` (the only segment a `cex` import takes today), `dataType` is not `ticker` or
+   * `klines`, or
+   * `cadence` is not one of the values a `cex` import takes (see `DatasetImportRequest`).
+   * Whether the range holds data, and whether it holds data fine enough for the `cadence`
+   * asked, is checked later, asynchronously — see the `failed` status on the poll endpoint
+   * below.
+   *
    */
   400: ResponseError;
   /**
@@ -3870,7 +4198,7 @@ export type StartLiveData = {
 
 export type StartLiveErrors = {
   /**
-   * Malformed `sources` (not exactly one entry, missing field, unsupported `type`), a `type` the strategy cannot consume (a ticker strategy with a `kline` source, or the reverse; the message names both), an invalid `visibility`, an invalid `paper` block (an unknown field, a wrong type or an out-of-range value), or no `paper` block for a strategy that listens to its own execution events. A `relay` or `stream` that is not `true` or `false`, or a `stream` where streams are not available yet. A `warmFrom` that is not an integer from 0 to 3600. An `instruments` that is empty or `null`.
+   * Malformed `sources` (not exactly one entry, missing field, unsupported `type`), a `venueType`, `exchange` and `segment` that `GET /exchanges` does not list together, or a segment with no live data (the message names what it lists), a `type` the strategy cannot consume (a ticker strategy with a `kline` source, or the reverse; the message names both), an invalid `visibility`, an invalid `paper` block (an unknown field, a wrong type or an out-of-range value), or no `paper` block for a strategy that listens to its own execution events. A `relay` or `stream` that is not `true` or `false`, or a `stream` where streams are not available yet. A `warmFrom` that is not an integer from 0 to 3600. An `instruments` that is empty or `null`.
    */
   400: ResponseError;
   /**
@@ -3895,7 +4223,7 @@ export type StartLiveError = StartLiveErrors[keyof StartLiveErrors];
 
 export type StartLiveResponses = {
   /**
-   * Started — the run's own state, in the sandbox stage, with its `streamUrl` when you asked for a stream
+   * Started — the run's own state, in the sandbox stage (in the live stage for a strategy that has already been through the sandbox), with its `streamUrl` when you asked for a stream
    */
   201: LiveRunWithStream;
 };