bbstrader.api

Handler injections that bridge the compiled C++ MetaTraderClient to a live MetaTrader 5 terminal via the Python MetaTrader5 package.

Note

The compiled bbstrader.api.client extension (MetaTraderClient, TradeRequest, AccountInfo, etc.) is documented in the C++ API reference, since it has no Python source for this generator to introspect.

api

Overview

The API Module provides a high-level client for interacting with the MetaTrader 5 platform. It serves as the primary interface for connecting to, retrieving data from, and sending commands to a MetaTrader 5 terminal from a Python application. The module is designed to simplify interactions and provide convenient data handling.

Features

• High-Level MT5 Client: A simplified client (Mt5client) for easy access to MetaTrader 5 functionalities.
• Dynamic Object Representation: Automatically patches MetaTrader 5 data objects for better string representation, making debugging easier.
• DataFrame Conversion: Includes a utility function (trade_object_to_df) to quickly convert lists of MT5 trade objects (like deals, orders, positions) into pandas DataFrames for analysis.
• Handler-Based Architecture: Uses a handler class (Mt5Handlers) to manage the underlying MetaTrader 5 API calls, promoting modularity.

Components

• Mt5client: The main client instance used to interact with the MetaTrader 5 terminal.
• Mt5Handlers: A class that encapsulates the direct calls to the MetaTrader 5 API.
• Helper Functions:
• trade_object_to_df: Converts lists of trade-related objects to pandas DataFrames.
• Dynamic patching of __str__ and __repr__ for improved object inspection.

Notes

This module requires a running MetaTrader 5 terminal and the MetaTrader5 Python package to be installed. The connection is managed by the Mt5client.

trade_object_to_df

trade_object_to_df(obj_list)

Fast conversion of a list of C++ bound objects to a pandas DataFrame.

Source code in src/bbstrader/api/__init__.py

def trade_object_to_df(obj_list):
    """
    Fast conversion of a list of C++ bound objects to a pandas DataFrame.
    """
    if not obj_list:
        return pd.DataFrame()

    first_obj = obj_list[0]
    columns = [
        name
        for name in dir(first_obj)
        if not name.startswith("_") and not callable(getattr(first_obj, name))
    ]
    fetcher = attrgetter(*columns)
    data = [fetcher(obj) for obj in obj_list]
    df = pd.DataFrame(data, columns=columns)
    return df

handlers

get_mt5_handlers

get_mt5_handlers()

Exhaustively maps all MetaTrader 5 Python functions to the C++ Handlers struct, converting return values to the appropriate types.

Source code in src/bbstrader/api/handlers.py

def get_mt5_handlers():
    """
    Exhaustively maps all MetaTrader 5 Python functions to the C++ Handlers struct,
    converting return values to the appropriate types.
    """
    h = MetaTraderHandlers()

    # 1. System & Session Management (Functions returning structs are wrapped)
    h.init_auto = lambda: mt5.initialize()
    h.init_path = lambda path: mt5.initialize(path)
    h.init_full = lambda path, login, password, server, timeout, portable: (
        mt5.initialize(
            path=path,
            login=login,
            password=password,
            server=server,
            timeout=timeout,
            portable=portable,
        )
    )
    h.login = lambda login, password, server, timeout: mt5.login(
        login=login, password=password, server=server, timeout=timeout
    )
    h.shutdown = mt5.shutdown
    h.get_version = mt5.version
    h.get_last_error = mt5.last_error
    h.get_terminal_info = lambda: _convert_obj(mt5.terminal_info(), TerminalInfo)
    h.get_account_info = lambda: _convert_obj(mt5.account_info(), AccountInfo)

    # 2. Symbols & Market Depth (Level 2)
    h.get_total_symbols = mt5.symbols_total
    h.get_symbols_all = lambda: _convert_list(mt5.symbols_get(), SymbolInfo)
    h.get_symbol_info = lambda symbol: _convert_obj(mt5.symbol_info(symbol), SymbolInfo)
    h.select_symbol = mt5.symbol_select
    h.get_symbols_by_group = lambda group: _convert_list(
        mt5.symbols_get(group), SymbolInfo
    )
    h.subscribe_book = mt5.market_book_add
    h.unsubscribe_book = mt5.market_book_release
    h.get_book_info = lambda symbol: _convert_list(
        mt5.market_book_get(symbol), BookInfo
    )

    # 3. Market Data (Rates & Ticks)
    h.get_rates_by_date = lambda symbol, timeframe, date_from, count: (
        mt5.copy_rates_from(symbol, timeframe, get_time(date_from), count)
    )
    h.get_rates_by_pos = lambda symbol, timeframe, start_pos, count: (
        mt5.copy_rates_from_pos(symbol, timeframe, start_pos, count)
    )
    h.get_rates_by_range = lambda symbol, timeframe, date_from, date_to: (
        mt5.copy_rates_range(symbol, timeframe, get_time(date_from), get_time(date_to))
    )
    h.get_ticks_by_date = lambda symbol, date_from, count, flags: mt5.copy_ticks_from(
        symbol, get_time(date_from), count, flags
    )
    h.get_ticks_by_range = lambda symbol, date_from, date_to, flags: (
        mt5.copy_ticks_range(symbol, get_time(date_from), get_time(date_to), flags)
    )

    h.get_tick_info = lambda symbol: _convert_obj(
        mt5.symbol_info_tick(symbol), TickInfo
    )

    # 4. Trading Operations
    h.check_order = lambda request: _convert_obj(check_order(request), OrderCheckResult)
    h.send_order = lambda request: _convert_obj(send_order(request), OrderSentResult)
    h.calc_margin = mt5.order_calc_margin
    h.calc_profit = mt5.order_calc_profit

    # 5. Active Orders & Positions
    h.get_orders_all = lambda: _convert_list(mt5.orders_get(), TradeOrder)
    h.get_orders_by_symbol = lambda symbol: _convert_list(
        mt5.orders_get(symbol=symbol), TradeOrder
    )
    h.get_orders_by_group = lambda group: _convert_list(
        mt5.orders_get(group=group), TradeOrder
    )
    h.get_order_by_ticket = lambda ticket: _convert_obj(
        (mt5.orders_get(ticket=ticket) or [None])[0], TradeOrder
    )
    h.get_total_orders = mt5.orders_total
    h.get_positions_all = lambda: _convert_list(mt5.positions_get(), TradePosition)
    h.get_positions_symbol = lambda symbol: _convert_list(
        mt5.positions_get(symbol=symbol), TradePosition
    )
    h.get_positions_group = lambda group: _convert_list(
        mt5.positions_get(group=group), TradePosition
    )
    h.get_position_ticket = lambda ticket: _convert_obj(
        (mt5.positions_get(ticket=ticket) or [None])[0], TradePosition
    )
    h.get_total_positions = mt5.positions_total

    # 6. Trade History (Orders & Deals)
    h.get_hist_orders_group = lambda date_from, date_to, group: _convert_list(
        mt5.history_orders_get(get_time(date_from), get_time(date_to), group=group),
        TradeOrder,
    )
    h.get_hist_orders_range = lambda date_from, date_to: _convert_list(
        mt5.history_orders_get(get_time(date_from), get_time(date_to)),
        TradeOrder,
    )
    h.get_hist_order_ticket = lambda ticket: _convert_obj(
        mt5.history_orders_get(ticket=ticket), TradeOrder
    )
    h.get_hist_orders_pos = lambda position: _convert_list(
        mt5.history_orders_get(position=position), TradeOrder
    )
    h.get_hist_orders_total = mt5.history_orders_total
    h.get_hist_deals_group = lambda date_from, date_to, group: _convert_list(
        mt5.history_deals_get(get_time(date_from), get_time(date_to), group=group),
        TradeDeal,
    )
    h.get_hist_deals_range = lambda date_from, date_to: _convert_list(
        mt5.history_deals_get(get_time(date_from), get_time(date_to)), TradeDeal
    )

    h.get_hist_deals_ticket = lambda ticket: _convert_obj(
        mt5.history_deals_get(ticket=ticket), TradeDeal
    )
    h.get_hist_deals_pos = lambda position: _convert_list(
        mt5.history_deals_get(position=position), TradeDeal
    )
    h.get_hist_deals_total = mt5.history_deals_total

    return h