@qtsurfer/api-client 0.18.0 → 0.20.0

package/src/generated/schemas.gen.ts

@@ -173,6 +173,10 @@ one doesn't.
   required: [
     "userId",
     "tier",
+    "maxExecute",
+    "maxRangeDays",
+    "maxSweepCartesian",
+    "maxImportRangeHours",
     "maxDatasets",
     "maxDatasetBytes",
     "maxTotalStorageBytes",
@@ -189,6 +193,34 @@ one doesn't.
       description: "Your current subscription tier.",
       example: "free",
     },
+    maxExecute: {
+      type: "integer",
+      description: `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.
+`,
+      example: 10,
+    },
+    maxRangeDays: {
+      type: "integer",
+      description:
+        "Maximum length, in days, of the time range of a backtest on one of your own datasets.",
+      example: 7,
+    },
+    maxSweepCartesian: {
+      type: "integer",
+      description: `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.
+`,
+      example: 100,
+    },
+    maxImportRangeHours: {
+      type: "integer",
+      description:
+        "Maximum length, in hours, of the time range of one dataset import from an exchange.",
+      example: 6,
+    },
     maxDatasets: {
       type: "integer",
       description: "Maximum number of active datasets your tier allows.",
@@ -197,7 +229,8 @@ one doesn't.
     maxDatasetBytes: {
       type: "integer",
       format: "int64",
-      description: "Maximum size, in bytes, of a single dataset version.",
+      description:
+        "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.",
       example: 52428800,
     },
     maxTotalStorageBytes: {
@@ -776,6 +809,9 @@ export const SweepSpecRequestSchema = {
       type: "string",
       enum: ["grid", "random", "lhs"],
       default: "grid",
+      description: `\`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.
+`,
     },
     seed: {
       type: "integer",
@@ -859,6 +895,8 @@ export const SweepBaseConfigSchema = {
       format: "double",
       exclusiveMinimum: 0,
       maximum: 100,
+      description:
+        "Share of the free balance each entry locks, in percent (0-100]. Omitted, a backtest sizes every entry with everything available.",
     },
   },
 } as const;
@@ -2025,6 +2063,13 @@ not be established without constructing the strategy.
         type: "string",
       },
     },
+    deletedAt: {
+      type: "string",
+      format: "date-time",
+      description: `When you deleted this strategy. Only ever present in \`GET /strategies?includeDeleted=true\`,
+and only on strategies you have deleted.
+`,
+    },
   },
 } as const;
 
@@ -2189,6 +2234,13 @@ least one upload has finished ingesting.
 `,
       example: "dsv_8e2b4f19c6a03d7e",
     },
+    deletedAt: {
+      type: "string",
+      format: "date-time",
+      description: `When you deleted this dataset. Only ever present in \`GET /datasets?includeDeleted=true\`,
+and only on datasets you have deleted.
+`,
+    },
     updatedAt: {
       type: "string",
       format: "date-time",
@@ -2847,12 +2899,12 @@ export const StartLiveRequestSchema = {
       enum: ["private", "public"],
       default: "private",
       description:
-        "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.",
     },
     relay: {
       type: "boolean",
       default: false,
-      description: `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.`,
+      description: `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.`,
     },
     name: {
       type: "string",
@@ -2860,6 +2912,73 @@ export const StartLiveRequestSchema = {
     description: {
       type: "string",
     },
+    paper: {
+      $ref: "#/components/schemas/LivePaperConfig",
+    },
+  },
+} as const;
+
+export const LivePaperConfigSchema = {
+  type: "object",
+  additionalProperties: false,
+  description: `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.
+`,
+  properties: {
+    initialFunding: {
+      type: "number",
+      format: "double",
+      exclusiveMinimum: 0,
+      maximum: 1000000000,
+      default: 100,
+      description:
+        "Starting capital of each account, in that account's own quote currency.",
+    },
+    feeRate: {
+      type: "number",
+      format: "double",
+      minimum: 0,
+      default: 0.001,
+      description:
+        "Fee rate for both sides (0.001 = 0.1%). Accepted on start; returned resolved into the two fields below.",
+    },
+    buyFeeRate: {
+      type: "number",
+      format: "double",
+      minimum: 0,
+      description: "Buy-side fee rate; overrides `feeRate`.",
+    },
+    sellFeeRate: {
+      type: "number",
+      format: "double",
+      minimum: 0,
+      description: "Sell-side fee rate; overrides `feeRate`.",
+    },
+    feeLeg: {
+      type: "string",
+      enum: ["RECEIVED", "QUOTE", "BASE"],
+      default: "RECEIVED",
+      description:
+        "Which asset fees are charged in. Case-insensitive on start.",
+    },
+    percentAmountToLock: {
+      type: "number",
+      format: "double",
+      exclusiveMinimum: 0,
+      maximum: 100,
+      description:
+        "Share of the account's free balance each entry locks, in percent. Omitted, the strategy's own setting applies, and without one 10%.",
+    },
+    output: {
+      type: "string",
+      enum: ["separate", "mix"],
+      default: "separate",
+      description: `\`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.`,
+    },
   },
 } as const;
 
@@ -2892,6 +3011,23 @@ export const UpdateLiveParamsRequestSchema = {
   },
 } as const;
 
+export const SendLiveCommandRequestSchema = {
+  type: "object",
+  required: ["command"],
+  properties: {
+    command: {
+      type: "string",
+      description: "The command's text — non-blank.",
+    },
+    properties: {
+      type: "object",
+      additionalProperties: true,
+      description:
+        "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.",
+    },
+  },
+} as const;
+
 export const LiveRunSchema = {
   type: "object",
   required: [
@@ -2932,11 +3068,12 @@ export const LiveRunSchema = {
       type: "string",
       enum: ["SANDBOX", "LIVE"],
       description:
-        "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.",
     },
     state: {
       type: "string",
-      description: `\`STARTING\` until first observed running; otherwise the runner's own reported state (e.g. \`RUNNING\`).`,
+      description:
+        "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.",
     },
     desired: {
       type: "string",
@@ -2946,8 +3083,17 @@ export const LiveRunSchema = {
     },
     reason: {
       type: "string",
-      description:
-        "Present only when the run stopped because it exceeded its resource allowance.",
+      description: `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.
+`,
     },
     sources: {
       type: "array",
@@ -2966,7 +3112,7 @@ export const LiveRunSchema = {
     },
     relay: {
       type: "boolean",
-      description: `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\`.`,
+      description: `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.`,
     },
     startedAtMs: {
       type: "integer",
@@ -2977,7 +3123,16 @@ export const LiveRunSchema = {
       type: "object",
       additionalProperties: true,
       description:
-        "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.",
+    },
+    paper: {
+      allOf: [
+        {
+          $ref: "#/components/schemas/LivePaperConfig",
+        },
+      ],
+      description:
+        "The run's paper trading configuration as accepted at start, normalised. Absent when the run has no paper trading.",
     },
   },
 } as const;
@@ -3055,11 +3210,12 @@ export const LiveRunSummarySchema = {
       type: "string",
       enum: ["SANDBOX", "LIVE"],
       description:
-        "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.",
     },
     state: {
       type: "string",
-      description: `\`STARTING\` until first observed running; otherwise the runner's own reported state (e.g. \`RUNNING\`).`,
+      description:
+        "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.",
     },
     desired: {
       type: "string",
@@ -3067,6 +3223,20 @@ export const LiveRunSummarySchema = {
       description:
         "What you last asked for. `state` can lag this briefly after `DELETE`.",
     },
+    reason: {
+      type: "string",
+      description: `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.
+`,
+    },
     sources: {
       type: "array",
       items: {
@@ -3191,6 +3361,217 @@ export const LiveSignalPageSchema = {
   },
 } as const;
 
+export const LivePaperSchema = {
+  type: "object",
+  required: ["runId", "stage", "accounts"],
+  properties: {
+    runId: {
+      type: "string",
+    },
+    stage: {
+      type: "string",
+      enum: ["SANDBOX", "LIVE"],
+    },
+    accounts: {
+      type: "array",
+      items: {
+        $ref: "#/components/schemas/LivePaperAccount",
+      },
+    },
+  },
+} as const;
+
+export const LivePaperAccountSchema = {
+  type: "object",
+  required: [
+    "currency",
+    "initialFunding",
+    "equity",
+    "realisedPnl",
+    "trades",
+    "gaps",
+    "openPositions",
+  ],
+  description: "One simulated account — one per quote currency the run trades.",
+  properties: {
+    currency: {
+      type: "string",
+      description: "The account's quote currency; every amount below is in it.",
+    },
+    initialFunding: {
+      type: "number",
+      format: "double",
+    },
+    equity: {
+      type: "number",
+      format: "double",
+      description: "Latest recorded equity — see `equityKind`.",
+    },
+    equityAtMs: {
+      type: "integer",
+      format: "int64",
+      description:
+        "Market time of that value. Absent while the account holds its starting capital.",
+    },
+    equityKind: {
+      type: "string",
+      enum: ["equity", "mark"],
+      description: `\`equity\` at a closed trade, \`mark\` at a periodic mark-to-market (includes open positions at market price).`,
+    },
+    realisedPnl: {
+      type: "number",
+      format: "double",
+      description: "Sum of the PnL of the closed trades.",
+    },
+    trades: {
+      type: "integer",
+      format: "int64",
+      description: "Closed trades.",
+    },
+    gaps: {
+      type: "integer",
+      description:
+        "Times open positions were lost because the run was restarted with them open.",
+    },
+    openPositions: {
+      type: "array",
+      items: {
+        $ref: "#/components/schemas/LivePaperPosition",
+      },
+    },
+    kpi: {
+      $ref: "#/components/schemas/LivePaperKpi",
+    },
+  },
+} as const;
+
+export const LivePaperPositionSchema = {
+  type: "object",
+  required: ["instrument", "base", "cost"],
+  properties: {
+    instrument: {
+      type: "string",
+      example: "BTC/USDT",
+    },
+    base: {
+      type: "number",
+      format: "double",
+      description: "Amount held, in the base asset.",
+    },
+    cost: {
+      type: "number",
+      format: "double",
+      description: "What it cost, in the account's currency.",
+    },
+  },
+} as const;
+
+export const LivePaperKpiSchema = {
+  type: "object",
+  description:
+    "The same KPIs a backtest reports, over the trades closed so far. Absent until the first closed trade is recorded.",
+  properties: {
+    totalTrades: {
+      type: "integer",
+      format: "int64",
+    },
+    winCount: {
+      type: "integer",
+      format: "int64",
+    },
+    lossCount: {
+      type: "integer",
+      format: "int64",
+    },
+    winRate: {
+      type: "number",
+      format: "double",
+      description: "Ratio (0.5 = half the trades won).",
+    },
+    pnlTotal: {
+      type: "number",
+      format: "double",
+    },
+    pnlTotalPercent: {
+      type: "number",
+      format: "double",
+      description: "Percent of `initialFunding` (0-100 scale).",
+    },
+    sharpeRatio: {
+      type: ["number", "null"],
+      format: "double",
+    },
+    sortinoRatio: {
+      type: ["number", "null"],
+      format: "double",
+    },
+    cagr: {
+      type: ["number", "null"],
+      format: "double",
+      description: "Ratio (0.15 for 15%).",
+    },
+    maxDrawdown: {
+      type: "number",
+      format: "double",
+    },
+    maxDrawdownPercent: {
+      type: "number",
+      format: "double",
+      description: "Percent (0-100 scale).",
+    },
+  },
+} as const;
+
+export const LivePaperEquityPageSchema = {
+  type: "object",
+  required: ["points"],
+  properties: {
+    points: {
+      type: "array",
+      items: {
+        $ref: "#/components/schemas/LivePaperEquityPoint",
+      },
+    },
+    _links: {
+      type: "object",
+      properties: {
+        next: {
+          type: "object",
+          properties: {
+            href: {
+              type: "string",
+            },
+          },
+        },
+      },
+    },
+  },
+} as const;
+
+export const LivePaperEquityPointSchema = {
+  type: "object",
+  required: ["currency", "kind", "eventTsMs"],
+  properties: {
+    currency: {
+      type: "string",
+    },
+    kind: {
+      type: "string",
+      enum: ["equity", "mark", "gap"],
+    },
+    eventTsMs: {
+      type: "integer",
+      format: "int64",
+      description: "Market time of the point.",
+    },
+    equity: {
+      type: "number",
+      format: "double",
+      description: "Absent on a `gap`.",
+    },
+  },
+} as const;
+
 export const LiveSignalSchema = {
   type: "object",
   required: [
@@ -3230,11 +3611,12 @@ export const LiveSignalSchema = {
     },
     type: {
       type: "string",
-      enum: ["hint", "info", "marker", "command"],
+      enum: ["hint", "info", "marker", "command", "paper"],
+      description: `\`paper\` items appear only for a run whose \`paper.output\` is \`mix\`; they are not relayed over the WebSocket channel.`,
     },
     kind: {
       type: ["string", "null"],
-      description: `\`BUY\`/\`SELL\` for a \`hint\`, the command name for a \`command\`, absent otherwise.`,
+      description: `\`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.`,
     },
     eventTsMs: {
       type: "integer",
@@ -3247,7 +3629,16 @@ export const LiveSignalSchema = {
       description: "Time it was published — always at or after `eventTsMs`.",
     },
     instrument: {
-      $ref: "#/components/schemas/LiveSignalInstrument",
+      anyOf: [
+        {
+          $ref: "#/components/schemas/LiveSignalInstrument",
+        },
+        {
+          type: "null",
+        },
+      ],
+      description:
+        "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.",
     },
     order: {
       $ref: "#/components/schemas/LiveSignalOrder",
@@ -3255,7 +3646,8 @@ export const LiveSignalSchema = {
     data: {
       type: "object",
       additionalProperties: true,
-      description: "The signal's own free-form payload.",
+      description:
+        "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.",
     },
     regenerated: {
       type: "boolean",
@@ -3341,3 +3733,24 @@ export const LiveParamsUpdateResultSchema = {
     },
   },
 } as const;
+
+export const LiveCommandResultSchema = {
+  type: "object",
+  required: ["runId", "commandId", "effectiveAtMs"],
+  properties: {
+    runId: {
+      type: "string",
+    },
+    commandId: {
+      type: "string",
+      description:
+        "This command's own id, generated fresh for this call. A retried request is a second, distinct command — this endpoint takes no idempotency key.",
+    },
+    effectiveAtMs: {
+      type: "integer",
+      format: "int64",
+      description:
+        "Epoch milliseconds — the market position every execution applies this command at.",
+    },
+  },
+} as const;