Package com.qtsurfer.api.sdk.auth

Class AuthenticatedClient

java.lang.Object

com.qtsurfer.api.sdk.auth.AuthenticatedClient

public final class AuthenticatedClient
extends Object

Authenticated SDK session.

Created by QTSurfer.authenticate(String) (or the overload that accepts an AuthOptions). Wraps the underlying api-client, owns a JWT (in memory by default, or in the provided TokenStore), and transparently re-exchanges the API key for a fresh JWT when a call returns 401.

Exposes the same workflow surface as QTSurfer: compile, backtest, exchanges, instruments, tickers, klines. Method semantics are unchanged — only the bearer token management differs.

Refresh policy: a 401 from any call routed through the generated api-client (prepare, execute, result polling, exchanges, instruments, tickers, klines) triggers exactly one POST /v1/auth/token exchange, then the original call is retried once; a second 401 is surfaced to the caller. The one exception is compile, which talks to its endpoint directly and does not participate in this retry — see compile(String, BacktestOptions).

Method Summary

Modifier and Type	Method	Description
static AuthenticatedClient	authenticate()	Equivalent to authenticate(String, AuthOptions) with a null apikey (resolved from QTSURFER_APIKEY) and AuthOptions.defaults().
static AuthenticatedClient	authenticate(String apikey)	Equivalent to authenticate(String, AuthOptions) with AuthOptions.defaults().
static AuthenticatedClient	authenticate(String apikey, AuthOptions opts)	Mint a fresh session from the given API key.
CompletableFuture<com.qtsurfer.api.client.model.ResultMap>	backtest(BacktestRequest request)	Equivalent to backtest(BacktestRequest, BacktestOptions) with BacktestOptions.defaults().
CompletableFuture<com.qtsurfer.api.client.model.ResultMap>	backtest(BacktestRequest request, BacktestOptions opts)	Run the full compile → prepare → execute pipeline and resolve once the run reaches a terminal state (completed, failed, or canceled).
void	clear()	Drop the cached token (in memory and in the store).
CompletableFuture<Strategy>	compile(BacktestRequest request)	Convenience overload that compiles BacktestRequest.strategy() with BacktestOptions.defaults(), ignoring every other field of the request.
CompletableFuture<Strategy>	compile(BacktestRequest request, BacktestOptions opts)	Convenience overload that compiles BacktestRequest.strategy() with the given options, ignoring every other field of the request.
CompletableFuture<Strategy>	compile(String source)	Equivalent to compile(String, BacktestOptions) with BacktestOptions.defaults().
CompletableFuture<Strategy>	compile(String source, BacktestOptions opts)	Compile strategy source into a reusable Strategy handle.
com.qtsurfer.api.client.model.AuthTokenResponse	ensureToken()	Return the cached token, seeding from the TokenStore on first use, and minting a new one if neither cache nor store hold one.
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 and market info.
InputStream	klines(String exchangeId, String base, String quote, String hour)	Equivalent to klines(String, String, String, String, DownloadFormat) with DownloadFormat.LASTRA.
InputStream	klines(String exchangeId, String base, String quote, String hour, DownloadFormat format)	Download one hour of klines for an instrument as a streaming InputStream.
AuthOptions	options()	Configuration in use by this session.
com.qtsurfer.api.client.model.AuthTokenResponse	refresh()	Force a fresh JWT exchange via POST /v1/auth/token.
InputStream	tickers(String exchangeId, String base, String quote, String hour)	Equivalent to tickers(String, String, String, String, DownloadFormat) with DownloadFormat.LASTRA.
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.
com.qtsurfer.api.client.model.AuthTokenResponse	token()	Most recently minted token, or null if no exchange has happened yet.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

options

public AuthOptions options()

Configuration in use by this session.

token

public com.qtsurfer.api.client.model.AuthTokenResponse token()

Most recently minted token, or null if no exchange has happened yet.

refresh

public com.qtsurfer.api.client.model.AuthTokenResponse refresh()

Force a fresh JWT exchange via POST /v1/auth/token. Bypasses the cache; the returned token is also written to the configured TokenStore.

ensureToken

public com.qtsurfer.api.client.model.AuthTokenResponse ensureToken()

Return the cached token, seeding from the TokenStore on first use, and minting a new one if neither cache nor store hold one.

clear

public void clear()

Drop the cached token (in memory and in the store).

compile

public CompletableFuture<Strategy> compile(String source)

Equivalent to compile(String, BacktestOptions) with BacktestOptions.defaults().

compile

public CompletableFuture<Strategy> compile(String source,
 BacktestOptions opts)

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. Only opts.onProgress() is used; polling and timeout settings do not apply to this stage.

Two behaviors this session normally guarantees do not apply here: a 401 from the compile endpoint is not retried after a token refresh (the endpoint is called directly rather than through the generated client, so the failure is never recognized as unauthorized), and token resolution itself happens synchronously before the request is sent — on a session with no cached or stored token, this call blocks to mint one and throws QTSAuthError directly rather than through the returned future.

compile

public CompletableFuture<Strategy> compile(BacktestRequest request)

Convenience overload that compiles BacktestRequest.strategy() with BacktestOptions.defaults(), ignoring every other field of the request. See compile(String, BacktestOptions).

compile

public CompletableFuture<Strategy> compile(BacktestRequest request,
 BacktestOptions opts)

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)

Equivalent to backtest(BacktestRequest, BacktestOptions) with BacktestOptions.defaults().

backtest

public CompletableFuture<com.qtsurfer.api.client.model.ResultMap> backtest(BacktestRequest request,
 BacktestOptions opts)

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.

A 401 during prepare, execute, or result polling triggers one token refresh and then restarts the entire pipeline from compile — not just the stage that failed. A 401 from the compile stage itself is not retried; see compile(String, BacktestOptions).

This call resolves the session's token synchronously before scheduling any async work: on a session with no cached or stored token, it blocks to mint one and throws QTSAuthError directly (not through the returned future) if that mint fails.

Parameters:

opts - 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. Synchronous — blocks the calling thread for the HTTP round trip. Participates in the session's refresh-on-401 policy: an unauthorized response triggers one token refresh and one retry of this call.

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 and market info. Synchronous — blocks the calling thread for the HTTP round trip. Participates in the session's refresh-on-401 policy: an unauthorized response triggers one token refresh and one retry of this call.

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)

Equivalent to tickers(String, String, String, String, DownloadFormat) with DownloadFormat.LASTRA.

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. Synchronous; the caller is responsible for closing the returned stream. Participates in the session's refresh-on-401 policy: an unauthorized response triggers one token refresh and one retry of this call.

Throws:

QTSDownloadError - on HTTP 4xx/5xx or transport failure

klines

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

Equivalent to klines(String, String, String, String, DownloadFormat) with DownloadFormat.LASTRA.

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. See tickers(String, String, String, String, DownloadFormat) for blocking, closing, and refresh semantics.

Throws:

QTSDownloadError - on HTTP 4xx/5xx or transport failure

authenticate

public static AuthenticatedClient authenticate(String apikey,
 AuthOptions opts)

Mint a fresh session from the given API key.

If apikey is null or blank, the value is read from the QTSURFER_APIKEY environment variable. A QTSAuthError is raised when neither source yields a usable API key, or when the initial JWT exchange fails.

authenticate

public static AuthenticatedClient authenticate(String apikey)

Equivalent to authenticate(String, AuthOptions) with AuthOptions.defaults().

authenticate

public static AuthenticatedClient authenticate()

Equivalent to authenticate(String, AuthOptions) with a null apikey (resolved from QTSURFER_APIKEY) and AuthOptions.defaults().