Quick start


 QTSurfer qts = QTSurfer.builder()
     .baseUrl("https://api.qtsurfer.com/v1")
     .token(System.getenv("JWT_API_TOKEN"))
     .build();

 // One-shot shortcut:
 ResultMap result = qts.backtest(request, options).join();

 // Or decomposed for streaming / reuse:
 Strategy strategy = qts.compile(source).join();
 Backtest job = strategy.backtest(request, options).join();
 job.progress().subscribe( ... );
 ResultMap result = job.await().join();

Nested Class Summary

Nested Classes

Modifier and Type

Class

Description

static final class

QTSurfer.Builder
Method Summary

Modifier and Type

Method

Description

static AuthenticatedClient

authenticate()

Overload that reads the API key from QTSURFER_APIKEY.

static AuthenticatedClient

authenticate(String apikey)

One-call setup: exchange an API key for a short-lived JWT and return an AuthenticatedClient that mirrors this SDK's surface (compile / backtest / exchanges / instruments / tickers / klines) with automatic refresh-on-401.

static AuthenticatedClient

authenticate(String apikey, AuthOptions options)

Overload accepting an AuthOptions (base URL, token store, executor).

CompletableFuture<com.qtsurfer.api.client.model.ResultMap>

backtest(BacktestRequest request)

Run the full compile → prepare → execute → await pipeline as a single future.

CompletableFuture<com.qtsurfer.api.client.model.ResultMap>

backtest(BacktestRequest request, BacktestOptions options)

Run the full compile → prepare → execute pipeline and resolve once the run reaches a terminal state (completed, failed, or canceled).

static QTSurfer.Builder

builder()

Start building a QTSurfer client via the fluent QTSurfer.Builder.

CompletableFuture<Strategy>

compile(BacktestRequest request)

Convenience: compile the strategy embedded in the given request.

CompletableFuture<Strategy>

compile(BacktestRequest request, BacktestOptions options)

Convenience overload that compiles BacktestRequest.strategy() with the given options, ignoring every other field of the request.

CompletableFuture<Strategy>

compile(String source)

Compile a strategy source.

CompletableFuture<Strategy>

compile(String source, BacktestOptions options)

Compile strategy source into a reusable Strategy handle.

List<com.qtsurfer.api.client.model.Exchange>

exchanges()

List available exchanges on the platform.

List<com.qtsurfer.api.client.model.InstrumentDetail>

instruments(String exchangeId)

List instruments available on the given exchange, including per-data-type coverage (see InstrumentDetail.getCoverage()) and market info.

InputStream

klines(String exchangeId, String base, String quote, String hour)

Download one hour of klines for an instrument as a streaming InputStream.

InputStream

klines(String exchangeId, String base, String quote, String hour, DownloadFormat format)

Download one hour of klines for an instrument as a streaming InputStream, requesting the given DownloadFormat.

QTSurferOptions

options()

Configuration this client was built with.

InputStream

tickers(String exchangeId, String base, String quote, String hour)

Download one hour of raw tickers for an instrument as a streaming InputStream.

InputStream

tickers(String exchangeId, String base, String quote, String hour, DownloadFormat format)

Download one hour of raw tickers for an instrument as a streaming InputStream, requesting the given DownloadFormat.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details
- options
  
  public QTSurferOptions options()
  
  Configuration this client was built with.
- compile
  
  public CompletableFuture<Strategy> compile(String source)
  
  Compile a strategy source. Resolves with a Strategy handle you can reuse.
- compile
  
  public CompletableFuture<Strategy> compile(String source, BacktestOptions options)
  
  Compile strategy source into a reusable Strategy handle.
  Issues a single synchronous HTTP request; the compile endpoint returns the strategyId directly, so a failing compile surfaces immediately as QTSStrategyCompileError rather than on a later poll. A 429 means the platform was holding too many compilations and the source was never judged, so it is safe to retry; any other error status reflects a judgment on the submitted code and will not succeed by retrying alone.
  
  Parameters:
  
  options - tuning knobs; only onProgress is used here (a single COMPILING event) — polling and timeout settings do not apply to this stage
- compile
  
  public CompletableFuture<Strategy> compile(BacktestRequest request)
  
  Convenience: compile the strategy embedded in the given request.
- compile
  
  public CompletableFuture<Strategy> compile(BacktestRequest request, BacktestOptions options)
  
  Convenience overload that compiles BacktestRequest.strategy() with the given options, ignoring every other field of the request. See compile(String, BacktestOptions).
- backtest
  
  public CompletableFuture<com.qtsurfer.api.client.model.ResultMap> backtest(BacktestRequest request)
  
  Run the full compile → prepare → execute → await pipeline as a single future. Equivalent to compile(request).thenCompose(s -> s.backtest(request, options)).thenCompose(Backtest::await).
- backtest
  
  public CompletableFuture<com.qtsurfer.api.client.model.ResultMap> backtest(BacktestRequest request, BacktestOptions options)
  
  Run the full compile → prepare → execute pipeline and resolve once the run reaches a terminal state (completed, failed, or canceled). The returned future completes exceptionally with QTSStrategyCompileError if compilation fails, QTSPreparationError if data preparation fails, QTSExecutionError if execution fails, or QTSTimeoutError if a stage exceeds its configured timeout.
  
  Parameters:
  
  options - tuning knobs (poll interval, timeout, progress callback) applied to every stage of the pipeline
- exchanges
  
  public List<com.qtsurfer.api.client.model.Exchange> exchanges()
  
  List available exchanges on the platform.
  
  Throws:
  
  QTSError - on HTTP 4xx/5xx or transport failure
- instruments
  
  public List<com.qtsurfer.api.client.model.InstrumentDetail> instruments(String exchangeId)
  
  List instruments available on the given exchange, including per-data-type coverage (see InstrumentDetail.getCoverage()) and market info.
  Unwraps the InstrumentListResponse HAL envelope returned by the underlying API client and returns just the instrument list.
  
  Parameters:
  
  exchangeId - exchange identifier (e.g. "binance")
  
  Throws:
  
  QTSError - on HTTP 4xx/5xx or transport failure
- tickers
  
  public InputStream tickers(String exchangeId, String base, String quote, String hour)
  
  Download one hour of raw tickers for an instrument as a streaming InputStream. Defaults to DownloadFormat.LASTRA; pass DownloadFormat.PARQUET for on-the-fly Parquet conversion.
  The caller is responsible for closing the stream — typically via try-with-resources, piping to Files.copy(...), or feeding it into a Lastra/Parquet reader.
  
  Throws:
  
  QTSDownloadError - on HTTP 4xx/5xx or transport failure
- tickers
  
  public InputStream tickers(String exchangeId, String base, String quote, String hour, DownloadFormat format)
  
  Download one hour of raw tickers for an instrument as a streaming InputStream, requesting the given DownloadFormat. The 4-argument overload delegates here with DownloadFormat.LASTRA.
  
  Throws:
  
  QTSDownloadError - on HTTP 4xx/5xx or transport failure
- klines
  
  public InputStream klines(String exchangeId, String base, String quote, String hour)
  
  Download one hour of klines for an instrument as a streaming InputStream. See tickers(java.lang.String, java.lang.String, java.lang.String, java.lang.String) for semantics.
  
  Throws:
  
  QTSDownloadError - on HTTP 4xx/5xx or transport failure
- klines
  
  public InputStream klines(String exchangeId, String base, String quote, String hour, DownloadFormat format)
  
  Download one hour of klines for an instrument as a streaming InputStream, requesting the given DownloadFormat. See tickers(String, String, String, String, DownloadFormat) for stream-closing semantics.
  
  Throws:
  
  QTSDownloadError - on HTTP 4xx/5xx or transport failure
- authenticate
  
  public static AuthenticatedClient authenticate(String apikey)
  
  One-call setup: exchange an API key for a short-lived JWT and return an AuthenticatedClient that mirrors this SDK's surface (compile / backtest / exchanges / instruments / tickers / klines) with automatic refresh-on-401.
  If apikey is null or blank, the value is read from the QTSURFER_APIKEY environment variable.
  
  Throws:
  
  QTSAuthError - when no API key is available or the initial JWT exchange fails.
- authenticate
  
  public static AuthenticatedClient authenticate(String apikey, AuthOptions options)
  
  Overload accepting an AuthOptions (base URL, token store, executor).
- authenticate
  
  public static AuthenticatedClient authenticate()
  
  Overload that reads the API key from QTSURFER_APIKEY.
- builder
  
  public static QTSurfer.Builder builder()
  
  Start building a QTSurfer client via the fluent QTSurfer.Builder.

Class QTSurfer

Quick start

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Details

options

compile

compile

compile

compile

backtest

backtest

exchanges

instruments

tickers

tickers

klines

klines

authenticate

authenticate

authenticate

builder