feat: add exchanges() and instruments() discovery methods (0.3.0)

- QTSurfer#exchanges() -> List<Exchange>
- QTSurfer#instruments(String exchangeId) -> List<InstrumentDetail>
- Both wrap ExchangeApi from api-client v0.1.2 and surface failures as QTSError
- ExchangesTest covers method signatures and null-guard

Author: mrmx

CHANGELOG.md

@@ -6,6 +6,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.3.0] — 2026-05-17
+
+### Added
+
+- **Exchange & instrument discovery:**
+  - `QTSurfer#exchanges()` → `List<Exchange>` — list all exchanges available on the platform.
+  - `QTSurfer#instruments(String exchangeId)` → `List<InstrumentDetail>` — list instruments for a given exchange, including `dataFrom`/`dataTo` availability windows, `lastPrice`, and `volume24h`.
+  - Both methods wrap `net.qtsurfer.api.client.api.ExchangeApi` (already generated in `api-client v0.1.2`) and surface failures as `QTSError`.
+
 ## [0.2.0] — 2026-05-01
 
 ### Added

README.md

@@ -39,15 +39,15 @@ Where `net.qtsurfer:api-client` gives you one method per endpoint, this package
 <dependency>
   <groupId>com.github.QTSurfer</groupId>
   <artifactId>sdk-java</artifactId>
-  <version>v0.2.0</version>
+  <version>v0.3.0</version>
 </dependency>
 ```
 
 The transitive `com.github.QTSurfer:api-client-java` and `dev.failsafe:failsafe` come along automatically.
 
 ### Maven Central (future)
 
-Once published to Central, the coordinate will be `net.qtsurfer:sdk:0.2.0`.
+Once published to Central, the coordinate will be `net.qtsurfer:sdk:0.3.0`.
 
 ## Quick start
 
@@ -149,6 +149,29 @@ try (var in = qts.klines("binance", "BTC", "USDT", "2026-01-15T10", DownloadForm
 
 The caller closes the stream. HTTP errors surface as `QTSDownloadError` (subclass of `QTSError`).
 
+## Exchange & instrument discovery
+
+List available exchanges and the instruments (with data-availability windows) for a given exchange.
+
+```java
+import net.qtsurfer.api.client.model.Exchange;
+import net.qtsurfer.api.client.model.InstrumentDetail;
+
+// List exchanges
+List<Exchange> exchanges = qts.exchanges();
+exchanges.forEach(e -> System.out.println(e.getId() + " — " + e.getName()));
+// → binance — Binance
+// → binancefutures — Binance Futures
+
+// List instruments for an exchange
+List<InstrumentDetail> instruments = qts.instruments("binance");
+instruments.forEach(i -> System.out.printf(
+        "%s  data: %s → %s  last: %.2f%n",
+        i.getId(), i.getDataFrom(), i.getDataTo(), i.getLastPrice()));
+```
+
+HTTP errors surface as `QTSError`. Responses reflect live platform state — no client-side cache.
+
 ## Error hierarchy
 
 All SDK errors extend `QTSError` (a `RuntimeException`) and surface as the cause of the `CompletionException` wrapping them when the future fails.
@@ -227,10 +250,15 @@ JWT_API_TOKEN=... QTSURFER_API_URL=... QTSURFER_TEST_VERBOSE=1 mvn -B -Dtest='*I
 - [x] `Strategy` + `Backtest` handles with `id()`, `state()`, `progress()`, `await()`, `cancel()`
 - [x] Progress exposed as `Flow.Publisher<BacktestProgress>` (JDK reactive-streams)
 - [x] Hourly tickers/klines downloads (`qts.tickers(...)` / `qts.klines(...)`) with `DownloadFormat` (Lastra/Parquet)
-- [ ] TTL cache for `exchanges` / `instruments`
 
-### v0.3 — Ecosystem
+### v0.3 — Exchange & instrument discovery ✅
+
+- [x] `qts.exchanges()` → `List<Exchange>` (live, no cache)
+- [x] `qts.instruments(exchangeId)` → `List<InstrumentDetail>` with data-availability windows, last price, and 24 h volume
 
+### v0.4 — Ecosystem
+
+- [ ] TTL cache for `exchanges` / `instruments`
 - [ ] Loaders for `signalsUrl` Parquet into `duckdb-java` / `lastra-java`
 - [ ] Optional reactive adapters (Reactor / RxJava)
 

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>net.qtsurfer</groupId>
     <artifactId>sdk</artifactId>
-    <version>0.2.0</version>
+    <version>0.3.0</version>
     <packaging>jar</packaging>
 
     <name>QTSurfer SDK</name>

src/main/java/net/qtsurfer/api/sdk/QTSurfer.java

@@ -1,15 +1,20 @@
 package net.qtsurfer.api.sdk;
 
 import net.qtsurfer.api.client.api.BacktestingApi;
+import net.qtsurfer.api.client.api.ExchangeApi;
 import net.qtsurfer.api.client.binary.ExchangeBinaryDownloads;
 import net.qtsurfer.api.client.invoker.ApiClient;
 import net.qtsurfer.api.client.invoker.ApiException;
+import net.qtsurfer.api.client.model.Exchange;
+import net.qtsurfer.api.client.model.InstrumentDetail;
 import net.qtsurfer.api.client.model.ResultMap;
 import net.qtsurfer.api.sdk.errors.QTSDownloadError;
+import net.qtsurfer.api.sdk.errors.QTSError;
 import net.qtsurfer.api.sdk.internal.HttpStrategyCompileClient;
 import net.qtsurfer.api.sdk.workflows.BacktestWorkflow;
 
 import java.io.InputStream;
+import java.util.List;
 import java.util.Objects;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.ExecutorService;
@@ -40,11 +45,14 @@ public final class QTSurfer {
     private final QTSurferOptions options;
     private final BacktestWorkflow backtestWorkflow;
     private final ExchangeBinaryDownloads downloads;
+    private final ExchangeApi exchangeApi;
 
-    private QTSurfer(QTSurferOptions options, BacktestWorkflow backtestWorkflow, ExchangeBinaryDownloads downloads) {
+    private QTSurfer(QTSurferOptions options, BacktestWorkflow backtestWorkflow,
+                     ExchangeBinaryDownloads downloads, ExchangeApi exchangeApi) {
         this.options = options;
         this.backtestWorkflow = backtestWorkflow;
         this.downloads = downloads;
+        this.exchangeApi = exchangeApi;
     }
 
     public QTSurferOptions options() { return options; }
@@ -84,6 +92,35 @@ public CompletableFuture<ResultMap> backtest(BacktestRequest request, BacktestOp
         return backtestWorkflow.runFull(request, options);
     }
 
+    /**
+     * List available exchanges on the platform.
+     *
+     * @throws QTSError on HTTP 4xx/5xx or transport failure
+     */
+    public List<Exchange> exchanges() {
+        try {
+            return exchangeApi.getExchanges();
+        } catch (ApiException e) {
+            throw new QTSError("exchanges call failed: " + describe(e), e);
+        }
+    }
+
+    /**
+     * List instruments available on the given exchange, including data availability
+     * and market info.
+     *
+     * @param exchangeId exchange identifier (e.g. {@code "binance"})
+     * @throws QTSError on HTTP 4xx/5xx or transport failure
+     */
+    public List<InstrumentDetail> instruments(String exchangeId) {
+        Objects.requireNonNull(exchangeId, "exchangeId");
+        try {
+            return exchangeApi.getInstruments(exchangeId);
+        } catch (ApiException e) {
+            throw new QTSError("instruments call failed: " + describe(e), e);
+        }
+    }
+
     /**
      * Download one hour of raw tickers for an instrument as a streaming
      * {@link InputStream}. Defaults to {@link DownloadFormat#LASTRA}; pass
@@ -159,7 +196,8 @@ public QTSurfer build() {
             ExecutorService exec = opts.executor() != null ? opts.executor() : ForkJoinPool.commonPool();
             BacktestWorkflow workflow = new BacktestWorkflow(
                     new HttpStrategyCompileClient(apiClient), backtestingApi, exec);
-            return new QTSurfer(opts, workflow, new ExchangeBinaryDownloads(apiClient));
+            return new QTSurfer(opts, workflow, new ExchangeBinaryDownloads(apiClient),
+                    new ExchangeApi(apiClient));
         }
     }
 }

src/test/java/net/qtsurfer/api/sdk/ExchangesTest.java

@@ -0,0 +1,32 @@
+package net.qtsurfer.api.sdk;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+class ExchangesTest {
+
+  @Test
+  void exchangesMethodReturnsListType() throws NoSuchMethodException {
+    var method = QTSurfer.class.getMethod("exchanges");
+    assertEquals(List.class, method.getReturnType());
+  }
+
+  @Test
+  void instrumentsMethodReturnsListType() throws NoSuchMethodException {
+    var method = QTSurfer.class.getMethod("instruments", String.class);
+    assertEquals(List.class, method.getReturnType());
+  }
+
+  @Test
+  void instrumentsRejectsNullExchangeId() {
+    QTSurfer qts = QTSurfer.builder()
+        .baseUrl("https://api.qtsurfer.net/v1")
+        .token("test-token")
+        .build();
+    assertThrows(NullPointerException.class, () -> qts.instruments(null));
+  }
+}