# Candles

Retrieve historical OHLC (open/high/low/close) candles for any supported mutual fund symbol.

## Making Requests

Use the `candles()` method on the `funds` resource to fetch fund candles.

> [!NOTE]
> Mutual fund candles are daily-resolution only (unlike stock candles). They do not include a `volume` field.

| Output Format          | Result Payload                          | Description                                     |
|------------------------|-----------------------------------------|-------------------------------------------------|
| **internal** (default) | `FundsCandle[]` or `FundsCandleHuman[]` | 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. |

<a name="candles"></a>
## candles

```typescript
// Positional form
candles<P>(
  symbol: string,
  params?: P,
): MarketDataPromise<FundsCandle[] | FundsCandleHuman[]>

// Object form
candles<P>(
  params: P & { symbol: string },
): MarketDataPromise<FundsCandle[] | FundsCandleHuman[]>
```

Fetches historical daily candles for a single fund symbol.

#### Parameters

- `symbol` (string)

  The fund symbol (e.g. `"VFINX"`).

- `resolution` (string, optional, default `"D"`)

  The candle resolution. Funds support daily-and-up only: `"D"`, `"daily"`, `"1D"`, `"W"`, `"weekly"`, `"1W"`, `"M"`, `"monthly"`, `"1M"`, `"Y"`, `"yearly"`, `"1Y"`, or any integer prefix of those units.

- `from` (string | Date, optional)

  Start of the date range.

- `to` (string | Date, optional)

  End of the date range.

- `countback` (number, optional)

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

- [`outputFormat`](https://www.marketdata.app/docs/sdk/js/settings#output-format) (optional): The format of the returned data. Alias: `format`.
- [`dateFormat`](https://www.marketdata.app/docs/sdk/js/settings#date-format) (optional): Date format. Alias: `dateformat`.
- [`columns`](https://www.marketdata.app/docs/sdk/js/settings#columns) (optional): Columns to include.
- [`addHeaders`](https://www.marketdata.app/docs/sdk/js/settings#headers) (optional): Whether to include headers in CSV output. Alias: `headers`.
- [`useHumanReadable`](https://www.marketdata.app/docs/sdk/js/settings#human-readable) (optional): Use human-readable field names. Alias: `human`.
- [`mode`](https://www.marketdata.app/docs/sdk/js/settings#data-mode) (optional): The data mode to use.

#### Returns

- [`MarketDataPromise<FundsCandle[] | FundsCandleHuman[] | Blob>`](https://www.marketdata.app/docs/sdk/js/client#MarketDataPromise)

### Default

```typescript
import { MarketDataClient } from "@marketdata/sdk";

const client = new MarketDataClient();

try {
  // VFINX is available without authentication (free test symbol).
  const candles = await client.funds.candles("VFINX", { countback: 30 });
  for (const c of candles) {
    console.log(`t=${c.t} o=${c.o} h=${c.h} l=${c.l} c=${c.c}`);
  }
} catch (error) {
  console.error(error);
}
```

### Date Range

```typescript
import { MarketDataClient } from "@marketdata/sdk";

const client = new MarketDataClient();

try {
  const candles = await client.funds.candles("VFINX", {
    resolution: "M",
    from: "2020-01-01",
    to: "2024-12-31",
  });
  console.log(`${candles.length} monthly bars`);
} catch (error) {
  console.error(error);
}
```

### Human Readable

```typescript
import { MarketDataClient } from "@marketdata/sdk";

const client = new MarketDataClient();

try {
  const candles = await client.funds.candles("VFINX", {
    countback: 10,
    human: true,
  });
  for (const c of candles) {
    console.log(`Date=${c.Date} Open=${c.Open} Close=${c.Close}`);
  }
} catch (error) {
  console.error(error);
}
```

<a name="FundsCandle"></a>
## FundsCandle

```typescript
interface FundsCandle {
  s?: string;
  t: number;  // timestamp
  o: number;  // open
  h: number;  // high
  l: number;  // low
  c: number;  // close
}
```

`FundsCandle` 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 NAV.
- `h` (number): High NAV.
- `l` (number): Low NAV.
- `c` (number): Closing NAV.

<a name="FundsCandleHuman"></a>
## FundsCandleHuman

```typescript
interface FundsCandleHuman {
  s?: string;
  Date: number;
  Open: number;
  High: number;
  Low: number;
  Close: number;
}
```

`FundsCandleHuman` is returned when `human: true` is set.