QTSurfer API (0.128.17)

Exchanges a long-lived API key for a short-lived JWT used by every other endpoint. This is the only endpoint that accepts an API key directly — callers should obtain a JWT here, then send it as Authorization: Bearer <token> to all other operations.

The returned JWT carries the caller's subscription tier as a claim and expires after expires_in seconds. Callers should refresh the token before expiry (or on a 401 response) by calling this endpoint again.

Your userId, current tier, and that tier's limits — no database call, safe to fetch on every page load. For live usage against these limits, see _links.usage (GET /account/usage).

How much of your account's shared storage pool (GET /account's maxTotalStorageBytes) you're currently using. Datasets, strategy-execution signals, and registered strategies all count against the same total — they compete for the same underlying storage, so there's one number to watch, not one per resource type. Not guaranteed real-time — a just-completed upload or strategy execution may take a short moment to be reflected here.

"Give me binance instruments" — returns the exchange's DEFAULT segment (spot) in data, each instrument with per-data-type coverage and market info. meta confirms the served segment (spot); HAL _links carry self plus the spot / futures segment-discovery links.

Returns the instruments for one market segment of the exchange, each with per-data-type coverage and market info. HAL _links carry self plus the spot / futures segment-discovery links; the default-segment shortcut is GET /exchange/{exchangeId}/instruments (spot).

Serves exactly one hour of raw ticker data for the given instrument on the requested exchange. The payload is a native Lastra file — QTSurfer's columnar format for tick-precision timeseries — with no JSON envelope.

One segment = one hour, aligned to UTC. The hour query parameter selects the segment and must match YYYY-MM-DDTHH (no minutes/seconds, no timezone suffix). Example: hour=2026-01-15T10 returns h10.lastra for 2026-01-15, covering [10:00:00Z, 11:00:00Z). Hours not yet available return 404.

A format=parquet query parameter switches the response to on-the-fly Parquet conversion via lastra-convert for clients that don't yet read Lastra. Lastra is the primary format and cheaper when the client can consume it.

Clients:

• lastra-java — reference Java reader/writer with per-column codecs (ALP, Gorilla, delta-varint, ZSTD) and CRC32 integrity.
• lastra-ts — TypeScript reader (~4 kB bundle, browser + Node.js).
• duckdb-lastra — DuckDB extension for ad-hoc SQL over Lastra files.
• lastra-convert — CLI + Java API for converting to/from Parquet, Reef, and CSV.
• curl -OJ for offline dumps (the Content-Disposition header sets a descriptive filename).

Same shape and semantics as /exchange/{exchangeId}/tickers/{base}/{quote}, but serves klines (aggregated bars) instead of raw ticks. One Lastra segment = one hour of klines at the exchange's native kline cadence, aligned to UTC.

Klines use the same columnar layout as tickers — readers that handle one format read the other with the same code. Use this endpoint when a per-tick payload would be too large for the window of interest.

Enqueues a prepare task over the requested date range. Returns immediately with a jobId; poll GET /backtest/{exchangeId}/{type}/prepare/{jobId} for completion.

The same params always return the same jobId (idempotent). Repeated calls with identical params do not enqueue duplicate work — they reuse the existing job.

Every source in DataSourceType can be prepared, but not every one can then be run: funding data can be prepared and is rejected by execute and executeSweep. A kline prepare takes the bar width from cadence — see PrepareRequest.

exchangeId: user is reserved for your own uploaded data. Instead of a managed exchange, it prepares from a dataset you created via POST /datasets (see the Dataset endpoints) — send datasetId in place of instrument. See PrepareRequest below for the two request shapes.

Retrieves the current state of the prepare job identified by jobId. Poll until status is Completed, Failed, or Aborted.

For a dataset prepare (exchangeId: user), coverage is reported against the dataset's own cadence grid instead of hours — see cadence/gaps/largestGapSteps on PrepareJobState.

Runs a parameter matrix over the single immutable dataset identified by requestId. The backend expands and executes the matrix internally; clients poll the returned sweepId for incremental results.

type must be ticker or kline; a kline sweep, walk-forward included, runs over bars of the cadence the request was prepared at. funding can be prepared but not swept yet: it is rejected with 400 before anything is queued.

Supplying walkForward runs the sweep in a different mode entirely. Instead of scoring every parameter vector once over the whole range, the data is split into F sequential folds; each fold optimizes the full grid on its own window and then scores only its winner on the window immediately after — data that winner was not chosen on. It answers a harder question than a leaderboard: not "which parameters won", but "does re-optimizing this periodically actually work". Omit the block and nothing changes, including the response.

The cost is the reason it is opt-in rather than always on: F folds × N vectors, so a 4-fold run over a 500-point grid is 2004 backtests where the plain sweep is 500. The request is rejected when folds × totalRuns exceeds the server's sweep budget.

Returns incremental sweep progress. The default ranked view sorts and may truncate the display leaderboard. order=natural returns every available row, untruncated, ordered by deterministic runIx; use that view when materialising durable trial rows.

The ranked view is ordered by plateau score by default, not by the raw objective. A plateau score is the objective of the worst run in a parameter point's immediate neighbourhood, so a point scores well only if the region around it also does — the highest raw score is frequently a spike that does not survive the parameters moving slightly. Pass ranking=raw for the unadjusted objective order.

Rows in the ranked view carry plateauScore and neighbourCount when plateau ranking applied. Read them together: neighbourCount: 0 means the point had no neighbours to compare against, so its plateau score is unevidenced rather than confirmed. Sweeps submitted before plateau ranking existed have no stored parameter grid to rebuild a neighbourhood from and are always ranked raw; the response's ranking field says which ordering was actually used.

A sweep submitted with walkForward answers in a different shape, and the walkForward field on the response is what tells the two apart — it appears as soon as the sweep is accepted, before any fold has finished, so it is safe to branch on while polling. There the leaderboard is one row per completed fold: that fold's winner as it scored out-of-sample, with runIx carrying the fold index rather than a grid position. The in-sample runs behind those winners are not retained — they are an optimization's working set, and only the winner survives its fold. ranking is always raw and no plateau, DSR or PBO figure is reported: the out-of-sample scores are already the honest number, and layering a certification computed over F observations on top of them would overstate what was measured.

Requests cancellation between parameter vectors. Completed rows remain readable.

How the objective moves as each parameter moves — the question a leaderboard cannot answer. A leaderboard says which point won; a sweep can spend its entire budget on an axis that never moved the objective at all, and showing only the top rows hides that completely.

A marginal takes one axis and collapses every other one: for each value of that axis, it aggregates every run that used it, whatever the rest of the parameters were. A flat marginal means the axis is irrelevant over the range swept. best, mean and worst are all reported because them disagreeing is itself the signal — a value with a high best and a poor mean works only in specific company, which is an interaction between parameters and would be invisible behind a single number.

A heatmap does the same over a pair of axes, where that interaction becomes visible directly.

Served from the sweep's stored rows: no re-run, no engine call, and it works on a sweep still in flight — the aggregates then describe the runs finished so far. Aborted runs are excluded throughout, since a run that threw measured nothing and counting it as a bad outcome would invent evidence against a parameter value that was never really tested.

This is a separate endpoint rather than extra fields on the result view because the two-dimensional half is quadratic in the axis count (N axes give N(N-1)/2 surfaces, each the product of two axes' value counts) and is not wanted on the poll that drives progress.

The resource a leaderboard row's equityCurve.url points at — only reachable when that trial's curve was actually selected (equityCurve.mode: topN or topPct on the sweep submission, and this trial ranked among the winners). Returns the exact same {points|timestamps+equities, meta} shape a plain backtest's inline equityCurve carries.

Query params reshape the response the same way a plain backtest's equityCurve options do. A param genuinely absent from the query string falls back to the equityCurve transform preference the sweep was submitted with — a param present but malformed does not fall back, it degrades the same way it always has. Above a server-side size threshold, the shape is forced regardless of either — meta.outMode in the response, not the query string or the submitted default, is the source of truth for what shape actually came back.

Enqueues an execute task that runs the strategy identified by strategyId over the data prepared by the prepare job identified by prepareJobId. The instrument and date range are recovered from the prepare job — they do not need to be sent again.

Returns immediately with a jobId; poll GET /backtest/{exchangeId}/{type}/execute/{jobId} for the result.

type must be a source that can be executed: ticker or kline. A kline strategy is fed bars of the cadence its prepareJobId was prepared at — chosen by you when preparing, not by the strategy. funding can be prepared but not executed yet: it is rejected with 400 before anything is queued.

Optionally takes params: strategy properties for this one run, applied without recompiling. This is how a sweep leaderboard winner gets re-run for its equityCurve — a sweep row carries the ten ranking metrics but never a curve, whatever its size. Compile once, call this endpoint N times with different params, and each response is an ordinary backtest result with the curve included.

The same request (same prepareJobId, strategyId, storeSignals, equityCurve, baseConfig, params) always returns the same jobId (idempotent) — a request that omits equityCurve, baseConfig or params dedupes exactly as it did before those fields existed. Two different params vectors over one prepare are two different jobs, and 9 and 9.0 are the same one.

The re-run is an independent execution rather than a replay of the sweep trial — the two paths do not share a simulator — but they are pinned to agree: one vector run both ways matches on every leaderboard metric, asserted as a regression test. Treat a difference as a bug worth reporting, not as expected behaviour.

Optionally takes baseConfig, the same SweepBaseConfig shape executeSweep accepts — initialFunding, feeRate, percentAmountToLock, etc. — so the same object can be reused against either endpoint. This endpoint has one effective fee rate rather than a sweep's independent buy/sell legs: a baseConfig that resolves to different buy/sell rates, or sets a non-default feeLeg, is rejected with 400 rather than silently collapsed to one side.

Works unchanged for a dataset-backed prepare (exchangeId: user) — the request body is identical either way, since the instrument and range are recovered from prepareJobId.

Requests cancellation of the specified execution. The execution status will transition to Aborted once the cancellation is processed. Cancellation is asynchronous — poll the GET endpoint to confirm the final status.

Retrieves the current state and results of the execute job identified by jobId. Poll until state.status is Completed, Failed, or Aborted.

A 202 means the result is not readable yet — keep polling. It is never a terminal outcome, and it carries no state, so a poll loop that stops on a terminal status will not stop on it.

Every strategy you have registered and not deleted, most recently compiled first.

Each entry carries the same provenance GET /strategy/{strategyId} does — compiledAt, requiredSources — but not its validation state, so listing stays cheap regardless of how many strategies you have. Check a specific strategy's validation with GET /strategy/{strategyId}.

With includeDeleted=true, strategies you have deleted are listed too, each with the deletedAt it was deleted at — useful to keep a copy of your list in sync, telling a deleted strategy apart from one that never existed.

Compiles raw strategy source and registers it, returning its strategyId.

The source is either Java — a class extending a strategy base class — or QTScript (beta), a compact strategy language whose braced bodies are plain Java. QTScript source begins with the strategy keyword — whitespace and comments (// or /* */) before it are ignored — and that is how the two are told apart: there is no separate endpoint and no header to set. Once registered, a strategy is used the same way whichever language it was written in.

This answers one question: is the source valid. It compiles, registers, and hands back the id — nothing more. Whether the class can actually run is POST /strategy/{strategyId}/validate, and everything known about a strategy, validation included, is read from GET /strategy/{strategyId}. One place to ask, so there is no second answer to keep in step.

A 200 means the source parsed and compiled, not that it will run. What only shows once the strategy sets up its indicators is found by validate: for QTScript, a window on an indicator name that is not registered (window nosuch m1 { ... }) registers, and validate ends failed on that line.

For Java, the strategyId is derived from what the code means, not from how it is written. Adding a comment, inserting a blank line, re-indenting, reordering imports, or moving a method around all return the same id — you have not created a second strategy. Renaming a variable, changing an identifier's case, reordering fields, or reordering statements inside a method return a different one.

For QTScript, the id is derived from the text, because indentation is part of its grammar. Only differences that cannot change the strategy are ignored: a byte-order mark, the style of line endings, whitespace at the end of a line, and blank lines before the first and after the last line. Anything else — a comment, the indentation, a blank line in between — returns a different id.

Two rules follow, and they are worth designing around:

• re-submitting a Java strategy you have only reformatted is free, and gives you back the id you already had, along with any validation already recorded against it;
• the id says nothing about behaviour. Two sources that compute the same thing by different means are two strategies, because deciding otherwise would mean deciding program equivalence.

The response also lists declaredProperties — the sweep/execute param keys this strategy is known to accept, so a caller can catch a typo'd key before submitting a sweep instead of only learning it from a rejected one. See DeclaredProperty: best-effort, not exhaustive.

Instantiates the compiled class and drives it through a bounded synthetic series, so a wiring fault surfaces here instead of at your first backtest. The verdict — pass or fail, plus any engine notices — is recorded and served from GET /strategy/{strategyId}.

Idempotent. If a verdict already exists for the current compilation it comes straight back with 200 and nothing is queued. Otherwise the check is queued and this returns 202; poll GET /strategy/{strategyId} until validation is passed or failed.

Recompiling supersedes a verdict, which makes this callable again — the old answer described bytecode that is no longer what would run.

Reports that the strategy is registered — implied by a 200 at all — and what validating it found.

A 404 means one thing: no such registered strategy for this user. It is never a stale or expired answer; registration and verdict are stored durably, not cached.

Removes a strategy from GET /strategy/{strategyId} and GET /strategies. This is not undone by re-submitting the same source to POST /strategy — that registers a new strategy, with a new id.

Backtests you already ran against this strategy are unaffected. Deleting it stops it from counting against your account and stops you from validating or re-running it under this id — it does not erase what already happened.

Only removes a strategy you registered yourself. If you copied someone else's strategy (a shared/marketplace listing), deleting your copy never affects theirs, or anyone else's.

The exact source you last submitted for this id — the same text POST /strategy derives strategyId from, whitespace and comments included.

"If available", not "always". A strategy you resolve only through a shared/marketplace listing you copied by reference carries no source of its own, and reads as a 404 here the same as a strategyId you never registered — that is the honest answer either way, since from this endpoint's point of view nothing is there to return.

Creates a dataset AND its first upload session in one call — a presigned URL your client PUTs the file to directly, no API credentials involved in that PUT. Call POST /datasets/{datasetId}/uploads/{uploadId}/finalize once the upload completes to kick off ingest.

Losing this response loses nothing: calling this dataset's POST /datasets/{datasetId}/uploads returns the very same upload session again rather than opening a new one, as long as nothing has been finalized against it yet.

v1 is ticker data only — type is not a request field, it is always "ticker" in the response. instrument must be a plain spot pair (BASE/QUOTE, exactly one /); derivative forms (e.g. BTC/USDT:USDT) are rejected.

Upload format. A CSV with a header row, a parquet file with the same columns by name, or a lastra file — our own native columnar format, the same one a dataset's dataUrl hands back by default, so a downloaded dataset can be handed to another user to upload with no conversion in between. For CSV/parquet, required: timestamp (ISO-8601, or numeric epoch seconds/millis/micros — detected from the first row, then enforced for every later row), close. Optional: open, high, low, volume, quoteVolume, bid, bidSize, ask, askSize. A lastra upload carries its own fixed column set instead and only needs a timestamp series and a close series present. Cadence and timestamp unit are discovered from the data, not declared, for all three.

A CSV upload is converted to our native columnar format (lastra) for storage. A parquet or lastra upload is stored as-is today. Either way, always check dataFormat on GET /datasets/{datasetId} and GET /datasets/{datasetId}/uploads/{uploadId} for which one dataUrl actually is, rather than assuming from how you uploaded it (a converted CSV and an uploaded lastra file both report dataFormat: "lastra").

The bytes PUT to upload.url may be that file directly, gzipped (.gz), or zipped (.zip, exactly one file inside — a dataset is one file regardless of how it travels). Format is detected from the decompressed content itself: there is no filename or Content-Type anywhere in this flow for a client to declare it with, so nothing needs to be sent besides the bytes.

Every dataset you have created and not deleted, most recently created first. Never a 404 — an empty array if you have none, same convention as GET /strategies.

With includeDeleted=true, datasets you have deleted are listed too, each with the deletedAt it was deleted at — useful to keep a copy of your list in sync, telling a deleted dataset apart from one that never existed.

Detail for one dataset, plus a self link.

Soft-delete — the dataset stops appearing in GET /datasets/GET /datasets/{datasetId} and can no longer be prepared from, but its object data is reclaimed later rather than purged inline, so a backtest already running against one of its versions is not disrupted.

Get a fresh presigned URL to upload a new version into a dataset you already have — a corrected file, or the next chunk of history. Behaves the same way POST /datasets does for a brand-new dataset's own upload: at most one upload session is open per dataset at a time, so calling this again before finalizing just hands back that same session rather than opening a second one — safe to call repeatedly if a response gets lost.

Once a session has been finalized (successfully or not), the next call here opens a genuinely new one for that dataset's next version.

Call once the file has been PUT to the upload.url from POST /datasets (or from POST /datasets/{datasetId}/uploads). Enqueues ingest and returns immediately; poll GET /datasets/{datasetId}/uploads/{uploadId} for the result.

Idempotent while the upload is still open — a repeat finalize before it has produced a version returns the same jobId rather than enqueueing a second ingest. Once it HAS produced a version, uploadId is spent: finalizing it again is a 409, even with different bytes freshly PUT to the same URL — open a new upload session instead (POST /datasets/{datasetId}/uploads) rather than reusing a spent one.

Poll after POST .../finalize until status is ready or failed. Also reports uploading (finalize not called yet, but the file was PUT) before you finalize at all.