api

MetaTraderAPI

MetaTraderAPI(
    login: int,
    password: str,
    server: str,
    timeout: int = 60,
    retry: int = 20,
    host: str = "localhost",
    port: int = 18812,
    wine: str | None = None,
    path: str | None = None,
    magic: int = 88888888,
    **kwargs
)

Bases: LiveAPI

API to connect MetaTrader 5 Terminal

Parameters:

• login (int) –

  description

• password (str) –

  description

• server (str) –

  description

• timeout (int, default: 60 ) –

  description. Defaults to 60.

• retry (int, default: 20 ) –

  description. Defaults to 20.

• host (str, default: 'localhost' ) –

  description. Defaults to "localhost".

• port (int, default: 18812 ) –

  description. Defaults to 18812.

• wine (str | None, default: None ) –

  description. Defaults to None.

• magic (int, default: 88888888 ) –

  description. Defaults to 88888888.

Raises:

• ConnectionRefusedError –

  description

• RuntimeError –

  description

Source code in lettrade/exchange/metatrader/api.py

def __init__(
    self,
    login: int,
    password: str,
    server: str,
    timeout: int = 60,
    retry: int = 20,
    host: str = "localhost",
    port: int = 18812,
    wine: str | None = None,
    path: str | None = None,
    magic: int = 88888888,
    **kwargs,
):
    """_summary_

    Args:
        login (int): _description_
        password (str): _description_
        server (str): _description_
        timeout (int, optional): _description_. Defaults to 60.
        retry (int, optional): _description_. Defaults to 20.
        host (str, optional): _description_. Defaults to "localhost".
        port (int, optional): _description_. Defaults to 18812.
        wine (str | None, optional): _description_. Defaults to None.
        magic (int, optional): _description_. Defaults to 88888888.

    Raises:
        ConnectionRefusedError: _description_
        RuntimeError: _description_
    """
    # Parameters
    self._config = kwargs
    self._magic = magic

    self._load_history_since = datetime.now() - timedelta(days=7)
    self._deal_time_checked = datetime.now() - timedelta(days=1)
    self._orders_stored = dict()
    self._executions_stored = dict()
    self._positions_stored = dict()

    # Update config
    self._config.update(
        host=host,
        port=port,
        login=int(login),
        password=password,
        server=server,
        wine=wine,
        path=path,
        retry=retry,
    )

    # Start enviroments
    self._refresh_environments()

account

account(**kwargs) -> dict

Metatrader 5 account information

Returns:

• dict ( dict ) –

  description

Source code in lettrade/exchange/metatrader/api.py

@mt5_connection
def account(self, **kwargs) -> dict:
    """Metatrader 5 account information

    Returns:
        dict: _description_
    """
    raw = self._mt5.account_info()
    if raw is None:
        raise _RetryException()
    return raw

bars

bars(
    symbol,
    timeframe,
    since: int | datetime | None = 0,
    to: int | datetime | None = 1000,
    **kwargs
) -> list[list]

summary

Parameters:

• symbol (_type_) –

  description

• timeframe (_type_) –

  description

• since (int | datetime | None, default: 0 ) –

  description. Defaults to 0.

• to (int | datetime | None, default: 1000 ) –

  description. Defaults to 1_000.

Returns:

• list[list] –

  list[list]: description

Source code in lettrade/exchange/metatrader/api.py

@mt5_connection
def bars(
    self,
    symbol,
    timeframe,
    since: int | datetime | None = 0,
    to: int | datetime | None = 1_000,
    **kwargs,
) -> list[list]:
    """_summary_

    Args:
        symbol (_type_): _description_
        timeframe (_type_): _description_
        since (int | datetime | None, optional): _description_. Defaults to 0.
        to (int | datetime | None, optional): _description_. Defaults to 1_000.

    Returns:
        list[list]: _description_
    """
    timeframe = TIMEFRAME_L2M[timeframe]

    if isinstance(since, int):
        raw = self._mt5.copy_rates_from_pos(symbol, timeframe, since, to)

    elif isinstance(to, int):
        raw = self._mt5.copy_rates_from(symbol, timeframe, since, to)
    else:
        raw = self._mt5.copy_rates_range(symbol, timeframe, since, to)

    if raw is None:
        raise _RetryException()
    return raw

do_order_open

do_order_open(
    symbol: str,
    size: float,
    type: int,
    price: float,
    sl: float = None,
    tp: float = None,
    tag: str | None = None,
    deviation: int = 10,
    **kwargs
) -> dict

summary

Parameters:

• symbol (str) –

  description

• size (float) –

  description

• type (int) –

  description

• price (float) –

  description

• sl (float, default: None ) –

  description. Defaults to None.

• tp (float, default: None ) –

  description. Defaults to None.

• tag (str, default: None ) –

  description. Defaults to "".

• deviation (int, default: 10 ) –

  description. Defaults to 10.

Returns:

• dict ( dict ) –

  description

Source code in lettrade/exchange/metatrader/api.py

@mt5_connection
def do_order_open(
    self,
    symbol: str,
    size: float,
    type: int,
    price: float,
    sl: float = None,
    tp: float = None,
    tag: str | None = None,
    deviation: int = 10,
    **kwargs,
) -> dict:
    """_summary_

    Args:
        symbol (str): _description_
        size (float): _description_
        type (int): _description_
        price (float): _description_
        sl (float, optional): _description_. Defaults to None.
        tp (float, optional): _description_. Defaults to None.
        tag (str, optional): _description_. Defaults to "".
        deviation (int, optional): _description_. Defaults to 10.

    Returns:
        dict: _description_
    """
    request = self._parse_trade_request(
        symbol=symbol,
        size=size,
        type=type,
        price=price,
        sl=sl,
        tp=tp,
        tag=tag,
        deviation=deviation,
    )
    raw = self._mt5.order_send(request)

    # Retry
    if raw is None:
        raise _RetryException()

    raw = self._parse_trade_send_response(raw)
    if raw.code != 0:
        raise LetLiveOrderInvalidException(raw.error, raw=raw)

    return raw

do_position_update

do_position_update(
    id: int,
    sl: float | None = None,
    tp: float | None = None,
    **kwargs
) -> dict

summary

Parameters:

• id (int) –

  description

• sl (float | None, default: None ) –

  description. Defaults to None.

• tp (float | None, default: None ) –

  description. Defaults to None.

Returns:

• dict ( dict ) –

  description

Source code in lettrade/exchange/metatrader/api.py

@mt5_connection
def do_position_update(
    self,
    id: int,
    # symbol: str,
    sl: float | None = None,
    tp: float | None = None,
    **kwargs,
) -> dict:
    """_summary_

    Args:
        id (int): _description_
        sl (float | None, optional): _description_. Defaults to None.
        tp (float | None, optional): _description_. Defaults to None.

    Returns:
        dict: _description_
    """
    request = self._parse_trade_request(
        position=id,
        # symbol=symbol,
        sl=sl,
        tp=tp,
        action=MT5.TRADE_ACTION_SLTP,
        **kwargs,
    )
    raw = self._mt5.order_send(request)

    # Retry
    if raw is None:
        raise _RetryException()

    return self._parse_trade_send_response(raw)

execution_get

execution_get(id: str, **kwargs) -> dict

summary

Parameters:

• id (str) –

  description

Returns:

• dict ( dict ) –

  description

Source code in lettrade/exchange/metatrader/api.py

@mt5_connection
def execution_get(self, id: str, **kwargs) -> dict:
    """_summary_

    Args:
        id (str): _description_

    Returns:
        dict: _description_
    """
    if id is not None:
        kwargs["ticket"] = int(id)

    raws = self._mt5.history_deals_get(**kwargs)

    # Retry
    if raws is None:
        raise _RetryException()

    if __debug__:
        logger.debug("Raw execution: %s", raws)

    return self._execution_parse_response(raws[0])

executions_get

executions_get(
    position_id: str | None = None,
    search: str | None = None,
    **kwargs
) -> list[dict]

summary

Parameters:

• position_id (str | None, default: None ) –

  description. Defaults to None.

• search (str | None, default: None ) –

  description. Defaults to None.

Returns:

• list[dict] –

  list[dict]: description

Source code in lettrade/exchange/metatrader/api.py

@mt5_connection
def executions_get(
    self,
    position_id: str | None = None,
    search: str | None = None,
    **kwargs,
) -> list[dict]:
    """_summary_

    Args:
        position_id (str | None, optional): _description_. Defaults to None.
        search (str | None, optional): _description_. Defaults to None.

    Returns:
        list[dict]: _description_
    """
    if position_id is not None:
        kwargs["position"] = int(position_id)
    if search is not None:
        kwargs["group"] = search

    raws = self._mt5.history_deals_get(**kwargs)

    # Retry
    if raws is None:
        raise _RetryException()

    # May be wrong account when position exist but no execution
    if not raws and position_id is not None:
        logger.warning(
            "Execution retry check connection when position=%s exist but no execution",
            position_id,
        )

        # Retry check mt5 connection
        raise _RetryException()

    if __debug__:
        logger.debug("Raw executions: %s", raws)

    return [self._execution_parse_response(raw) for raw in raws]

executions_total

executions_total(
    since: datetime | None = None,
    to: datetime | None = None,
    **kwargs
) -> int

summary

Parameters:

• since (datetime | None, default: None ) –

  description. Defaults to None.

• to (datetime | None, default: None ) –

  description. Defaults to None.

Returns:

• int ( int ) –

  description

Source code in lettrade/exchange/metatrader/api.py

@mt5_connection
def executions_total(
    self,
    since: datetime | None = None,
    to: datetime | None = None,
    **kwargs,
) -> int:
    """_summary_

    Args:
        since (datetime | None, optional): _description_. Defaults to None.
        to (datetime | None, optional): _description_. Defaults to None.

    Returns:
        int: _description_
    """
    if since is not None:
        kwargs["date_from"] = since
    if to is not None:
        kwargs["date_to"] = to

    raw = self._mt5.history_deals_total(**kwargs)
    if raw is None:
        raise _RetryException()
    return raw

heartbeat

heartbeat() -> bool

Heartbeat

Returns:

• bool ( bool ) –

  description

Source code in lettrade/exchange/metatrader/api.py

def heartbeat(self) -> bool:
    """Heartbeat

    Returns:
        bool: _description_
    """
    return True

init

init(**kwargs)

Source code in lettrade/exchange/live/api.py

def init(self, **kwargs):
    """"""

market

market(symbol: str, **kwargs) -> dict

summary

Parameters:

• symbol (str) –

  description

Returns:

• dict ( dict ) –

  description

Source code in lettrade/exchange/metatrader/api.py

@mt5_connection
def market(self, symbol: str, **kwargs) -> dict:
    """_summary_

    Args:
        symbol (str): _description_

    Returns:
        dict: _description_
    """
    raw = self._mt5.symbol_info(symbol)
    if raw is None:
        raise _RetryException()
    return self._market_parse_response(raw)

markets

markets(search: str | None = None, **kwargs) -> list[dict]

The filter for arranging a group of necessary symbols. If the group is specified, the function returns only symbols meeting a specified criteria.

Search example

Get symbols whose names do not contain USD, EUR, JPY and GBP search="*,!*USD*,!*EUR*,!*JPY*,!*GBP*"

Parameters:

• search (str | None, default: None ) –

  description. Defaults to None.

Returns:

• list[dict] –

  list[dict]: description

Source code in lettrade/exchange/metatrader/api.py

@mt5_connection
def markets(self, search: str | None = None, **kwargs) -> list[dict]:
    """The filter for arranging a group of necessary symbols.
    If the group is specified, the function returns only symbols meeting a specified criteria.

    Search example:
        Get symbols whose names do not contain USD, EUR, JPY and GBP
        `search="*,!*USD*,!*EUR*,!*JPY*,!*GBP*"`

    Args:
        search (str | None, optional): _description_. Defaults to None.

    Returns:
        list[dict]: _description_
    """
    raws = self._mt5.symbols_get(search)
    if raws is None:
        raise _RetryException()
    return [self._market_parse_response(raw) for raw in raws]

next

next()

Next tick action

Source code in lettrade/exchange/metatrader/api.py

def next(self):
    """Next tick action"""
    self._check_transaction_events()

order_open

order_open(order: MetaTraderOrder) -> dict

summary

Parameters:

• order (MetaTraderOrder) –

  description

Raises:

• NotImplementedError –

  description

Returns:

• dict ( dict ) –

  description

Source code in lettrade/exchange/metatrader/api.py

def order_open(self, order: "MetaTraderOrder") -> dict:
    """_summary_

    Args:
        order (MetaTraderOrder): _description_

    Raises:
        NotImplementedError: _description_

    Returns:
        dict: _description_
    """
    match order.type:
        case OrderType.Limit:
            price = order.limit_price
        case OrderType.Stop:
            price = order.stop_price
        case OrderType.Market:
            tick = self.tick_get(order.data.symbol)
            price = tick.ask if order.is_long else tick.bid
        case _:
            raise NotImplementedError(
                f"Open order type {order.type} is not implement yet"
            )

    type = MT5.ORDER_TYPE_BUY if order.is_long else MT5.ORDER_TYPE_SELL

    return self.do_order_open(
        symbol=order.data.symbol,
        type=type,
        size=order.size,
        price=price,
        sl=order.sl,
        tp=order.tp,
        tag=order.tag,
    )

orders_get

orders_get(
    id: str | None = None,
    symbol: str | None = None,
    **kwargs
) -> list[dict]

summary

Parameters:

• id (str | None, default: None ) –

  description. Defaults to None.

• symbol (str | None, default: None ) –

  description. Defaults to None.

Returns:

• list[dict] –

  list[dict]: description

Source code in lettrade/exchange/metatrader/api.py

@mt5_connection
def orders_get(
    self,
    id: str | None = None,
    symbol: str | None = None,
    **kwargs,
) -> list[dict]:
    """_summary_

    Args:
        id (str | None, optional): _description_. Defaults to None.
        symbol (str | None, optional): _description_. Defaults to None.

    Returns:
        list[dict]: _description_
    """
    if id is not None:
        kwargs["ticket"] = int(id)
    if symbol is not None:
        kwargs["symbol"] = symbol

    raws = self._mt5.orders_get(**kwargs)

    # Return None to retry
    if raws is None:
        raise _RetryException()

    return [self._order_parse_response(raw) for raw in raws]

orders_history_get

orders_history_get(
    id: str | None = None,
    position_id: str | None = None,
    since: datetime | None = None,
    to: datetime | None = None,
    **kwargs
) -> list[dict]

summary

Parameters:

• id (str | None, default: None ) –

  description. Defaults to None.

• position_id (str | None, default: None ) –

  description. Defaults to None.

• since (datetime | None, default: None ) –

  description. Defaults to None.

• to (datetime | None, default: None ) –

  description. Defaults to None.

Returns:

• list[dict] –

  list[dict]: description

Source code in lettrade/exchange/metatrader/api.py

@mt5_connection
def orders_history_get(
    self,
    id: str | None = None,
    position_id: str | None = None,
    since: datetime | None = None,
    to: datetime | None = None,
    **kwargs,
) -> list[dict]:
    """_summary_

    Args:
        id (str | None, optional): _description_. Defaults to None.
        position_id (str | None, optional): _description_. Defaults to None.
        since (datetime | None, optional): _description_. Defaults to None.
        to (datetime | None, optional): _description_. Defaults to None.

    Returns:
        list[dict]: _description_
    """
    if id is not None:
        kwargs["ticket"] = int(id)
    if position_id is not None:
        kwargs["position"] = int(position_id)
    if since is not None:
        kwargs["date_from"] = since
    if to is not None:
        kwargs["date_to"] = to

    raws = self._mt5.history_orders_get(**kwargs)

    # Retry
    if raws is None:
        raise _RetryException()

    return [self._order_parse_response(raw) for raw in raws]

orders_history_total

orders_history_total(
    since: datetime | None = None,
    to: datetime | None = None,
    **kwargs
) -> int

summary

Parameters:

• since (datetime | None, default: None ) –

  description. Defaults to None.

• to (datetime | None, default: None ) –

  description. Defaults to None.

Returns:

• int ( int ) –

  description

Source code in lettrade/exchange/metatrader/api.py

@mt5_connection
def orders_history_total(
    self,
    since: datetime | None = None,
    to: datetime | None = None,
    **kwargs,
) -> int:
    """_summary_

    Args:
        since (datetime | None, optional): _description_. Defaults to None.
        to (datetime | None, optional): _description_. Defaults to None.

    Returns:
        int: _description_
    """
    if since is not None:
        kwargs["date_from"] = since
    if to is not None:
        kwargs["date_to"] = to

    raw = self._mt5.history_orders_get(**kwargs)
    if raw is None:
        raise _RetryException()
    return raw

orders_total

orders_total(
    since: datetime | None = None,
    to: datetime | None = None,
    **kwargs
) -> int

summary

Parameters:

• since (datetime | None, default: None ) –

  description. Defaults to None.

• to (datetime | None, default: None ) –

  description. Defaults to None.

Returns:

• int ( int ) –

  description

Source code in lettrade/exchange/metatrader/api.py

@mt5_connection
def orders_total(
    self,
    since: datetime | None = None,
    to: datetime | None = None,
    **kwargs,
) -> int:
    """_summary_

    Args:
        since (datetime | None, optional): _description_. Defaults to None.
        to (datetime | None, optional): _description_. Defaults to None.

    Returns:
        int: _description_
    """
    if since is not None:
        kwargs["date_from"] = since
    if to is not None:
        kwargs["date_to"] = to

    raw = self._mt5.orders_total(**kwargs)
    if raw is None:
        raise _RetryException()

    return raw

position_close

position_close(
    position: MetaTraderPosition, **kwargs
) -> dict

Close a position

Parameters:

• position (MetaTraderPosition) –

  description

Returns:

• dict ( dict ) –

  description

Source code in lettrade/exchange/metatrader/api.py

def position_close(self, position: "MetaTraderPosition", **kwargs) -> dict:
    """Close a position

    Args:
        position (MetaTraderPosition): _description_

    Returns:
        dict: _description_
    """
    tick = self.tick_get(position.data.symbol)
    price = tick.ask if position.is_long else tick.bid

    # Opposite with position side
    type = MT5.ORDER_TYPE_SELL if position.is_long else MT5.ORDER_TYPE_BUY

    return self.do_position_close(
        id=int(position.id),
        symbol=position.data.symbol,
        type=type,
        size=position.size,
        price=price,
        **kwargs,
    )

position_update

position_update(
    position: MetaTraderPosition,
    sl: float | None = None,
    tp: float | None = None,
    **kwargs
) -> dict

summary

Parameters:

• position (MetaTraderPosition) –

  description

• sl (float | None, default: None ) –

  description. Defaults to None.

• tp (float | None, default: None ) –

  description. Defaults to None.

Returns:

• dict ( dict ) –

  description

Source code in lettrade/exchange/metatrader/api.py

def position_update(
    self,
    position: "MetaTraderPosition",
    sl: float | None = None,
    tp: float | None = None,
    **kwargs,
) -> dict:
    """_summary_

    Args:
        position (MetaTraderPosition): _description_
        sl (float | None, optional): _description_. Defaults to None.
        tp (float | None, optional): _description_. Defaults to None.

    Returns:
        dict: _description_
    """
    return self.do_position_update(
        id=int(position.id),
        symbol=position.data.symbol,
        sl=sl,
        tp=tp,
        **kwargs,
    )

positions_get

positions_get(
    id: str = None, symbol: str = None, **kwargs
) -> list[dict]

summary

Parameters:

• id (str, default: None ) –

  description. Defaults to None.

• symbol (str, default: None ) –

  description. Defaults to None.

Returns:

• list[dict] –

  list[dict]: description

Source code in lettrade/exchange/metatrader/api.py

@mt5_connection
def positions_get(
    self,
    id: str = None,
    symbol: str = None,
    **kwargs,
) -> list[dict]:
    """_summary_

    Args:
        id (str, optional): _description_. Defaults to None.
        symbol (str, optional): _description_. Defaults to None.

    Returns:
        list[dict]: _description_
    """
    if id is not None:
        kwargs.update(ticket=int(id))
    if symbol is not None:
        kwargs.update(symbol=symbol)

    raws = self._mt5.positions_get(**kwargs)

    # Retry
    if raws is None:
        raise _RetryException()

    return [self._position_parse_response(raw) for raw in raws]

positions_total

positions_total(
    since: datetime | None = None,
    to: datetime | None = None,
    **kwargs
) -> int

summary

Parameters:

• since (datetime | None, default: None ) –

  description. Defaults to None.

• to (datetime | None, default: None ) –

  description. Defaults to None.

Returns:

• int ( int ) –

  description

Source code in lettrade/exchange/metatrader/api.py

@mt5_connection
def positions_total(
    self,
    since: datetime | None = None,
    to: datetime | None = None,
    **kwargs,
) -> int:
    """_summary_

    Args:
        since (datetime | None, optional): _description_. Defaults to None.
        to (datetime | None, optional): _description_. Defaults to None.

    Returns:
        int: _description_
    """
    if since is not None:
        kwargs["date_from"] = since
    if to is not None:
        kwargs["date_to"] = to

    raw = self._mt5.positions_total(**kwargs)
    if raw is None:
        raise _RetryException()
    return raw

start

start(exchange: MetaTraderExchange)

summary

Parameters:

• exchange (MetaTraderExchange) –

  description

Source code in lettrade/exchange/metatrader/api.py

def start(self, exchange: "MetaTraderExchange"):
    """_summary_

    Args:
        exchange (MetaTraderExchange): _description_
    """
    self._exchange = exchange

    self._load_history_transactions()
    self._check_transaction_events()

stop

stop()

Stop MetaTrader 5 Terminal

Source code in lettrade/exchange/metatrader/api.py

def stop(self):
    """Stop MetaTrader 5 Terminal"""
    self._mt5.shutdown()

tick_get

tick_get(symbol: str, **kwargs) -> dict

summary

Parameters:

• symbol (str) –

  description

Returns:

• dict ( dict ) –

  description

Source code in lettrade/exchange/metatrader/api.py

@mt5_connection
def tick_get(self, symbol: str, **kwargs) -> dict:
    """_summary_

    Args:
        symbol (str): _description_

    Returns:
        dict: _description_
    """
    raw = self._mt5.symbol_info_tick(symbol)
    if raw is None:
        raise _RetryException()
    return raw