Candles

Retrieve historical OHLCV (open/high/low/close/volume) candles for any supported stock symbol.

Making Requests

Use the candles() method on the stocks resource to fetch candles. The method handles large intraday date ranges automatically by splitting them into year-sized chunks and fetching them concurrently (up to 50 in-flight at once), then merging the results.

Output Format	Result Payload	Description
internal (default)	StockCandle[] or StockCandleHuman[]	Array of decoded candle records, one per bar.
json	Raw JSON object	The compressed, array-keyed response object.
csv	Blob	CSV payload. Use .save(filename) to write it.

candles

// Positional form
candles<P>(
  symbol: string,
  params?: P,
): MarketDataResult<StockCandle[] | StockCandleHuman[]>

// Object form
candles<P>(
  params: P & { symbol: string },
): MarketDataResult<StockCandle[] | StockCandleHuman[]>

Fetches historical candles for a single symbol.

Parameters

• symbol (string)

  The stock symbol to fetch candles for.

• resolution (string, optional, default "D")

  The candle resolution. Common values:

  • Minute-based: "1", "5", "15", "30", "45", "minutely"
  • Hour-based: "H", "1H", "2H", "hourly"
  • Day-and-up: "D", "daily", "W", "weekly", "M", "monthly", "Y", "yearly"

• from (string | Date, optional)

  Start of the date range. Accepts ISO strings, Unix seconds as a string, or a Date.

• to (string | Date, optional)

  End of the date range. Accepts ISO strings, Unix seconds as a string, or a Date.

• countback (number, optional)

  Fetch N candles before to (mutually exclusive with from).

• extended (boolean, optional)

  Include extended-hours data for intraday resolutions.

• adjustsplits (boolean, optional)

  Adjust historical prices for splits.

• outputFormat (optional): The format of the returned data. Alias: format.

• dateFormat (optional): Date format for response timestamps. Alias: dateformat.

• columns (optional): Columns to include.

• addHeaders (optional): Whether to include headers in CSV output. Alias: headers.

• useHumanReadable (optional): Use human-readable field names. Alias: human.

• mode (optional): The data mode to use.

Returns

• MarketDataResult<StockCandle[] | StockCandleHuman[] | Blob>

Notes

• For intraday resolutions (minute- or hour-based), date ranges longer than 365 days are split into yearly chunks and fetched concurrently. The individual responses are merged back into a single chronologically ordered result.
• Up to 50 chunks can be in flight simultaneously (sliding window, not batching).

Daily Candles

import { MarketDataClient } from "marketdata-sdk-js";

const client = new MarketDataClient();

// Default resolution is "D" (daily)
const result = await client.stocks.candles("AAPL", { countback: 30 });

result.match(
  (candles) => {
    for (const c of candles) {
      console.log(`t=${c.t} o=${c.o} h=${c.h} l=${c.l} c=${c.c} v=${c.v}`);
    }
  },
  (error) => console.error(error.message),
);

Intraday Range

import { MarketDataClient } from "marketdata-sdk-js";

const client = new MarketDataClient();

// Hourly candles over a multi-year range.
// The SDK automatically splits into year-sized chunks
// and fetches them concurrently.
const result = await client.stocks.candles("AAPL", {
  resolution: "1H",
  from: new Date("2023-01-01"),
  to: new Date("2024-12-31"),
});

result.match(
  (candles) => console.log(`Got ${candles.length} bars`),
  (error) => console.error(error.message),
);

Human Readable

import { MarketDataClient } from "marketdata-sdk-js";

const client = new MarketDataClient();

const result = await client.stocks.candles("AAPL", {
  resolution: "D",
  countback: 10,
  human: true,
});

result.match(
  (candles) => {
    for (const c of candles) {
      console.log(`Date=${c.Date} Open=${c.Open} Close=${c.Close}`);
    }
  },
  (error) => console.error(error.message),
);

CSV

import { MarketDataClient, OutputFormat } from "marketdata-sdk-js";

const client = new MarketDataClient();

const result = await client.stocks.candles("AAPL", {
  resolution: "D",
  countback: 100,
  outputFormat: OutputFormat.CSV,
});

const filename = await result.save("aapl_daily.csv");
console.log(`CSV saved to: ${filename}`);

StockCandle

interface StockCandle {
  s?: string;
  t: number;  // timestamp
  o: number;  // open
  h: number;  // high
  l: number;  // low
  c: number;  // close
  v: number;  // volume
}

StockCandle uses the API's short, machine-readable field names.

Properties

• s (string, optional): Status indicator.
• t (number): Unix timestamp of the bar.
• o (number): Opening price.
• h (number): High price.
• l (number): Low price.
• c (number): Closing price.
• v (number): Volume.

StockCandleHuman

interface StockCandleHuman {
  s?: string;
  Date: number;
  Open: number;
  High: number;
  Low: number;
  Close: number;
  Volume: number;
}

StockCandleHuman is returned when human: true is set.