Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),

## [Unreleased]

### Added ✨

- `type` on `BacktestRequest` and `SweepRequest` (`DataSourceType.TICKER`, the default, or `KLINE`). A strategy
that reads candles can now be backtested and swept from Java: preparation, execution, polling, cancellation
and the sweep reads use the requested route. Until now every Java run was prepared as ticker data, so a kline
strategy over a klines dataset ended `Failed`. The TypeScript and Python SDKs already took this option.
- `getBacktestResult(exchangeId, type, jobId)`, `getSweepRunEquityCurve(exchangeId, type, ...)` and
`getBoundedSweepRunEquityCurve(exchangeId, type, ...)` on `QTSurfer` and `AuthenticatedClient`: a run is
addressed by its exchange, its type and its id, so reading a kline run needs its type. The forms without a
type keep reading the ticker route.

## [0.34.1] — 2026-10-25

### Fixed 🐛
Expand Down
17 changes: 17 additions & 0 deletions docs/backtesting.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,23 @@ A kline backtest over `exchangeId: user` requires the selected ready dataset ver
types with `400` before queueing. Upload datasets are classified from their rows when ingest reaches
`READY`, so inspect the resulting `Dataset.type` rather than assuming every upload is a ticker.

A request is a ticker run unless it says otherwise. A strategy that reads candles needs `type(DataSourceType.KLINE)`
on its `BacktestRequest` (or `SweepRequest`); the type then applies to every stage of the run, preparation,
execution, polling, cancellation, and the sweep reads. A kline strategy submitted as a ticker run ends `Failed`
with the platform's reason. To read or cancel a run from another process, address it by its type too:
`getBacktestResult(exchangeId, DataSourceType.KLINE, jobId)`; the two-argument form reads the ticker route.

```java
ResultMap result = qts.executeBacktest(BacktestRequest.builder()
.strategy(candleStrategy)
.exchangeId("user")
.datasetId("ds_candles")
.from("2026-08-01T00:00:00Z")
.to("2026-08-01T03:00:00Z")
.type(DataSourceType.KLINE)
.build()).join();
```

`executeBacktest(request)` compiles the source, prepares the requested window, submits execution, polls
both asynchronous stages, and completes with `ResultMap`. Polling uses Failsafe exponential backoff
and optional stage timeouts.
Expand Down
24 changes: 22 additions & 2 deletions src/main/java/com/qtsurfer/api/sdk/BacktestRequest.java
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
package com.qtsurfer.api.sdk;

import com.qtsurfer.api.client.model.DataSourceType;
import com.qtsurfer.api.client.model.EquityCurveOptions;
import com.qtsurfer.api.client.model.SweepBaseConfig;
import java.util.LinkedHashMap;
Expand Down Expand Up @@ -57,6 +58,10 @@
* keeps the platform defaults
* @param params scalar strategy properties for this run; an empty map keeps every
* declared property at its default
* @param type the kind of data the strategy reads, {@link DataSourceType#TICKER} (trades) or
* {@link DataSourceType#KLINE} (candles); {@code null} means
* {@code TICKER}. A strategy that reads candles needs {@code KLINE}, and over a
* user dataset that dataset's version must hold candles
*/
public record BacktestRequest(
String strategy,
Expand All @@ -69,8 +74,16 @@ public record BacktestRequest(
String datasetVersionId,
EquityCurveOptions equityCurve,
SweepBaseConfig baseConfig,
Map<String, Object> params
Map<String, Object> params,
DataSourceType type
) {
/** Compatibility constructor for callers that predate {@code type}: a ticker run. */
public BacktestRequest(String strategy, String exchangeId, String instrument, String from, String to,
Boolean storeSignals, String datasetId, String datasetVersionId,
EquityCurveOptions equityCurve, SweepBaseConfig baseConfig, Map<String, Object> params) {
this(strategy, exchangeId, instrument, from, to, storeSignals, datasetId, datasetVersionId,
equityCurve, baseConfig, params, null);
}
public BacktestRequest(String strategy, String exchangeId, String instrument, String from, String to,
Boolean storeSignals, String datasetId, String datasetVersionId) {
this(strategy, exchangeId, instrument, from, to, storeSignals, datasetId, datasetVersionId,
Expand Down Expand Up @@ -99,6 +112,7 @@ public BacktestRequest(String strategy, String exchangeId, String instrument, St
Objects.requireNonNull(from, "from");
Objects.requireNonNull(to, "to");
params = params == null ? Map.of() : Map.copyOf(params);
type = type == null ? DataSourceType.TICKER : type;
if (params.size() > 64) {
throw new IllegalArgumentException("params may hold at most 64 properties");
}
Expand Down Expand Up @@ -127,6 +141,7 @@ public static final class Builder {
private EquityCurveOptions equityCurve;
private SweepBaseConfig baseConfig;
private final Map<String, Object> params = new LinkedHashMap<>();
private DataSourceType type;

public Builder strategy(String strategy) { this.strategy = strategy; return this; }
public Builder exchangeId(String exchangeId) { this.exchangeId = exchangeId; return this; }
Expand All @@ -146,6 +161,11 @@ public static final class Builder {
* @return this builder
*/
public Builder baseConfig(SweepBaseConfig baseConfig) { this.baseConfig = baseConfig; return this; }
/**
* @param type the kind of data the strategy reads: {@code TICKER} (the default) or {@code KLINE}
* @return this builder
*/
public Builder type(DataSourceType type) { this.type = type; return this; }
/** Add or replace one scalar strategy property for this run. */
public Builder param(String name, Object value) {
this.params.put(Objects.requireNonNull(name, "name"), Objects.requireNonNull(value, "value"));
Expand All @@ -161,7 +181,7 @@ public Builder params(Map<String, Object> params) {
public BacktestRequest build() {
return new BacktestRequest(
strategy, exchangeId, instrument, from, to, storeSignals, datasetId, datasetVersionId,
equityCurve, baseConfig, params);
equityCurve, baseConfig, params, type);
}
}
}
38 changes: 38 additions & 0 deletions src/main/java/com/qtsurfer/api/sdk/QTSurfer.java
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@
import com.qtsurfer.api.client.model.Account;
import com.qtsurfer.api.client.model.AccountUsage;
import com.qtsurfer.api.client.model.Dataset;
import com.qtsurfer.api.client.model.DataSourceType;
import com.qtsurfer.api.client.model.DatasetCreated;
import com.qtsurfer.api.client.model.DatasetImportCreated;
import com.qtsurfer.api.client.model.DatasetImportRequest;
Expand Down Expand Up @@ -463,6 +464,22 @@ public BacktestOutcome getBacktestResult(String exchangeId, String jobId) {
return backtestWorkflow.readResult(exchangeId, jobId);
}

/**
* {@link #getBacktestResult(String, String)} for a run of the given data type. A run is addressed
* by its exchange, its type and its job id, so a kline run is not found under the ticker route
* the two-argument form reads.
*
* @param exchangeId exchange the run was submitted against
* @param type {@link DataSourceType#TICKER} or {@link DataSourceType#KLINE}, as the run was submitted
* @param jobId id of the execute job
*/
public BacktestOutcome getBacktestResult(String exchangeId, DataSourceType type, String jobId) {
Objects.requireNonNull(exchangeId, "exchangeId");
Objects.requireNonNull(type, "type");
Objects.requireNonNull(jobId, "jobId");
return backtestWorkflow.readResult(exchangeId, type, jobId);
}

/** @deprecated Use {@link #getBacktestResult(String, String)}. */
@Deprecated(forRemoval = false)
public BacktestOutcome backtestResult(String exchangeId, String jobId) {
Expand Down Expand Up @@ -546,6 +563,27 @@ public EquityCurveResult getSweepRunEquityCurve(
exchangeId, requestId, sweepId, runIx, outMode, resample, differential);
}

/** {@link #getSweepRunEquityCurve(String, String, String, int, EquityCurveOutMode, Integer, Boolean)} for a sweep of the given data type. */
public EquityCurveResult getSweepRunEquityCurve(
String exchangeId, DataSourceType type, String requestId, String sweepId, int runIx,
EquityCurveOutMode outMode, Integer resample, Boolean differential) {
Objects.requireNonNull(exchangeId, "exchangeId");
Objects.requireNonNull(type, "type");
Objects.requireNonNull(requestId, "requestId");
Objects.requireNonNull(sweepId, "sweepId");
return backtestWorkflow.getSweepRunEquityCurve(
exchangeId, type, requestId, sweepId, runIx, outMode, resample, differential);
}

/** {@link #getBoundedSweepRunEquityCurve(String, String, String, int, Integer)} for a sweep of the given data type. */
public BoundedEquityCurve getBoundedSweepRunEquityCurve(
String exchangeId, DataSourceType type, String requestId, String sweepId, int runIx, Integer maxResample) {
int limit = maxResample == null ? BoundedEquityCurve.DEFAULT_MAX_RESAMPLE : maxResample;
BoundedEquityCurve.validateMaxResample(limit);
return BoundedEquityCurve.decode(getSweepRunEquityCurve(
exchangeId, type, requestId, sweepId, runIx, EquityCurveOutMode.SHORT, limit, true), limit);
}

/** Read a retained sweep curve as normalized absolute points with a bounded server request. */
public BoundedEquityCurve getBoundedSweepRunEquityCurve(
String exchangeId, String requestId, String sweepId, int runIx, Integer maxResample) {
Expand Down
23 changes: 20 additions & 3 deletions src/main/java/com/qtsurfer/api/sdk/SweepRequest.java
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
package com.qtsurfer.api.sdk;

import com.qtsurfer.api.client.model.ExecuteSweepAccepted;
import com.qtsurfer.api.client.model.DataSourceType;
import com.qtsurfer.api.client.model.EquityCurveRequest;

import java.util.LinkedHashMap;
Expand Down Expand Up @@ -67,6 +68,8 @@
* {@code null} keeps the platform defaults
* @param storeSignals when {@code Boolean.TRUE}, retain emitted signals for every trial;
* {@code null} keeps the platform default
* @param type the kind of data the strategy reads, {@link DataSourceType#TICKER} (trades) or
* {@link DataSourceType#KLINE} (candles); {@code null} means {@code TICKER}
*/
public record SweepRequest(
String strategy,
Expand All @@ -83,14 +86,23 @@ public record SweepRequest(
String datasetId,
String datasetVersionId,
EquityCurveRequest equityCurve,
Boolean storeSignals
Boolean storeSignals,
DataSourceType type
) {
/** Compatibility constructor for callers that predate {@code type}: a ticker sweep. */
public SweepRequest(String strategy, String exchangeId, String instrument, String from, String to,
Map<String, ParamAxis> params, SweepSampler sampler, Integer samples, Long seed,
SweepObjective objective, WalkForwardSpec walkForward, String datasetId,
String datasetVersionId, EquityCurveRequest equityCurve, Boolean storeSignals) {
this(strategy, exchangeId, instrument, from, to, params, sampler, samples, seed, objective,
walkForward, datasetId, datasetVersionId, equityCurve, storeSignals, null);
}
public SweepRequest(String strategy, String exchangeId, String instrument, String from, String to,
Map<String, ParamAxis> params, SweepSampler sampler, Integer samples, Long seed,
SweepObjective objective, WalkForwardSpec walkForward, String datasetId,
String datasetVersionId) {
this(strategy, exchangeId, instrument, from, to, params, sampler, samples, seed, objective,
walkForward, datasetId, datasetVersionId, null, null);
walkForward, datasetId, datasetVersionId, null, null, null);
}
/**
* @throws NullPointerException when a required field is missing, or when neither
Expand Down Expand Up @@ -118,6 +130,7 @@ public SweepRequest(String strategy, String exchangeId, String instrument, Strin
throw new IllegalArgumentException("params must hold at least one axis");
}
params = Map.copyOf(params);
type = type == null ? DataSourceType.TICKER : type;
}

/**
Expand All @@ -144,6 +157,7 @@ public static final class Builder {
private String datasetVersionId;
private EquityCurveRequest equityCurve;
private Boolean storeSignals;
private DataSourceType type;

/**
* @param strategy strategy source code (Java)
Expand Down Expand Up @@ -268,6 +282,9 @@ public Builder params(Map<String, ParamAxis> params) {
/** Request storage of emitted signals for every sweep trial. */
public Builder storeSignals(boolean storeSignals) { this.storeSignals = storeSignals; return this; }

/** The kind of data the strategy reads: {@code TICKER} (the default) or {@code KLINE}. */
public Builder type(DataSourceType type) { this.type = type; return this; }

/**
* Build the request.
*
Expand All @@ -277,7 +294,7 @@ public SweepRequest build() {
return new SweepRequest(
strategy, exchangeId, instrument, from, to,
params, sampler, samples, seed, objective, walkForward,
datasetId, datasetVersionId, equityCurve, storeSignals);
datasetId, datasetVersionId, equityCurve, storeSignals, type);
}
}
}
38 changes: 38 additions & 0 deletions src/main/java/com/qtsurfer/api/sdk/auth/AuthenticatedClient.java
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
import com.qtsurfer.api.client.model.AuthTokenResponse;
import com.qtsurfer.api.client.model.CreateDatasetRequest;
import com.qtsurfer.api.client.model.Dataset;
import com.qtsurfer.api.client.model.DataSourceType;
import com.qtsurfer.api.client.model.DatasetCreated;
import com.qtsurfer.api.client.model.DatasetImportCreated;
import com.qtsurfer.api.client.model.DatasetImportRequest;
Expand Down Expand Up @@ -640,6 +641,22 @@ public BacktestOutcome getBacktestResult(String exchangeId, String jobId) {
return withRefreshOn401(() -> backtestWorkflow.readResult(exchangeId, jobId));
}

/**
* {@link #getBacktestResult(String, String)} for a run of the given data type. A run is addressed
* by its exchange, its type and its job id, so a kline run is not found under the ticker route
* the two-argument form reads.
*
* @param exchangeId exchange the run was submitted against
* @param type {@link DataSourceType#TICKER} or {@link DataSourceType#KLINE}, as the run was submitted
* @param jobId id of the execute job
*/
public BacktestOutcome getBacktestResult(String exchangeId, DataSourceType type, String jobId) {
Objects.requireNonNull(exchangeId, "exchangeId");
Objects.requireNonNull(type, "type");
Objects.requireNonNull(jobId, "jobId");
return withRefreshOn401(() -> backtestWorkflow.readResult(exchangeId, type, jobId));
}

/** @deprecated Use {@link #getBacktestResult(String, String)}. */
@Deprecated(forRemoval = false)
public BacktestOutcome backtestResult(String exchangeId, String jobId) {
Expand Down Expand Up @@ -716,6 +733,27 @@ public EquityCurveResult getSweepRunEquityCurve(
exchangeId, requestId, sweepId, runIx, outMode, resample, differential));
}

/** {@link #getSweepRunEquityCurve(String, String, String, int, EquityCurveOutMode, Integer, Boolean)} for a sweep of the given data type. */
public EquityCurveResult getSweepRunEquityCurve(
String exchangeId, DataSourceType type, String requestId, String sweepId, int runIx,
EquityCurveOutMode outMode, Integer resample, Boolean differential) {
Objects.requireNonNull(exchangeId, "exchangeId");
Objects.requireNonNull(type, "type");
Objects.requireNonNull(requestId, "requestId");
Objects.requireNonNull(sweepId, "sweepId");
return withRefreshOn401(() -> backtestWorkflow.getSweepRunEquityCurve(
exchangeId, type, requestId, sweepId, runIx, outMode, resample, differential));
}

/** {@link #getBoundedSweepRunEquityCurve(String, String, String, int, Integer)} for a sweep of the given data type. */
public BoundedEquityCurve getBoundedSweepRunEquityCurve(
String exchangeId, DataSourceType type, String requestId, String sweepId, int runIx, Integer maxResample) {
int limit = maxResample == null ? BoundedEquityCurve.DEFAULT_MAX_RESAMPLE : maxResample;
BoundedEquityCurve.validateMaxResample(limit);
return BoundedEquityCurve.decode(getSweepRunEquityCurve(
exchangeId, type, requestId, sweepId, runIx, EquityCurveOutMode.SHORT, limit, true), limit);
}

/** Read a retained sweep curve as normalized absolute points with a bounded server request. */
public BoundedEquityCurve getBoundedSweepRunEquityCurve(
String exchangeId, String requestId, String sweepId, int runIx, Integer maxResample) {
Expand Down
Loading
Loading