Fund Candles (Python SDK)

• Last updated Sep 3, 2026
• View as Markdown

Retrieve historical price candles for any supported fund symbol.

Making Requests

Use the candles() method on the funds resource to fetch fund candles. The method supports multiple output formats:

Output Format	Return Type	Description
DATAFRAME	pandas.DataFrame or polars.DataFrame	Returns a DataFrame with candles data (default).
INTERNAL	list[FundsCandle] or list[FundsCandlesHumanReadable]	Returns a list of FundsCandle objects. When use_human_readable=True, returns a list of FundsCandlesHumanReadable objects with capitalized field names.
JSON	dict	Returns the raw JSON response as a dictionary.
CSV	str	Writes CSV data to file and returns the filename string.

candles

def candles(
    symbol: str,
    *,
    resolution: str = "D",
    from_date: str | datetime.datetime = None,
    to_date: str | datetime.datetime = None,
    date: str | datetime.datetime = None,
    countback: int = None,
    output_format: OutputFormat = OutputFormat.DATAFRAME,
    date_format: DateFormat = None,
    columns: list[str] = None,
    add_headers: bool = None,
    use_human_readable: bool = False,
    mode: Mode = None,
    filename: str | Path = None,
) -> list[FundsCandle] | list[FundsCandlesHumanReadable] | dict | str | MarketDataClientErrorResult

Fetches historical candles (OHLC) data for a fund symbol. The symbol parameter can be passed as the first positional argument or as a keyword argument. All other parameters must be keyword-only.

Parameters

• symbol (str)

  The fund symbol for which to fetch candles data.

• resolution (str, optional)

  The granularity of the candle data (e.g., "1D", "1W", "1M"). Defaults to "D" (daily).

• from_date (str | datetime.datetime, optional)

  Start date for the date range.

• to_date (str | datetime.datetime, optional)

  End date for the date range.

• date (str | datetime.datetime, optional)

  Specific date for the candles data.

• countback (int, optional)

  Number of candles to return, counting backwards from the to_date.

• output_format (OutputFormat, optional)

  The format of the returned data. Defaults to OutputFormat.DATAFRAME. See Settings for details.

• date_format (DateFormat, optional)

  The date format to use in the response. Defaults to DateFormat.UNIX. See Settings for details.

• columns (optional)

  Specify which columns to include in the response. See Settings for details.

• add_headers (optional)

  Whether to include headers in the response. See Settings for details.

• use_human_readable (optional)

  Whether to use human-readable format for values. Only applies when output_format=OutputFormat.INTERNAL. See Settings for details.

• mode (Mode, optional)

  The data mode to use. See Settings for details.

• filename (str | Path, optional)

  File path for CSV output (only used with output_format=OutputFormat.CSV).

Returns

• list[FundsCandle] | list[FundsCandlesHumanReadable] | dict | str | MarketDataClientErrorResult

  The candles data in the requested format, or a MarketDataClientErrorResult if an error occurred.

Example (DataFrame)

from marketdata import MarketDataClient

client = MarketDataClient()

# Get fund candles as DataFrame (default)
# symbol can be passed positionally or as keyword
df = client.funds.candles("VFINX")
# or
df = client.funds.candles(symbol="VFINX")

# Get candles for a date range
df = client.funds.candles(
    "VFINX",
    resolution="1D",
    from_date="2023-01-01",
    to_date="2023-01-31"
)

print(df)

Example (Internal)

from marketdata import MarketDataClient, OutputFormat

client = MarketDataClient()

# Get fund candles as internal objects
candles = client.funds.candles(
    "VFINX",
    resolution="1D",
    from_date="2023-01-01",
    to_date="2023-01-31",
    output_format=OutputFormat.INTERNAL
)

# Access individual candle properties
for candle in candles:
    print(f"Time: {candle.t}")
    print(f"Open: {candle.o}")
    print(f"High: {candle.h}")
    print(f"Low: {candle.l}")
    print(f"Close: {candle.c}")

Example (JSON)

from marketdata import MarketDataClient, OutputFormat

client = MarketDataClient()

# Get fund candles as JSON
candles = client.funds.candles(
    "VFINX",
    resolution="1D",
    from_date="2023-01-01",
    to_date="2023-01-31",
    output_format=OutputFormat.JSON
)

print(candles)

Example (CSV)

from marketdata import MarketDataClient, OutputFormat
from pathlib import Path

client = MarketDataClient()

# Get fund candles as CSV
csv_file = client.funds.candles(
    "VFINX",
    resolution="1D",
    from_date="2023-01-01",
    to_date="2023-01-31",
    output_format=OutputFormat.CSV,
    filename=Path("funds_candles.csv")
)

print(f"CSV file saved to: {csv_file}")

Example (Human Readable)

from marketdata import MarketDataClient, OutputFormat

client = MarketDataClient()

# Get fund candles in human-readable format
candles = client.funds.candles(
    "VFINX",
    resolution="1D",
    from_date="2023-01-01",
    to_date="2023-01-31",
    output_format=OutputFormat.INTERNAL,
    use_human_readable=True
)

# Access individual candle properties
for candle in candles:
    print(f"Date: {candle.Date}")
    print(f"Open: {candle.Open}")
    print(f"High: {candle.High}")
    print(f"Low: {candle.Low}")
    print(f"Close: {candle.Close}")

FundsCandle

@dataclass
class FundsCandle:
    t: datetime.datetime
    o: float
    h: float
    l: float
    c: float

FundsCandle represents a single fund candle (OHLC data), encapsulating price information for a specific time period.

Properties

• t (datetime.datetime): The timestamp for the candle (automatically converted from Unix timestamp).
• o (float): The opening price.
• h (float): The highest price.
• l (float): The lowest price.
• c (float): The closing price.

Notes

• The t field is automatically converted to a datetime.datetime object from a Unix timestamp.

FundsCandlesHumanReadable

@dataclass
class FundsCandlesHumanReadable:
    Date: datetime.datetime
    Open: float
    High: float
    Low: float
    Close: float

FundsCandlesHumanReadable represents a fund candle in human-readable format with capitalized field names and formatted values.

Properties

• Date (datetime.datetime): The timestamp for the candle (automatically converted from Unix timestamp).
• Open (float): The opening price.
• High (float): The highest price.
• Low (float): The lowest price.
• Close (float): The closing price.

Notes

• The Date field is automatically converted to a datetime.datetime object from a Unix timestamp.
• Field names use capitalized format (e.g., Open instead of o, Date instead of t).