@qtsurfer/api-client 0.18.0 → 0.20.0

package/src/generated/types.gen.ts

@@ -119,12 +119,34 @@ export type Account = {
    * Your current subscription tier.
    */
   tier: string;
+  /**
+   * 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
+   * carries the same number. The value already includes any API allowance your plan has.
+   *
+   */
+  maxExecute: number;
+  /**
+   * Maximum length, in days, of the time range of a backtest on one of your own datasets.
+   */
+  maxRangeDays: number;
+  /**
+   * Largest full grid, in parameter combinations, a sweep may run with the `grid` sampler.
+   * A grid with more combinations is refused with `400`; the `random` and `lhs` samplers run
+   * only their `samples` and are not held to it.
+   *
+   */
+  maxSweepCartesian: number;
+  /**
+   * Maximum length, in hours, of the time range of one dataset import from an exchange.
+   */
+  maxImportRangeHours: number;
   /**
    * Maximum number of active datasets your tier allows.
    */
   maxDatasets: number;
   /**
-   * Maximum size, in bytes, of a single dataset version.
+   * Maximum size, in bytes, of a single dataset version as stored, that is the `bytes` of its ready version. For a CSV upload that is the converted file, not the file you upload, so estimate from the number of rows. The Datasets guide has the details.
    */
   maxDatasetBytes: number;
   /**
@@ -512,6 +534,11 @@ export type SweepAxis =
     };
 
 export type SweepSpecRequest = {
+  /**
+   * `grid` runs every combination of the axes and is held to your plan's
+   * `maxSweepCartesian` (`GET /account`); `random` and `lhs` run `samples` combinations and are not.
+   *
+   */
   sampler?: "grid" | "random" | "lhs";
   /**
    * Reproducibility seed. If omitted, the server generates one with Java's
@@ -536,6 +563,9 @@ export type SweepBaseConfig = {
   buyFeeRate?: number;
   sellFeeRate?: number;
   feeLeg?: "RECEIVED" | "QUOTE" | "BASE";
+  /**
+   * Share of the free balance each entry locks, in percent (0-100]. Omitted, a backtest sizes every entry with everything available.
+   */
   percentAmountToLock?: number;
 };
 
@@ -1205,6 +1235,12 @@ export type StrategySummary = {
    *
    */
   requiredSources?: Array<string>;
+  /**
+   * When you deleted this strategy. Only ever present in `GET /strategies?includeDeleted=true`,
+   * and only on strategies you have deleted.
+   *
+   */
+  deletedAt?: string;
 };
 
 /**
@@ -1318,6 +1354,12 @@ export type Dataset = {
    *
    */
   currentVersionId?: string;
+  /**
+   * When you deleted this dataset. Only ever present in `GET /datasets?includeDeleted=true`,
+   * and only on datasets you have deleted.
+   *
+   */
+  deletedAt?: string;
   /**
    * When `currentVersionId` last changed. Absent until it has a value.
    */
@@ -1772,15 +1814,56 @@ 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.
+   * 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.
    */
   visibility?: "private" | "public";
   /**
-   * Request that this run's signals be relayed over its WebSocket channel once it reaches the `live` stage — see the "Live execution" guide. Has no effect while the run is still in the `sandbox` stage, regardless of this value.
+   * 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;
   name?: string;
   description?: string;
+  paper?: LivePaperConfig;
+};
+
+/**
+ * Paper trading for this run: the same economics as a backtest's `baseConfig` (same fields,
+ * defaults and limits), plus `output`. An empty object takes every default. Each quote
+ * currency the run trades gets its own simulated account, opened with `initialFunding` in
+ * that currency; accounts are never added together. As returned on a run, the block is
+ * normalised: `feeRate` is resolved into `buyFeeRate`/`sellFeeRate` and defaults are filled
+ * in.
+ *
+ */
+export type LivePaperConfig = {
+  /**
+   * Starting capital of each account, in that account's own quote currency.
+   */
+  initialFunding?: number;
+  /**
+   * Fee rate for both sides (0.001 = 0.1%). Accepted on start; returned resolved into the two fields below.
+   */
+  feeRate?: number;
+  /**
+   * Buy-side fee rate; overrides `feeRate`.
+   */
+  buyFeeRate?: number;
+  /**
+   * Sell-side fee rate; overrides `feeRate`.
+   */
+  sellFeeRate?: number;
+  /**
+   * Which asset fees are charged in. Case-insensitive on start.
+   */
+  feeLeg?: "RECEIVED" | "QUOTE" | "BASE";
+  /**
+   * Share of the account's free balance each entry locks, in percent. Omitted, the strategy's own setting applies, and without one 10%.
+   */
+  percentAmountToLock?: number;
+  /**
+   * `separate` keeps paper output out of the run's signals (read it with `GET /live/{runId}/paper`); `mix` also interleaves it into the run's signals as `type: paper`, right after the signal that caused it.
+   */
+  output?: "separate" | "mix";
 };
 
 export type UpdateLiveRequest = {
@@ -1798,6 +1881,19 @@ export type UpdateLiveParamsRequest = {
   };
 };
 
+export type SendLiveCommandRequest = {
+  /**
+   * The command's text — non-blank.
+   */
+  command: string;
+  /**
+   * An optional map of your own choosing, alongside command. Absent means none; when given, it must be a JSON object, and `command` and `properties` are the only keys the body may carry. Each entry lands as a top-level entry on the strategy's `CommandRequest` — no key is off limits, since the command's own text is kept separately.
+   */
+  properties?: {
+    [key: string]: unknown;
+  };
+};
+
 /**
  * A live run's full state, as returned by starting, reading, or stopping it through its strategy.
  */
@@ -1811,11 +1907,11 @@ export type LiveRun = {
   description?: string;
   visibility: "private" | "public";
   /**
-   * A new run always starts `SANDBOX` — a trial run compared against a second execution for agreement — and moves to `LIVE` once it passes.
+   * 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.
    */
   stage: "SANDBOX" | "LIVE";
   /**
-   * `STARTING` until first observed running; otherwise the runner's own reported state (e.g. `RUNNING`).
+   * The run's health right now: `STARTING` (no runner has reported on it yet), `RUNNING`, `LAGGING` (behind the market data, usually while catching up; clears by itself), `HUNG` (stuck inside one strategy call for longer than allowed; clears when it returns), `DEGRADED` (its independent executions produced different signals), `FAILED` (refused, could not start or failed while running; `reason` says why) or `STOPPED`. `LAGGING`, `HUNG` and `DEGRADED` come and go on a running run. The set may grow: read an unknown value as a running run with something to look at. See the Live execution guide.
    */
   state: string;
   /**
@@ -1823,7 +1919,17 @@ export type LiveRun = {
    */
   desired: "RUNNING" | "STOPPED";
   /**
-   * Present only when the run stopped because it exceeded its resource allowance.
+   * Why the run stopped or failed, when there is something to say; absent otherwise. It is never a
+   * 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:
+   * 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.
+   *
    */
   reason?: string;
   sources: Array<LiveSource>;
@@ -1835,7 +1941,7 @@ export type LiveRun = {
    */
   paramsVersion: number;
   /**
-   * Whether this run's signals are being relayed over the WebSocket channel described in the "Live execution" guide, right now. This is the effective value — `false` on a `sandbox` run regardless of what was requested at start; matches the requested value once `stage` reaches `live`.
+   * Whether this run's signals are relayed over the WebSocket channel described in the "Live execution" guide. It is the value requested at start, in either stage.
    */
   relay: boolean;
   /**
@@ -1843,11 +1949,15 @@ export type LiveRun = {
    */
   startedAtMs: number;
   /**
-   * The sandbox trial's promotion verdict, once one exists. Shape is not yet stabilized as public API — treat as opaque diagnostics.
+   * 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.
    */
   gate?: {
     [key: string]: unknown;
   };
+  /**
+   * The run's paper trading configuration as accepted at start, normalised. Absent when the run has no paper trading.
+   */
+  paper?: LivePaperConfig;
 };
 
 /**
@@ -1876,17 +1986,31 @@ export type LiveRunSummary = {
   description?: string;
   visibility: "private" | "public";
   /**
-   * A new run always starts `SANDBOX` — a trial run compared against a second execution for agreement — and moves to `LIVE` once it passes.
+   * 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.
    */
   stage: "SANDBOX" | "LIVE";
   /**
-   * `STARTING` until first observed running; otherwise the runner's own reported state (e.g. `RUNNING`).
+   * The run's health right now: `STARTING` (no runner has reported on it yet), `RUNNING`, `LAGGING` (behind the market data, usually while catching up; clears by itself), `HUNG` (stuck inside one strategy call for longer than allowed; clears when it returns), `DEGRADED` (its independent executions produced different signals), `FAILED` (refused, could not start or failed while running; `reason` says why) or `STOPPED`. `LAGGING`, `HUNG` and `DEGRADED` come and go on a running run. The set may grow: read an unknown value as a running run with something to look at. See the Live execution guide.
    */
   state: string;
   /**
    * What you last asked for. `state` can lag this briefly after `DELETE`.
    */
   desired: "RUNNING" | "STOPPED";
+  /**
+   * Why the run stopped or failed, when there is something to say; absent otherwise. It is never a
+   * 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:
+   * 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.
+   *
+   */
+  reason?: string;
   sources: Array<LiveSource>;
   /**
    * Epoch milliseconds this run was started.
@@ -1943,6 +2067,112 @@ export type LiveSignalPage = {
   _links?: PublicLiveListLinks;
 };
 
+export type LivePaper = {
+  runId: string;
+  stage: "SANDBOX" | "LIVE";
+  accounts: Array<LivePaperAccount>;
+};
+
+/**
+ * One simulated account — one per quote currency the run trades.
+ */
+export type LivePaperAccount = {
+  /**
+   * The account's quote currency; every amount below is in it.
+   */
+  currency: string;
+  initialFunding: number;
+  /**
+   * Latest recorded equity — see `equityKind`.
+   */
+  equity: number;
+  /**
+   * Market time of that value. Absent while the account holds its starting capital.
+   */
+  equityAtMs?: number;
+  /**
+   * `equity` at a closed trade, `mark` at a periodic mark-to-market (includes open positions at market price).
+   */
+  equityKind?: "equity" | "mark";
+  /**
+   * Sum of the PnL of the closed trades.
+   */
+  realisedPnl: number;
+  /**
+   * Closed trades.
+   */
+  trades: number;
+  /**
+   * Times open positions were lost because the run was restarted with them open.
+   */
+  gaps: number;
+  openPositions: Array<LivePaperPosition>;
+  kpi?: LivePaperKpi;
+};
+
+export type LivePaperPosition = {
+  instrument: string;
+  /**
+   * Amount held, in the base asset.
+   */
+  base: number;
+  /**
+   * What it cost, in the account's currency.
+   */
+  cost: number;
+};
+
+/**
+ * The same KPIs a backtest reports, over the trades closed so far. Absent until the first closed trade is recorded.
+ */
+export type LivePaperKpi = {
+  totalTrades?: number;
+  winCount?: number;
+  lossCount?: number;
+  /**
+   * Ratio (0.5 = half the trades won).
+   */
+  winRate?: number;
+  pnlTotal?: number;
+  /**
+   * Percent of `initialFunding` (0-100 scale).
+   */
+  pnlTotalPercent?: number;
+  sharpeRatio?: number | null;
+  sortinoRatio?: number | null;
+  /**
+   * Ratio (0.15 for 15%).
+   */
+  cagr?: number | null;
+  maxDrawdown?: number;
+  /**
+   * Percent (0-100 scale).
+   */
+  maxDrawdownPercent?: number;
+};
+
+export type LivePaperEquityPage = {
+  points: Array<LivePaperEquityPoint>;
+  _links?: {
+    next?: {
+      href?: string;
+    };
+  };
+};
+
+export type LivePaperEquityPoint = {
+  currency: string;
+  kind: "equity" | "mark" | "gap";
+  /**
+   * Market time of the point.
+   */
+  eventTsMs: number;
+  /**
+   * Absent on a `gap`.
+   */
+  equity?: number;
+};
+
 /**
  * One signal, in the same shape the real-time signal channel delivers.
  */
@@ -1964,9 +2194,12 @@ export type LiveSignal = {
    * The parameter set in force when this signal was produced.
    */
   paramsVersion?: number;
-  type: "hint" | "info" | "marker" | "command";
   /**
-   * `BUY`/`SELL` for a `hint`, the command name for a `command`, absent otherwise.
+   * `paper` items appear only for a run whose `paper.output` is `mix`; they are not relayed over the WebSocket channel.
+   */
+  type: "hint" | "info" | "marker" | "command" | "paper";
+  /**
+   * `BUY`/`SELL` for a `hint`, the command name for a `command`; for `paper`, what the item is: `fill`, `trade`, `equity`, `mark`, `kpi` or `gap`. Absent otherwise.
    */
   kind?: string | null;
   /**
@@ -1977,10 +2210,13 @@ export type LiveSignal = {
    * Time it was published — always at or after `eventTsMs`.
    */
   emittedAtMs: number;
-  instrument: LiveSignalInstrument;
+  /**
+   * The instrument the signal is about. `null` only for a `paper` item about a whole account (`equity`, `mark`, `kpi`), whose `data.currency` names the account.
+   */
+  instrument: LiveSignalInstrument | null;
   order?: LiveSignalOrder;
   /**
-   * The signal's own free-form payload.
+   * The signal's own free-form payload, what the strategy put there with `signal.set(...)`. Whoever may read the run may read it, so on a `public` run it is public. A signal whose `data` is over 8 KiB (8,192 bytes of its JSON) is not pushed on the WebSocket channel, and `GET /live/{runId}/signals` returns it whole.
    */
   data?: {
     [key: string]: unknown;
@@ -2032,6 +2268,18 @@ export type LiveParamsUpdateResult = {
   effectiveAtMs: number;
 };
 
+export type LiveCommandResult = {
+  runId: string;
+  /**
+   * This command's own id, generated fresh for this call. A retried request is a second, distinct command — this endpoint takes no idempotency key.
+   */
+  commandId: string;
+  /**
+   * Epoch milliseconds — the market position every execution applies this command at.
+   */
+  effectiveAtMs: number;
+};
+
 export type AuthenticateData = {
   body?: never;
   path?: never;
@@ -2313,7 +2561,14 @@ export type DownloadKlinesResponse =
 export type ListStrategiesData = {
   body?: never;
   path?: never;
-  query?: never;
+  query?: {
+    /**
+     * `true` also lists the strategies you have deleted, each with its `deletedAt`. Any other
+     * value, or leaving it out, lists only the ones you have not deleted.
+     *
+     */
+    includeDeleted?: boolean;
+  };
   url: "/strategies";
 };
 
@@ -2348,6 +2603,10 @@ export type CompileStrategyErrors = {
    *
    */
   400: ResponseError;
+  /**
+   * The source is larger than 32 KiB (32768 bytes). Every endpoint that reads a request body caps it, and the message names the cap; see the Strategy guide.
+   */
+  413: ResponseError;
   /**
    * Too many compilations in flight. Retry later.
    */
@@ -2647,7 +2906,9 @@ export type ExecuteSweepData = {
 export type ExecuteSweepErrors = {
   /**
    * Invalid sweep specification, a `type` that cannot be swept yet (`funding`), or the
-   * expanded grid exceeds the server limit.
+   * expanded grid exceeds the server limit. A full `grid` with more combinations than your
+   * plan allows (`maxSweepCartesian` in `GET /account`) is refused with a message that asks
+   * for the `random` or `lhs` sampler.
    *
    */
   400: ResponseError;
@@ -3042,7 +3303,14 @@ export type GetBacktestResultResponse =
 export type ListDatasetsData = {
   body?: never;
   path?: never;
-  query?: never;
+  query?: {
+    /**
+     * `true` also lists the datasets you have deleted, each with its `deletedAt`. Any other
+     * value, or leaving it out, lists only the ones you have not deleted.
+     *
+     */
+    includeDeleted?: boolean;
+  };
   url: "/datasets";
 };
 
@@ -3228,7 +3496,7 @@ export type FinalizeDatasetUploadErrors = {
    */
   409: ResponseError;
   /**
-   * The uploaded file exceeds your tier's size limit for a dataset.
+   * The uploaded file is many times your tier's size limit for a dataset. The limit itself applies to the stored size, which is known only after conversion, so an upload that passes here can still end `failed` when ingest finishes.
    */
   413: ResponseError;
   /**
@@ -3451,7 +3719,7 @@ export type StartLiveData = {
 
 export type StartLiveErrors = {
   /**
-   * Malformed `sources` (not exactly one entry, missing field, unsupported `type`), or an invalid `visibility`.
+   * 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.
    */
   400: ResponseError;
   /**
@@ -3605,7 +3873,7 @@ export type UpdateLiveParamsErrors = {
    */
   404: ResponseError;
   /**
-   * This run's compilation has no declared properties on record — recompile the strategy to enable runtime parameter updates.
+   * This run's compiled strategy has no record of the parameters it declares. Register the strategy again with `POST /strategy` and start a new run, since a run keeps the compiled version it started with.
    */
   409: ResponseError;
 };
@@ -3623,6 +3891,55 @@ export type UpdateLiveParamsResponses = {
 export type UpdateLiveParamsResponse =
   UpdateLiveParamsResponses[keyof UpdateLiveParamsResponses];
 
+export type SendLiveCommandData = {
+  body: SendLiveCommandRequest;
+  path: {
+    runId: string;
+  };
+  query?: never;
+  url: "/live/{runId}/commands";
+};
+
+export type SendLiveCommandErrors = {
+  /**
+   * `command` missing, not a string, blank; `properties` given but not an object; or the body carries any key other than `command` and `properties`.
+   */
+  400: ResponseError;
+  /**
+   * No such run, or you do not own it.
+   */
+  404: ResponseError;
+  /**
+   * One of three reasons, each its own message: the run is not running, so there is nothing to tell;
+   * this run's compiled strategy has no record of whether it handles commands — register the strategy
+   * again with `POST /strategy` and start a new run, since a run keeps the compiled version it started
+   * with; or the strategy does not implement `CommandRequestHandler` at all.
+   *
+   */
+  409: ResponseError;
+  /**
+   * The request body is larger than 2 KiB (2048 bytes). Every endpoint that reads a request body caps it, and the message names the cap.
+   */
+  413: ResponseError;
+  /**
+   * The command could not be delivered right now, and it was not sent — unlike a parameter update, a command has no fallback path. Try again.
+   */
+  503: ResponseError;
+};
+
+export type SendLiveCommandError =
+  SendLiveCommandErrors[keyof SendLiveCommandErrors];
+
+export type SendLiveCommandResponses = {
+  /**
+   * Accepted — on its way to every execution behind the run.
+   */
+  202: LiveCommandResult;
+};
+
+export type SendLiveCommandResponse =
+  SendLiveCommandResponses[keyof SendLiveCommandResponses];
+
 export type GetLiveRunSignalsData = {
   body?: never;
   path: {
@@ -3645,6 +3962,10 @@ export type GetLiveRunSignalsData = {
      *
      */
     instrument?: string;
+    /**
+     * Narrow to one or more signal types, comma-separated (`hint`, `info`, `marker`, `command`, `paper`). Combines with `instrument`.
+     */
+    type?: string;
     /**
      * Continue from a previous page's `_links.next`. Takes precedence over `sinceMs`.
      */
@@ -3659,7 +3980,7 @@ export type GetLiveRunSignalsData = {
 
 export type GetLiveRunSignalsErrors = {
   /**
-   * `instrument`, `sinceMs`, `limit` or `cursor` is malformed.
+   * `instrument`, `type`, `sinceMs`, `limit` or `cursor` is malformed.
    */
   400: ResponseError;
   /**
@@ -3685,6 +4006,82 @@ export type GetLiveRunSignalsResponses = {
 export type GetLiveRunSignalsResponse =
   GetLiveRunSignalsResponses[keyof GetLiveRunSignalsResponses];
 
+export type GetLiveRunPaperData = {
+  body?: never;
+  path: {
+    runId: string;
+  };
+  query?: never;
+  url: "/live/{runId}/paper";
+};
+
+export type GetLiveRunPaperErrors = {
+  /**
+   * No such run, not one you may read, or a run without paper trading.
+   */
+  404: ResponseError;
+};
+
+export type GetLiveRunPaperError =
+  GetLiveRunPaperErrors[keyof GetLiveRunPaperErrors];
+
+export type GetLiveRunPaperResponses = {
+  /**
+   * The run's paper accounts
+   */
+  200: LivePaper;
+};
+
+export type GetLiveRunPaperResponse =
+  GetLiveRunPaperResponses[keyof GetLiveRunPaperResponses];
+
+export type GetLiveRunPaperEquityData = {
+  body?: never;
+  path: {
+    runId: string;
+  };
+  query?: {
+    /**
+     * One account's quote currency, e.g. `USDT`.
+     */
+    currency?: string;
+    /**
+     * Start from this market time (epoch ms). Ignored when `cursor` is given.
+     */
+    sinceMs?: number;
+    /**
+     * Continue from a previous page's `_links.next`.
+     */
+    cursor?: string;
+    limit?: number;
+  };
+  url: "/live/{runId}/paper/equity";
+};
+
+export type GetLiveRunPaperEquityErrors = {
+  /**
+   * `sinceMs`, `limit` or `cursor` is malformed.
+   */
+  400: ResponseError;
+  /**
+   * No such run, not one you may read, or a run without paper trading.
+   */
+  404: ResponseError;
+};
+
+export type GetLiveRunPaperEquityError =
+  GetLiveRunPaperEquityErrors[keyof GetLiveRunPaperEquityErrors];
+
+export type GetLiveRunPaperEquityResponses = {
+  /**
+   * One page of the curve
+   */
+  200: LivePaperEquityPage;
+};
+
+export type GetLiveRunPaperEquityResponse =
+  GetLiveRunPaperEquityResponses[keyof GetLiveRunPaperEquityResponses];
+
 export type MintLiveConnectionTokenData = {
   body?: never;
   path?: never;