velo.query

Executes a completed query request and collects every decoded item into the endpoint's result type. Use velo.stream() instead when you want to process supported responses incrementally.

Imports

import { Velo } from 'velo-sdk';

Example

import { Velo, futures } from 'velo-sdk';
 
const velo = new Velo({ apiKey: process.env.VELO_API_KEY! });
 
const data = await velo.query(
  futures
    .price(['close'])
    .volume(['total'])
    .for({ exchanges: ['binance-futures'], coins: ['BTC'] })
    .over({ last: '24h', resolution: '1h' }),
);
 
for (const row of data.rows()) {
  console.log(row);
}

query() also accepts a typed request object:

const stories = await velo.query({
  kind: 'news.stories',
  params: { begin: Date.now() - 60 * 60 * 1_000 },
});

Definition

function query<K extends QueryKind, P extends QueryParams<K>>(
  input: QueryInput<K, P>,
  options?: HttpRequestOptions,
): Promise<QueryResult<K, P>>;

Parameters

input

Type: QueryInput<K, P>

A direct endpoint request or a completed request builder. The request kind determines the resolved type, and incomplete fluent builders are rejected by TypeScript.

Common results include:

Input	Resolved value
Futures, options, or spot rows	A typed `Data` object
`futures.basis()`	A typed `Data` object
`orderbook.levels()`	`OrderbookData`
`options.terms()`	`TermPoint[]`
`catalog.futures()`, `.options()`, or `.spot()`	The corresponding product array
`marketCaps.history()`	`MarketCap[]`
`news.stories()`	`NewsStory[]`

Subscription requests such as news.feed() cannot be passed to query(). Execute them with velo.watch().

options

Type: HttpRequestOptions
Optional

Overrides the client's HTTP settings for every HTTP request generated by this execution.

Property	Type	Description
`signal`	`AbortSignal`	Aborts in-flight requests and pending retry waits.
`timeout`	`number`	Per-attempt timeout in milliseconds. Defaults to the client setting, initially `60_000`.
`retry`	`Partial<RetryOptions>`	Overrides the retry count and backoff for this execution.

RetryOptions has the following properties:

Property	Type	Default	Description
`retries`	`number`	`5`	Maximum retry attempts after the initial request.
`baseDelayMs`	`number`	`500`	Initial backoff delay, which doubles after each failure.
`maxDelayMs`	`number`	`10_000`	Maximum backoff delay.

Connection failures, timeouts, HTTP 408, 429, and transient 5xx responses are retried. Server-provided Retry-After values are respected when they request a longer delay.

Return Type

Type: Promise<QueryResult<K, P>>

Returns a promise whose resolved type is inferred from the request kind and parameters. Market-row requests also preserve the selected exchange and column types.

Large requests may be split into multiple HTTP requests. The SDK overlaps up to four of them while preserving request order, then collects all decoded items before resolving. Calling query() again with the same input executes it again.

Errors

Invalid request objects and incomplete or unsupported requests fail before an HTTP request is sent. Request failures reject with a VeloError subclass after the configured retry budget is exhausted. Aborting options.signal rejects with the signal's abort reason.