@qtsurfer/api-client

Auto-generated TypeScript API client for the QTSurfer API, produced from the OpenAPI 3.1 spec with @hey-api/openapi-ts.

This package is intentionally thin: one function per operation, 1:1 with the spec. For workflow orchestration (polling, retries, domain objects, unified errors), use @qtsurfer/sdk.

• Tree-shakeable standalone functions.
• Full type safety for requests, responses, and error shapes.
• Native fetch based client via @hey-api/client-fetch.
• Works in Node.js >=20, modern browsers, Deno, and Bun.

Installation

pnpm add @qtsurfer/api-client
# or
npm install @qtsurfer/api-client

Quick start

import { client, getExchanges, prepareBacktesting } from '@qtsurfer/api-client';

client.setConfig({
  baseUrl: 'https://api.qtsurfer.com/v1',
  headers: {
    Authorization: `Bearer ${process.env.QTSURFER_TOKEN}`,
  },
});

const { data: exchanges, error } = await getExchanges();
if (error) throw error;

console.log(exchanges);

API surface

All operations are exported as standalone functions; every operation accepts an Options object and returns { data, error, response }.

| Function | Method | Path | Purpose | | -------- | ------ | ---- | ------- | | getExchanges | GET | /exchanges | List available exchanges | | getInstruments | GET | /exchange/{exchangeId}/instruments | List instruments for an exchange | | getExchangeTickersHour | GET | /exchange/{exchangeId}/tickers/{base}/{quote} | Download one hour of tickers as Lastra/Parquet | | getExchangeKlinesHour | GET | /exchange/{exchangeId}/klines/{base}/{quote} | Download one hour of klines as Lastra/Parquet | | postStrategy | POST | /strategy | Compile a strategy | | getStrategyStatus | GET | /strategy/{strategyId} | Poll strategy compilation status | | prepareBacktesting | POST | /backtesting/prepare | Start a data preparation job | | getPreparationStatus | GET | /backtesting/prepare/{jobId} | Poll preparation status | | executeBacktesting | POST | /backtesting/execute | Start a backtest execution | | cancelExecution | POST | /backtesting/execute/{jobId}/cancel | Cancel a running execution | | getExecutionResult | GET | /backtesting/execute/{jobId} | Poll or fetch execution results |

All generated types (Exchange, InstrumentDetail, BacktestJobResult, ResultMap, etc.) are re-exported from the root.

Configuring the client

The default client points to the staging server. Override via setConfig or by passing options inline:

import { client, getExchanges } from '@qtsurfer/api-client';

// Global
client.setConfig({
  baseUrl: 'https://api.qtsurfer.com/v1',
});

// Per-call
await getExchanges({
  baseUrl: 'https://api.qtsurfer.com/v1',
  headers: { 'X-Request-Id': '...' },
});

To build your own isolated client (e.g. per-tenant), use createClient from @hey-api/client-fetch.

Error handling

Each function returns a discriminated union. Narrow via error before using data:

const { data, error } = await prepareBacktesting({
  body: {
    /* PrepareBacktestingRequest */
  },
});

if (error) {
  console.error(error.code, error.message);
  return;
}

console.log(data.jobId);

Regenerating the client

The src/generated/ directory is a committed artifact produced from the OpenAPI spec hosted at QTSurfer/qtsurfer-api.

pnpm install
pnpm generate   # runs @hey-api/openapi-ts against the remote spec
pnpm lint       # tsc --noEmit
pnpm build      # emits dist/ with .js + .d.ts

Configuration lives in openapi-ts.config.ts. To generate against a local checkout instead, change input to a relative path (e.g. ../qtsurfer-api/openapi.yaml).

Development

| Script | Description | | ------ | ----------- | | pnpm generate | Regenerate the client from the OpenAPI spec | | pnpm lint | Type-check without emitting | | pnpm build | Compile to dist/ |

License

Apache-2.0 — see LICENSE.