Market¶

Candles, rates, and market data services.

Models¶

Candle¶

Candle ¶

Bases: BaseModel

A single OHLCV bar from the MT5 price history.

Wraps one row of the numpy structured array returned by mt5.copy_rates_from_pos(), mt5.copy_rates_from(), and mt5.copy_rates_range().

ATTRIBUTE	DESCRIPTION
`time`	Bar open time as a Unix timestamp (seconds). TYPE: `int`
`open`	Opening price of the bar. TYPE: `float`
`high`	Highest price reached during the bar. TYPE: `float`
`low`	Lowest price reached during the bar. TYPE: `float`
`close`	Closing price of the bar. TYPE: `float`
`tick_volume`	Number of price ticks during the bar. TYPE: `int`
`spread`	Spread in points at bar open. TYPE: `int`
`real_volume`	Traded volume (exchange instruments only; 0 for Forex). TYPE: `int`

Services¶

MarketService¶

MarketService ¶

Retrieves OHLCV rate data from the MT5 terminal.

Wraps the three MT5 rate-copy functions: - copy_rates_from_pos — most recent N bars from the current position - copy_rates_from — N bars starting from a specific datetime - copy_rates_range — all bars within a datetime range

MT5 returns rates as a numpy structured array or a list of dicts depending on the build. The hasattr / dict-key fallback in each parser handles both shapes transparently.

get_candles ¶

get_candles(
    symbol: str, timeframe: int, count: int
) -> Result[list[Candle]]

Retrieve the most recent candles for a symbol.

Calls mt5.copy_rates_from_pos() starting at bar index 0 (the most recent completed bar) and going back count bars.

PARAMETER	DESCRIPTION
`symbol`	Trading instrument name (e.g. `"EURUSD"`). TYPE: `str`
`timeframe`	MT5 timeframe constant (e.g. `constants.TIMEFRAME_H1`). TYPE: `int`
`count`	Number of bars to retrieve. TYPE: `int`

RETURNS	DESCRIPTION
`Result[list[Candle]]`	`Result[list[Candle]]`: The list of candles in chronological
`Result[list[Candle]]`	order on success (may be empty), or a failure result if the
`Result[list[Candle]]`	MT5 call fails or the payload cannot be parsed.

copy_rates_from ¶

copy_rates_from(
    symbol: str,
    timeframe: int,
    date_from: datetime,
    count: int,
) -> Result[list[Candle]]

Retrieve candles starting from a specific datetime.

PARAMETER	DESCRIPTION
`symbol`	Trading instrument name. TYPE: `str`
`timeframe`	MT5 timeframe constant. TYPE: `int`
`date_from`	Start datetime (inclusive). TYPE: `datetime`
`count`	Number of bars to retrieve going forward from `date_from`. TYPE: `int`

RETURNS	DESCRIPTION
`Result[list[Candle]]`	`Result[list[Candle]]`: Candles in chronological order, or a
`Result[list[Candle]]`	failure result on error.

copy_rates_range ¶

copy_rates_range(
    symbol: str,
    timeframe: int,
    date_from: datetime,
    date_to: datetime,
) -> Result[list[Candle]]

Retrieve all candles within a datetime range.

PARAMETER	DESCRIPTION
`symbol`	Trading instrument name. TYPE: `str`
`timeframe`	MT5 timeframe constant. TYPE: `int`
`date_from`	Range start datetime (inclusive). TYPE: `datetime`
`date_to`	Range end datetime (inclusive). TYPE: `datetime`

RETURNS	DESCRIPTION
`Result[list[Candle]]`	`Result[list[Candle]]`: Candles in chronological order, or a
`Result[list[Candle]]`	failure result on error.

Usage¶

from syntiq_mt5 import constants

# Get recent candles
res = mt5.get_candles("EURUSD", timeframe=constants.TIMEFRAME_H1, count=100)

# Get candles from a date
from datetime import datetime, timezone
date_from = datetime(2024, 1, 1, tzinfo=timezone.utc)
res = mt5.copy_rates_from("EURUSD", constants.TIMEFRAME_D1, date_from, count=30)

# Get candles in a range
date_to = datetime(2024, 1, 31, tzinfo=timezone.utc)
res = mt5.copy_rates_range("EURUSD", constants.TIMEFRAME_H4, date_from, date_to)