Asynchronous MetaTrader5 library and Bot Building Framework
Project description
aiomql
Installation
pip install aiomql
Key Features
- Asynchronous Python Library For MetaTrader 5
- Build bots for trading in different financial markets using a bot factory
- Use threadpool executors to run multiple strategies on multiple instruments concurrently
- Record and keep track of trades and strategies in csv files.
- Utility classes for using the MetaTrader 5 Library
- Sample Pre-Built strategies
Simple Usage as an asynchronous MetaTrader5 Libray
import asyncio
# import the class
from aiomql import MetaTrader, Account, TimeFrame, OrderType
async def main():
# Assuming your login details are already defined in the aiomql.json somewhere in your project directory.
acc = Account()
# if this is unsuccessful the program exits
await acc.sign_in()
# print all available symbols
print(acc.symbols)
asyncio.run(main())
As a Bot Building FrameWork using a Sample Strategy
from aiomql import Bot
from aiomql import ForexSymbol
from aiomql import FingerTrap
# Create a bot instance
bot = Bot()
# Choose a Symbol to trade
symbol = ForexSymbol(name='EURUSD')
# Create a strategy
ft_eur_usd = FingerTrap(symbol=symbol)
# Add strategy to Bot
bot.add_strategy(ft_eur_usd)
# run the bot
bot.execute()
Api Documentation
aiomql
aiomql.account
Account Objects
class Account(AccountInfo)
A class for managing a trading account. A singleton class. A subclass of AccountInfo. All AccountInfo attributes are available in this class.
Attributes:
connected
bool - Status of connection to MetaTrader 5 Terminalsymbols
set[SymbolInfo] - A set of available symbols for the financial market.
Notes:
Other Account properties are defined in the AccountInfo class.
refresh
async def refresh()
Refreshes the account instance with the latest account details from the MetaTrader 5 terminal
account_info
@property
def account_info() -> dict
Get account login, server and password details. If the login attribute of the account instance returns a falsy value, the config instance is used to get the account details.
Returns:
dict
- A dict of login, server and password details
Notes:
This method will only look for config details in the config instance if the login attribute of the account Instance returns a falsy value
sign_in
async def sign_in() -> bool
Connect to a trading account.
Returns:
bool
- True if login was successful else False
has_symbol
def has_symbol(symbol: str | Type[SymbolInfo])
Checks to see if a symbol is available for a trading account
Arguments:
symbol (str | SymbolInfo):
Returns:
bool
- True if symbol is present otherwise False
symbols_get
async def symbols_get() -> set[SymbolInfo]
Get all financial instruments from the MetaTrader 5 terminal available for the current account.
Returns:
set[Symbol]
- A set of available symbols.
aiomql.bot_builder
Bot Objects
class Bot()
The bot builder class. This class is used to build a bot by adding strategies and running them in the executor.
Attributes:
account
Account - Account Object.executor
- The default thread executor.symbols
set[Symbols] - A set of symbols for the trading session
initialize
async def initialize()
Prepares the bot by signing in to the trading account and initializing the symbols for the trading session.
Raises:
SystemExit if sign in was not successful
execute
def execute()
Execute the bot.
start
async def start()
Starts the bot by calling the initialize method and running the strategies in the executor.
add_strategy
def add_strategy(strategy: Strategy)
Add a strategy to the executor. An added strategy will only run if it's symbol was successfully initialized.
Arguments:
strategy
Strategy - A Strategy instance to run on bot
Notes:
Make sure the symbol has been added to the market
add_strategies
def add_strategies(strategies: Iterable[Strategy])
Add multiple strategies at the same time
Arguments:
strategies
- A list of strategies
add_strategy_all
def add_strategy_all(*, strategy: Type[Strategy], params: dict | None = None)
Use this to run a single strategy on all available instruments in the market using the default parameters i.e one set of parameters for all trading symbols
Arguments:
strategy
Strategy - Strategy classparams
dict - A dictionary of parameters for the strategy
init_symbols
async def init_symbols()
Initialize the symbols for the current trading session. This method is called internally by the bot.
init_symbol
async def init_symbol(symbol: Symbol) -> Symbol
Initialize a symbol before the beginning of a trading sessions. Removes it from the list of symbols if it was not successfully initialized or not available for the current market.
Arguments:
symbol
Symbol - Symbol object to be initialized
Returns:
symbol
Symbol - if successfully initialized
aiomql.candle
Candle and Candles classes for handling bars from the MetaTrader 5 terminal.
Candle Objects
class Candle()
A class representing bars from the MetaTrader 5 terminal as a customized class analogous to Japanese Candlesticks. You can subclass this class for added customization.
Attributes:
time
int - Period start time.open
int - Open pricehigh
float - The highest price of the periodlow
float - The lowest price of the periodclose
float - Close pricetick_volume
float - Tick volumereal_volume
float - Trade volumespread
float - SpreadIndex
int - Custom attribute representing the position of the candle in a sequence.
__init__
def __init__(**kwargs)
Create a Candle object from keyword arguments.
Arguments:
**kwargs
- Candle attributes and values as keyword arguments.
set_attributes
def set_attributes(**kwargs)
Set keyword arguments as instance attributes
Arguments:
**kwargs
- Instance attributes and values as keyword arguments
mid
@property
def mid() -> float
The median of open and close
Returns:
float
- The median of open and close
is_bullish
def is_bullish() -> bool
A simple check to see if the candle is bullish.
Returns:
bool
- True or False
is_bearish
def is_bearish() -> bool
A simple check to see if the candle is bearish.
Returns:
bool
- True or False
Candles Objects
class Candles(Generic[_Candle])
An iterable container class of Candle objects in chronological order.
Attributes:
-
Index
Series['int'] - A pandas Series of the indexes of all candles in the object. -
time
Series['int'] - A pandas Series of the time of all candles in the object. -
open
Series[float] - A pandas Series of the opening price of all candles in the object. -
high
Series[float] - A pandas Series of the high price of all candles in the object. -
low
Series[float] - A pandas Series of the low price of all candles in the object. -
close
Series[float] - A pandas Series of the closing price of all candles in the object. -
tick_volume
Series[float] - A pandas Series of the tick volume of all candles in the object. -
real_volume
Series[float] - A pandas Series of the real volume of all candles in the object. -
spread
Series[float] - A pandas Series of the spread of all candles in the object. -
timeframe
TimeFrame - The timeframe of the candles in the object. -
Candle
Type[Candle] - The Candle class for representing the candles in the object.properties:
-
data
DataFrame - A pandas DataFrame of all candles in the object.
Notes:
The candle class can be customized by subclassing the Candle class and passing the subclass as the candle keyword argument. Or defining it on the class body as a class attribute.
__init__
def __init__(*,
data: DataFrame | _Candles | Iterable,
flip=False,
candle_class: Type[_Candle] = None)
A container class of Candle objects in chronological order.
Arguments:
data
DataFrame|Candles|Iterable - A pandas dataframe, a Candles object or any suitable iterable
Arguments:
flip
bool - Reverse the chronological order of the candles to the oldest first. Defaults to False.candle_class
- A subclass of Candle to use as the candle class. Defaults to Candle.
ta
@property
def ta()
Access to the pandas_ta library for performing technical analysis on the underlying data attribute.
Returns:
pandas_ta
- The pandas_ta library
ta_lib
@property
def ta_lib()
Access to the ta library for performing technical analysis. Not dependent on the underlying data attribute.
Returns:
ta
- The ta library
data
@property
def data() -> DataFrame
The original data passed to the class as a pandas DataFrame
rename
def rename(inplace=True, **kwargs) -> _Candles | None
Rename columns of the candles class.
Arguments:
inplace
bool - Rename the columns inplace or return a new instance of the class with the renamed columns**kwargs
- The new names of the columns
Returns:
Candles
- A new instance of the class with the renamed columns if inplace is False.None
- If inplace is True
aiomql.core.base
Base Objects
class Base()
A base class for all data model classes in the aiomql package. This class provides a set of common methods and attributes for all data model classes. For the data model classes attributes are annotated on the class body and are set as object attributes when the class is instantiated.
Arguments:
-
**kwargs
- Object attributes and values as keyword arguments. Only added if they are annotated on the class body.Class Attributes:
-
mt5
MetaTrader - An instance of the MetaTrader class -
config
Config - An instance of the Config class -
Meta
Type[Meta] - The Meta class for configuration of the data model class
set_attributes
def set_attributes(**kwargs)
Set keyword arguments as object attributes
Arguments:
**kwargs
- Object attributes and values as keyword arguments
Raises:
AttributeError
- When assigning an attribute that does not belong to the class or any parent class
Notes:
Only sets attributes that have been annotated on the class body.
annotations
@property
@cache
def annotations() -> dict
Class annotations from all ancestor classes and the current class.
Returns:
dict
- A dictionary of class annotations
get_dict
def get_dict(exclude: set = None, include: set = None) -> dict
Returns class attributes as a dict, with the ability to filter
Arguments:
exclude
- A set of attributes to be excludedinclude
- Specific attributes to be returned
Returns:
dict
- A dictionary of specified class attributes
Notes:
You can only set either of include or exclude. If you set both, include will take precedence
class_vars
@property
@cache
def class_vars()
Annotated class attributes
Returns:
dict
- A dictionary of available class attributes in all ancestor classes and the current class.
dict
@property
def dict() -> dict
All instance and class attributes as a dictionary, except those excluded in the Meta class.
Returns:
dict
- A dictionary of instance and class attributes
Meta Objects
class Meta()
A class for defining class attributes to be excluded or included in the dict property
Attributes:
exclude
set - A set of attributes to be excludedinclude
set - Specific attributes to be returned. Include supercedes exclude.
filter
@classmethod
@property
def filter(cls) -> set
Combine the exclude and include attributes to return a set of attributes to be excluded.
Returns:
set
- A set of attributes to be excluded
aiomql.core.config
Config Objects
class Config()
A class for handling configuration settings for the aiomql package.
Arguments:
**kwargs
- Configuration settings as keyword arguments. Variables set this way supersede those set in the config file.
Attributes:
record_trades
bool - Whether to keep record of trades or not.filename
str - Name of the config filerecords_dir
str - Path to the directory where trade records are savedwin_percentage
float - Percentage of achieved target profit in a trade to be considered a winlogin
int - Trading account numberpassword
str - Trading account passwordserver
str - Broker serverpath
str - Path to terminal filetimeout
int - Timeout for terminal connection
Notes:
By default, the config class looks for a file named aiomql.json. You can change this by passing the filename keyword argument to the constructor. By passing reload=True to the load_config method, you can reload and search again for the config file.
account_info
def account_info() -> dict['login', 'password', 'server']
Returns Account login details as found in the config object if available
Returns:
dict
- A dictionary of login details
aiomql.core.constants
TradeAction Objects
class TradeAction(Repr, IntEnum)
TRADE_REQUEST_ACTION Enum.
Attributes:
DEAL
int - Delete the pending order placed previously Place a trade order for an immediate execution with the specified parameters (market order).PENDING
int - Delete the pending order placed previouslySLTP
int - Modify Stop Loss and Take Profit values of an opened positionMODIFY
int - Modify the parameters of the order placed previouslyREMOVE
int - Delete the pending order placed previouslyCLOSE_BY
int - Close a position by an opposite one
OrderFilling Objects
class OrderFilling(Repr, IntEnum)
ORDER_TYPE_FILLING Enum.
Attributes:
-
FOK
int - This execution policy means that an order can be executed only in the specified volume. If the necessary amount of a financial instrument is currently unavailable in the market, the order will not be executed. The desired volume can be made up of several available offers. -
IOC
int - An agreement to execute a deal at the maximum volume available in the market within the volume specified in the order. If the request cannot be filled completely, an order with the available volume will be executed, and the remaining volume will be canceled. -
RETURN
int - This policy is used only for market (ORDER_TYPE_BUY and ORDER_TYPE_SELL), limit and stop limit orders (ORDER_TYPE_BUY_LIMIT, ORDER_TYPE_SELL_LIMIT,ORDER_TYPE_BUY_STOP_LIMIT and ORDER_TYPE_SELL_STOP_LIMIT) and only for the symbols with Market or Exchange execution modes. If filled partially, a market or limit order with the remaining volume is not canceled, and is processed further. During activation of the ORDER_TYPE_BUY_STOP_LIMIT and ORDER_TYPE_SELL_STOP_LIMIT orders, an appropriate limit order ORDER_TYPE_BUY_LIMIT/ORDER_TYPE_SELL_LIMIT with the ORDER_FILLING_RETURN type is created.
OrderTime Objects
class OrderTime(Repr, IntEnum)
ORDER_TIME Enum.
Attributes:
GTC
int - Good till cancel orderDAY
int - Good till current trade day orderSPECIFIED
int - The order is active until the specified dateSPECIFIED_DAY
int - The order is active until 23:59:59 of the specified day. If this time appears to be out of a trading session, the expiration is processed at the nearest trading time.
OrderType Objects
class OrderType(Repr, IntEnum)
ORDER_TYPE Enum.
Attributes:
-
BUY
int - Market buy order -
SELL
int - Market sell order -
BUY_LIMIT
int - Buy Limit pending order -
SELL_LIMIT
int - Sell Limit pending order -
BUY_STOP
int - Buy Stop pending order -
SELL_STOP
int - Sell Stop pending order -
BUY_STOP_LIMIT
int - Upon reaching the order price, Buy Limit pending order is placed at StopLimit price -
SELL_STOP_LIMIT
int - Upon reaching the order price, Sell Limit pending order is placed at StopLimit price -
CLOSE_BY
int - Order for closing a position by an opposite oneProperties:
-
opposite
int - Gets the opposite of an order type
opposite
@property
def opposite()
Gets the opposite of an order type for closing an open position
Returns:
int
- integer value of opposite order type
BookType Objects
class BookType(Repr, IntEnum)
BOOK_TYPE Enum.
Attributes:
SELL
int - Sell order (Offer)BUY
int - Buy order (Bid)SELL_MARKET
int - Sell order by MarketBUY_MARKET
int - Buy order by Market
TimeFrame Objects
class TimeFrame(Repr, IntEnum)
TIMEFRAME Enum.
Attributes:
-
M1
int - One Minute -
M2
int - Two Minutes -
M3
int - Three Minutes -
M4
int - Four Minutes -
M5
int - Five Minutes -
M6
int - Six Minutes -
M10
int - Ten Minutes -
M15
int - Fifteen Minutes -
M20
int - Twenty Minutes -
M30
int - Thirty Minutes -
H1
int - One Hour -
H2
int - Two Hours -
H3
int - Three Hours -
H4
int - Four Hours -
H6
int - Six Hours -
H8
int - Eight Hours -
D1
int - One Day -
W1
int - One Week -
MN1
int - One MonthProperties:
-
time
- return the value of the timeframe object in seconds. Used as a property
Methods:
get
- get a timeframe object from a time value in seconds
time
@property
def time()
The number of seconds in a TIMEFRAME
Returns:
int
- The number of seconds in a TIMEFRAME
Examples:
t = TimeFrame.H1 print(t.time) 3600
CopyTicks Objects
class CopyTicks(Repr, IntEnum)
COPY_TICKS Enum. This defines the types of ticks that can be requested using the copy_ticks_from() and copy_ticks_range() functions.
Attributes:
ALL
int - All ticksINFO
int - Ticks containing Bid and/or Ask price changesTRADE
int - Ticks containing Last and/or Volume price changes
PositionType Objects
class PositionType(Repr, IntEnum)
POSITION_TYPE Enum. Direction of an open position (buy or sell)
Attributes:
BUY
int - BuySELL
int - Sell
PositionReason Objects
class PositionReason(Repr, IntEnum)
POSITION_REASON Enum. The reason for opening a position is contained in the POSITION_REASON Enum
Attributes:
CLIENT
int - The position was opened as a result of activation of an order placed from a desktop terminalMOBILE
int - The position was opened as a result of activation of an order placed from a mobile applicationWEB
int - The position was opened as a result of activation of an order placed from the web platformEXPERT
int - The position was opened as a result of activation of an order placed from an MQL5 program, i.e. an Expert Advisor or a script
DealType Objects
class DealType(Repr, IntEnum)
DEAL_TYPE enum. Each deal is characterized by a type, allowed values are enumerated in this enum
Attributes:
-
BUY
int - Buy -
SELL
int - Sell -
BALANCE
int - Balance -
CREDIT
int - Credit -
CHARGE
int - Additional Charge -
CORRECTION
int - Correction -
BONUS
int - Bonus -
COMMISSION
int - Additional Commission -
COMMISSION_DAILY
int - Daily Commission -
COMMISSION_MONTHLY
int - Monthly Commission -
COMMISSION_AGENT_DAILY
int - Daily Agent Commission -
COMMISSION_AGENT_MONTHLY
int - Monthly Agent Commission -
INTEREST
int - Interest Rate -
DEAL_DIVIDEND
int - Dividend Operations -
DEAL_DIVIDEND_FRANKED
int - Franked (non-taxable) dividend operations -
DEAL_TAX
int - Tax Charges -
BUY_CANCELED
int - Canceled buy deal. There can be a situation when a previously executed buy deal is canceled. In this case, the type of the previously executed deal (DEAL_TYPE_BUY) is changed to DEAL_TYPE_BUY_CANCELED, and its profit/loss is zeroized. Previously obtained profit/loss is charged/withdrawn using a separated balance operation -
SELL_CANCELED
int - Canceled sell deal. There can be a situation when a previously executed sell deal is canceled. In this case, the type of the previously executed deal (DEAL_TYPE_SELL) is changed to DEAL_TYPE_SELL_CANCELED, and its profit/loss is zeroized. Previously obtained profit/loss is charged/withdrawn using a separated balance operation.
DealEntry Objects
class DealEntry(Repr, IntEnum)
DEAL_ENTRY Enum. Deals differ not only in their types set in DEAL_TYPE enum, but also in the way they change positions. This can be a simple position opening, or accumulation of a previously opened position (market entering), position closing by an opposite deal of a corresponding volume (market exiting), or position reversing, if the opposite-direction deal covers the volume of the previously opened position.
Attributes:
IN
int - Entry InOUT
int - Entry OutINOUT
int - ReverseOUT_BY
int - Close a position by an opposite one
DealReason Objects
class DealReason(Repr, IntEnum)
DEAL_REASON Enum. The reason for deal execution is contained in the DEAL_REASON property. A deal can be executed as a result of triggering of an order placed from a mobile application or an MQL5 program, as well as as a result of the StopOut event, variation margin calculation, etc.
Attributes:
CLIENT
int - The deal was executed as a result of activation of an order placed from a desktop terminalMOBILE
int - The deal was executed as a result of activation of an order placed from a desktop terminalWEB
int - The deal was executed as a result of activation of an order placed from the web platformEXPERT
int - The deal was executed as a result of activation of an order placed from an MQL5 program, i.e. an Expert Advisor or a scriptSL
int - The deal was executed as a result of Stop Loss activationTP
int - The deal was executed as a result of Take Profit activationSO
int - The deal was executed as a result of the Stop Out eventROLLOVER
int - The deal was executed due to a rolloverVMARGIN
int - The deal was executed after charging the variation marginSPLIT
int - The deal was executed after the split (price reduction) of an instrument, which had an open position during split announcement
OrderReason Objects
class OrderReason(Repr, IntEnum)
ORDER_REASON Enum.
Attributes:
CLIENT
int - The order was placed from a desktop terminalMOBILE
int - The order was placed from a mobile applicationWEB
int - The order was placed from a web platformEXPERT
int - The order was placed from an MQL5-program, i.e. by an Expert Advisor or a scriptSL
int - The order was placed as a result of Stop Loss activationTP
int - The order was placed as a result of Take Profit activationSO
int - The order was placed as a result of the Stop Out event
SymbolChartMode Objects
class SymbolChartMode(Repr, IntEnum)
SYMBOL_CHART_MODE Enum. A symbol price chart can be based on Bid or Last prices. The price selected for symbol charts also affects the generation and display of bars in the terminal. Possible values of the SYMBOL_CHART_MODE property are described in this enum
Attributes:
BID
int - Bars are based on Bid pricesLAST
int - Bars are based on last prices
SymbolCalcMode Objects
class SymbolCalcMode(Repr, IntEnum)
SYMBOL_CALC_MODE Enum. The SYMBOL_CALC_MODE enumeration is used for obtaining information about how the margin requirements for a symbol are calculated.
Attributes:
-
FOREX
int - Forex mode - calculation of profit and margin for Forex -
FOREX_NO_LEVERAGE
int - Forex No Leverage mode � calculation of profit and margin for Forex symbols without taking into account the leverage -
FUTURES
int - Futures mode - calculation of margin and profit for futures -
CFD
int - CFD mode - calculation of margin and profit for CFD -
CFDINDEX
int - CFD index mode - calculation of margin and profit for CFD by indexes -
CFDLEVERAGE
int - CFD Leverage mode - calculation of margin and profit for CFD at leverage trading -
EXCH_STOCKS
int - Calculation of margin and profit for trading securities on a stock exchange -
EXCH_FUTURES
int - Calculation of margin and profit for trading futures contracts on a stock exchange -
EXCH_OPTIONS
int - value is 34 -
EXCH_OPTIONS_MARGIN
int - value is 36 -
EXCH_BONDS
int - Exchange Bonds mode � calculation of margin and profit for trading bonds on a stock exchange -
STOCKS_MOEX
int - Exchange MOEX Stocks mode �calculation of margin and profit for trading securities on MOEX -
EXCH_BONDS_MOEX
int - Exchange MOEX Bonds mode � calculation of margin and profit for trading bonds on MOEX -
SERV_COLLATERAL
int - Collateral mode - a symbol is used as a non-tradable asset on a trading account. The market value of an open position is calculated based on the volume, current market price, contract size and liquidity ratio. The value is included into Assets, which are added to Equity. Open positions of such symbols increase the Free Margin amount and are used as additional margin (collateral) for open positions
SymbolTradeMode Objects
class SymbolTradeMode(Repr, IntEnum)
SYMBOL_TRADE_MODE Enum. There are several symbol trading modes. Information about trading modes of a certain symbol is reflected in the values this enumeration
Attributes:
DISABLED
int - Trade is disabled for the symbolLONGONLY
int - Allowed only long positionsSHORTONLY
int - Allowed only short positionsCLOSEONLY
int - Allowed only position close operationsFULL
int - No trade restrictions
SymbolTradeExecution Objects
class SymbolTradeExecution(Repr, IntEnum)
SYMBOL_TRADE_EXECUTION Enum. The modes, or execution policies, define the rules for cases when the price has changed or the requested volume cannot be completely fulfilled at the moment.
Attributes:
-
REQUEST
int - Executing a market order at the price previously received from the broker. Prices for a certain market order are requested from the broker before the order is sent. Upon receiving the prices, order execution at the given price can be either confirmed or rejected. -
INSTANT
int - Executing a market order at the specified price immediately. When sending a trade request to be executed, the platform automatically adds the current prices to the order.- If the broker accepts the price, the order is executed.
- If the broker does not accept the requested price, a "Requote" is sent � the broker returns prices, at which this order can be executed.
-
MARKET
int - A broker makes a decision about the order execution price without any additional discussion with the trader. Sending the order in such a mode means advance consent to its execution at this price. -
EXCHANGE
int - Trade operations are executed at the prices of the current market offers.
SymbolSwapMode Objects
class SymbolSwapMode(Repr, IntEnum)
SYMBOL_SWAP_MODE Enum. Methods of swap calculation at position transfer are specified in enumeration ENUM_SYMBOL_SWAP_MODE. The method of swap calculation determines the units of measure of the SYMBOL_SWAP_LONG and SYMBOL_SWAP_SHORT parameters. For example, if swaps are charged in the client deposit currency, then the values of those parameters are specified as an amount of money in the client deposit currency.
Attributes:
-
DISABLED
int - Swaps disabled (no swaps) -
POINTS
int - Swaps are charged in points -
CURRENCY_SYMBOL
int - Swaps are charged in money in base currency of the symbol -
CURRENCY_MARGIN
int - Swaps are charged in money in margin currency of the symbol -
CURRENCY_DEPOSIT
int - Swaps are charged in money, in client deposit currency -
INTEREST_CURRENT
int - Swaps are charged as the specified annual interest from the instrument price at calculation of swap (standard bank year is 360 days) -
INTEREST_OPEN
int - Swaps are charged as the specified annual interest from the open price of position (standard bank year is 360 days) -
REOPEN_CURRENT
int - Swaps are charged by reopening positions. At the end of a trading day the position is closed. Next day it is reopened by the close price +/- specified number of points (parameters SYMBOL_SWAP_LONG and SYMBOL_SWAP_SHORT) -
REOPEN_BID
int - Swaps are charged by reopening positions. At the end of a trading day the position is closed. Next day it is reopened by the current Bid price +/- specified number of points (parameters SYMBOL_SWAP_LONG and SYMBOL_SWAP_SHORT)
DayOfWeek Objects
class DayOfWeek(Repr, IntEnum)
DAY_OF_WEEK Enum.
Attributes:
SUNDAY
int - SundayMONDAY
int - MondayTUESDAY
int - TuesdayWEDNESDAY
int - WednesdayTHURSDAY
int - ThursdayFRIDAY
int - FridaySATURDAY
int - Saturday
SymbolOrderGTCMode Objects
class SymbolOrderGTCMode(Repr, IntEnum)
SYMBOL_ORDER_GTC_MODE Enum. If the SYMBOL_EXPIRATION_MODE property is set to SYMBOL_EXPIRATION_GTC (good till canceled), the expiration of pending orders, as well as of Stop Loss/Take Profit orders should be additionally set using the ENUM_SYMBOL_ORDER_GTC_MODE enumeration.
Attributes:
-
GTC
int - Pending orders and Stop Loss/Take Profit levels are valid for an unlimited period until theirConstants, Enumerations and explicit cancellation -
DAILY
int - Orders are valid during one trading day. At the end of the day, all Stop Loss and Take Profit levels, as well as pending orders are deleted. -
DAILY_NO_STOPS
int - When a trade day changes, only pending orders are deleted, while Stop Loss and Take Profit levels are preserved
SymbolOptionRight Objects
class SymbolOptionRight(Repr, IntEnum)
SYMBOL_OPTION_RIGHT Enum. An option is a contract, which gives the right, but not the obligation, to buy or sell an underlying asset (goods, stocks, futures, etc.) at a specified price on or before a specific date. The following enumerations describe option properties, including the option type and the right arising from it.
Attributes:
CALL
int - A call option gives you the right to buy an asset at a specified price.PUT
int - A put option gives you the right to sell an asset at a specified price.
SymbolOptionMode Objects
class SymbolOptionMode(Repr, IntEnum)
SYMBOL_OPTION_MODE Enum.
Attributes:
EUROPEAN
int - European option may only be exercised on a specified date (expiration, execution date, delivery date)AMERICAN
int - American option may be exercised on any trading day or before expiry. The period within which a buyer can exercise the option is specified for it.
AccountTradeMode Objects
class AccountTradeMode(Repr, IntEnum)
ACCOUNT_TRADE_MODE Enum. There are several types of accounts that can be opened on a trade server. The type of account on which an MQL5 program is running can be found out using the ENUM_ACCOUNT_TRADE_MODE enumeration.
Attributes:
DEMO
- Demo accountCONTEST
- Contest accountREAL
- Real Account
TickFlag Objects
class TickFlag(Repr, IntFlag)
TICK_FLAG Enum. TICK_FLAG defines possible flags for ticks. These flags are used to describe ticks obtained by the copy_ticks_from() and copy_ticks_range() functions.
Attributes:
BID
int - Bid price changedASK
int - Ask price changedLAST
int - Last price changedVOLUME
int - Volume changedBUY
int - last Buy price changedSELL
int - last Sell price changed
TradeRetcode Objects
class TradeRetcode(Repr, IntEnum)
TRADE_RETCODE Enum. Return codes for order send/check operations
Attributes:
-
REQUOTE
int - Requote -
REJECT
int - Request rejected -
CANCEL
int - Request canceled by trader -
PLACED
int - Order placed -
DONE
int - Request completed -
DONE_PARTIAL
int - Only part of the request was completed -
ERROR
int - Request processing error -
TIMEOUT
int - Request canceled by timeout -
INVALID
int - Invalid request -
INVALID_VOLUME
int - Invalid volume in the request -
INVALID_PRICE
int - Invalid price in the request -
INVALID_STOPS
int - Invalid stops in the request -
TRADE_DISABLED
int - Trade is disabled -
MARKET_CLOSED
int - Market is closed -
NO_MONEY
int - There is not enough money to complete the request -
PRICE_CHANGED
int - Prices changed -
PRICE_OFF
int - There are no quotes to process the request -
INVALID_EXPIRATION
int - Invalid order expiration date in the request -
ORDER_CHANGED
int - Order state changed -
TOO_MANY_REQUESTS
int - Too frequent requests -
NO_CHANGES
int - No changes in request -
SERVER_DISABLES_AT
int - Autotrading disabled by server -
CLIENT_DISABLES_AT
int - Autotrading disabled by client terminal -
LOCKED
int - Request locked for processing -
FROZEN
int - Order or position frozen -
INVALID_FILL
int - Invalid order filling type -
CONNECTION
int - No connection with the trade server -
ONLY_REAL
int - Operation is allowed only for live accounts -
LIMIT_ORDERS
int - The number of pending orders has reached the limit -
LIMIT_VOLUME
int - The volume of orders and positions for the symbol has reached the limit -
INVALID_ORDER
int - Incorrect or prohibited order type -
POSITION_CLOSED
int - Position with the specified POSITION_IDENTIFIER has already been closed -
INVALID_CLOSE_VOLUME
int - A close volume exceeds the current position volume -
CLOSE_ORDER_EXIST
int - A close order already exists for a specified position. This may happen when working in the hedging system: � when attempting to close a position with an opposite one, while close orders for the position already exist � when attempting to fully or partially close a position if the total volume of the already present close orders and the newly placed one exceeds the current position volume -
LIMIT_POSITIONS
int - The number of open positions simultaneously present on an account can be limited by the server settings.After a limit is reached, the server returns the TRADE_RETCODE_LIMIT_POSITIONS error when attempting to place an order. The limitation operates differently depending on the position accounting type: � Netting � number of open positions is considered. When a limit is reached, the platform does not let placing new orders whose execution may increase the number of open positions. In fact, the platform allows placing orders only for the symbols that already have open positions. The current pending orders are not considered since their execution may lead to changes in the current positions but it cannot increase their number.� Hedging � pending orders are considered together with open positions, since a pending order activation always leads to opening a new position. When a limit is reached, the platform does not allow placing both new market orders for opening positions and pending orders.
-
REJECT_CANCEL
int - The pending order activation request is rejected, the order is canceled. -
LONG_ONLY
int - The request is rejected, because the "Only long positions are allowed" rule is set for the symbol (POSITION_TYPE_BUY) -
SHORT_ONLY
int - The request is rejected, because the "Only short positions are allowed" rule is set for the symbol (POSITION_TYPE_SELL) -
CLOSE_ONLY
int - The request is rejected, because the "Only position closing is allowed" rule is set for the symbol -
FIFO_CLOSE
int - The request is rejected, because "Position closing is allowed only by FIFO rule" flag is set for the trading account (ACCOUNT_FIFO_CLOSE=true)
AccountStopOutMode Objects
class AccountStopOutMode(Repr, IntEnum)
ACCOUNT_STOPOUT_MODE Enum.
Attributes:
PERCENT
int - Account stop out mode in percentsMONEY
int - Account stop out mode in money
AccountMarginMode Objects
class AccountMarginMode(Repr, IntEnum)
ACCOUNT_MARGIN_MODE Enum.
Attributes:
-
RETAIL_NETTING
int - Used for the OTC markets to interpret positions in the "netting" mode (only one position can exist for one symbol). The margin is calculated based on the symbol type (SYMBOL_TRADE_CALC_MODE). -
EXCHANGE
int - Used for the exchange markets. Margin is calculated based on the discounts specified in symbol settings. Discounts are set by the broker, but not less than the values set by the exchange. -
HEDGING
int - Used for the exchange markets where individual positions are possible (hedging, multiple positions can exist for one symbol). The margin is calculated based on the symbol type (SYMBOL_TRADE_CALC_MODE) taking into account the hedged margin (SYMBOL_MARGIN_HEDGED).
aiomql.core.errors
Error Objects
class Error()
Error class for handling errors from MetaTrader 5.
aiomql.core.exceptions
Exceptions for the aiomql package.
LoginError Objects
class LoginError(Exception)
Raised when an error occurs when logging in.
VolumeError Objects
class VolumeError(Exception)
Raised when a volume is not valid or out of range for a symbol.
SymbolError Objects
class SymbolError(Exception)
Raised when a symbol is not provided where required or not available in the Market Watch.
OrderError Objects
class OrderError(Exception)
Raised when an error occurs when working with the order class.
aiomql.core.meta_trader
MetaTrader Objects
class MetaTrader(metaclass=BaseMeta)
__aenter__
async def __aenter__() -> 'MetaTrader'
Async context manager entry point. Initializes the connection to the MetaTrader terminal.
Returns:
MetaTrader
- An instance of the MetaTrader class.
__aexit__
async def __aexit__(exc_type, exc_val, exc_tb)
Async context manager exit point. Closes the connection to the MetaTrader terminal.
login
async def login(login: int,
password: str,
server: str,
timeout: int = 60000) -> bool
Connects to the MetaTrader terminal using the specified login, password and server.
Arguments:
login
int - The trading account number.password
str - The trading account password.server
str - The trading server name.timeout
int - The timeout for the connection in seconds.
Returns:
bool
- True if successful, False otherwise.
initialize
async def initialize(path: str = "",
login: int = 0,
password: str = "",
server: str = "",
timeout: int | None = None,
portable=False) -> bool
Initializes the connection to the MetaTrader terminal. All parameters are optional.
Arguments:
path
str - The path to the MetaTrader terminal executable.login
int - The trading account number.password
str - The trading account password.server
str - The trading server name.timeout
int - The timeout for the connection in seconds.portable
bool - If True, the terminal will be launched in portable mode.
Returns:
bool
- True if successful, False otherwise.
shutdown
async def shutdown() -> None
Closes the connection to the MetaTrader terminal.
Returns:
None
- None
version
async def version() -> tuple[int, int, str] | None
account_info
async def account_info() -> AccountInfo | None
orders_get
async def orders_get(group: str = "",
ticket: int = 0,
symbol: str = "") -> tuple[TradeOrder] | None
Get active orders with the ability to filter by symbol or ticket. There are three call options. Call without parameters. Return active orders on all symbols
Arguments:
-
symbol
str - Symbol name. Optional named parameter. If a symbol is specified, the ticket parameter is ignored. -
group
str - The filter for arranging a group of necessary symbols. Optional named parameter. If the group is specified, the function returns only active orders meeting a specified criteria for a symbol name. -
ticket
int - Order ticket (ORDER_TICKET). Optional named parameter.
Returns:
list[TradeOrder]
- A list of active trade orders as TradeOrder objects
aiomql.core.models
AccountInfo Objects
class AccountInfo(Base)
Account Information Class.
Attributes:
login
- intpassword
- strserver
- strtrade_mode
- AccountTradeModebalance
- floatleverage
- floatprofit
- floatpoint
- floatamount
- float = 0equity
- floatcredit
- floatmargin
- floatmargin_level
- floatmargin_free
- floatmargin_mode
- AccountMarginModemargin_so_mode
- AccountStopoutModemargin_so_call
- floatmargin_so_so
- floatmargin_initial
- floatmargin_maintenance
- floatfifo_close
- boollimit_orders
- floatcurrency
- str = "USD"trade_allowed
- bool = Truetrade_expert
- bool = Truecurrency_digits
- intassets
- floatliabilities
- floatcommission_blocked
- floatname
- strcompany
- str
TerminalInfo Objects
class TerminalInfo(Base)
Terminal information class. Holds information about the terminal.
Attributes:
community_account
- boolcommunity_connection
- boolconnected
- booldlls_allowed
- booltrade_allowed
- booltradeapi_disabled
- boolemail_enabled
- boolftp_enabled
- boolnotifications_enabled
- boolmqid
- boolbuild
- intmaxbars
- intcodepage
- intping_last
- intcommunity_balance
- floatretransmission
- floatcompany
- strname
- strlanguage
- strpath
- strdata_path
- strcommondata_path
- str
SymbolInfo Objects
class SymbolInfo(Base)
Symbol Information Class. Symbols are financial instruments available for trading in the MetaTrader 5 terminal.
Attributes:
name
- strcustom
- boolchart_mode
- SymbolChartModeselect
- boolvisible
- boolsession_deals
- intsession_buy_orders
- intsession_sell_orders
- intvolume
- floatvolumehigh
- floatvolumelow
- floattime
- intdigits
- intspread
- floatspread_float
- boolticks_bookdepth
- inttrade_calc_mode
- SymbolCalcModetrade_mode
- SymbolTradeModestart_time
- intexpiration_time
- inttrade_stops_level
- inttrade_freeze_level
- inttrade_exemode
- SymbolTradeExecutionswap_mode
- SymbolSwapModeswap_rollover3days
- DayOfWeekmargin_hedged_use_leg
- boolexpiration_mode
- intfilling_mode
- intorder_mode
- intorder_gtc_mode
- SymbolOrderGTCModeoption_mode
- SymbolOptionModeoption_right
- SymbolOptionRightbid
- floatbidhigh
- floatbidlow
- floatask
- floataskhigh
- floatasklow
- floatlast
- floatlasthigh
- floatlastlow
- floatvolume_real
- floatvolumehigh_real
- floatvolumelow_real
- floatoption_strike
- floatpoint
- floattrade_tick_value
- floattrade_tick_value_profit
- floattrade_tick_value_loss
- floattrade_tick_size
- floattrade_contract_size
- floattrade_accrued_interest
- floattrade_face_value
- floattrade_liquidity_rate
- floatvolume_min
- floatvolume_max
- floatvolume_step
- floatvolume_limit
- floatswap_long
- floatswap_short
- floatmargin_initial
- floatmargin_maintenance
- floatsession_volume
- floatsession_turnover
- floatsession_interest
- floatsession_buy_orders_volume
- floatsession_sell_orders_volume
- floatsession_open
- floatsession_close
- floatsession_aw
- floatsession_price_settlement
- floatsession_price_limit_min
- floatsession_price_limit_max
- floatmargin_hedged
- floatprice_change
- floatprice_volatility
- floatprice_theoretical
- floatprice_greeks_delta
- floatprice_greeks_theta
- floatprice_greeks_gamma
- floatprice_greeks_vega
- floatprice_greeks_rho
- floatprice_greeks_omega
- floatprice_sensitivity
- floatbasis
- strcategory
- strcurrency_base
- strcurrency_profit
- strcurrency_margin
- Anybank
- strdescription
- strexchange
- strformula
- Anyisin
- Anyname
- strpage
- strpath
- str
BookInfo Objects
class BookInfo(Base)
Book Information Class.
Attributes:
type
- BookTypeprice
- floatvolume
- floatvolume_dbl
- float
TradeOrder Objects
class TradeOrder(Base)
Trade Order Class.
Attributes:
ticket
- inttime_setup
- inttime_setup_msc
- inttime_expiration
- inttime_done
- inttime_done_msc
- inttype
- OrderTypetype_time
- OrderTimetype_filling
- OrderFillingstate
- intmagic
- intposition_id
- intposition_by_id
- intreason
- OrderReasonvolume_current
- floatvolume_initial
- floatprice_open
- floatsl
- floattp
- floatprice_current
- floatprice_stoplimit
- floatsymbol
- strcomment
- strexternal_id
- str
TradeRequest Objects
class TradeRequest(Base)
Trade Request Class.
Attributes:
action
- TradeActiontype
- OrderTypeorder
- intsymbol
- strvolume
- floatsl
- floattp
- floatprice
- floatdeviation
- floatstop_limit
- floattype_time
- OrderTimetype_filling
- OrderFillingexpiration
- intposition
- intposition_by
- intcomment
- strmagic
- intdeviation
- intcomment
- str
OrderCheckResult Objects
class OrderCheckResult(Base)
Order Check Result
Attributes:
retcode
- intbalance
- floatequity
- floatprofit
- floatmargin
- floatmargin_free
- floatmargin_level
- floatcomment
- strrequest
- TradeRequest
OrderSendResult Objects
class OrderSendResult(Base)
Order Send Result
Attributes:
retcode
- intdeal
- intorder
- intvolume
- floatprice
- floatbid
- floatask
- floatcomment
- strrequest
- TradeRequestrequest_id
- intretcode_external
- intprofit
- float
TradePosition Objects
class TradePosition(Base)
Trade Position
Attributes:
ticket
- inttime
- inttime_msc
- inttime_update
- inttime_update_msc
- inttype
- OrderTypemagic
- floatidentifier
- intreason
- PositionReasonvolume
- floatprice_open
- floatsl
- floattp
- floatprice_current
- floatswap
- floatprofit
- floatsymbol
- strcomment
- strexternal_id
- str
TradeDeal Objects
class TradeDeal(Base)
Trade Deal
Attributes:
ticket
- intorder
- inttime
- inttime_msc
- inttype
- DealTypeentry
- DealEntrymagic
- intposition_id
- intreason
- DealReasonvolume
- floatprice
- floatcommission
- floatswap
- floatprofit
- floatfee
- floatsl
- floattp
- floatsymbol
- strcomment
- strexternal_id
- str
aiomql.core
aiomql.executor
Executor Objects
class Executor()
Executor class for running multiple strategies on multiple symbols concurrently.
Attributes:
executor
ThreadPoolExecutor - The executor object.workers
list - List of strategies.
add_workers
def add_workers(strategies: Sequence[type(Strategy)])
Add multiple strategies at once
Arguments:
strategies
Sequence[Strategy] - A sequence of strategies.
remove_workers
def remove_workers(*symbols: Sequence[Symbol])
Removes any worker running on a symbol not successfully initialized.
Arguments:
*symbols
- Successfully initialized symbols.
add_worker
def add_worker(strategy: type(Strategy))
Add a strategy instance to the list of workers
Arguments:
strategy
Strategy - A strategy object
run
@staticmethod
def run(strategy: type(Strategy))
Wraps the coroutine trade method of each strategy with 'asyncio.run'.
Arguments:
strategy
Strategy - A strategy object
execute
async def execute(workers: int = 0)
Run the strategies with a threadpool executor.
Arguments:
workers
- Number of workers to use in executor pool. Defaults to zero which uses all workers.
Notes:
No matter the number specified, the executor will always use a minimum of 5 workers.
aiomql.history
History Objects
class History()
The history class handles completed trade deals and trade orders in the trading history of an account.
Attributes:
deals
list[TradeDeal] - Iterable of trade dealsorders
list[TradeOrder] - Iterable of trade orderstotal_deals
- Total number of dealstotal_orders
int - Total number ordersgroup
str - Filter for selecting history by symbols.ticket
int - Filter for selecting history by ticket numberposition
int - Filter for selecting history deals by positioninitialized
bool - check if initial request has been sent to the terminal to get history.mt5
MetaTrader - MetaTrader instanceconfig
Config - Config instance
__init__
def __init__(*,
date_from: datetime | float = 0,
date_to: datetime | float = 0,
group: str = "",
ticket: int = 0,
position: int = 0)
Arguments:
-
date_from
datetime, float - Date the orders are requested from. Set by the 'datetime' object or as a number of seconds elapsed since 1970.01.01. Defaults to the current time in "utc" -
date_to
datetime, float - Date up to which the orders are requested. Set by the 'datetime' object or as a number of seconds elapsed since 1970.01.01. Defaults to the current time in "utc" -
group
str - Filter for selecting history by symbols. -
ticket
int - Filter for selecting history by ticket number -
position
int - Filter for selecting history deals by position
init
async def init(deals=True, orders=True) -> bool
Get history deals and orders
Arguments:
deals
bool - If true get history deals during initial request to terminalorders
bool - If true get history orders during initial request to terminal
Returns:
bool
- True if all requests were successful else False
get_deals
async def get_deals() -> list[TradeDeal]
Get deals from trading history using the parameters set in the constructor.
Returns:
list[TradeDeal]
- A list of trade deals
deals_total
async def deals_total() -> int
Get total number of deals within the specified period in the constructor.
Returns:
int
- Total number of Deals
get_orders
async def get_orders() -> list[TradeOrder]
Get orders from trading history using the parameters set in the constructor.
Returns:
list[TradeOrder]
- A list of trade orders
orders_total
async def orders_total() -> int
Get total number of orders within the specified period in the constructor.
Returns:
int
- Total number of orders
aiomql.lib.strategies.finger_trap
Entry Objects
@dataclass
class Entry()
Entry class for FingerTrap strategy.Will be used to store entry conditions and other entry related data.
Attributes:
bearish
bool - True if the market is bearishbullish
bool - True if the market is bullishranging
bool - True if the market is rangingsnooze
float - Time to wait before checking for entry conditionstrend
str - The current trend of the marketlast_candle
Candle - The last candle of the marketnew
bool - True if the last candle is neworder_type
OrderType - The type of order to placepips
int - The number of pips to place the order from the current price
aiomql.lib.strategies
aiomql.lib.symbols.forex_symbol
ForexSymbol Objects
class ForexSymbol(Symbol)
Subclass of Symbol for Forex Symbols. Handles the conversion of currency and the computation of stop loss, take profit and volume.
pip
@property
def pip()
Returns the pip value of the symbol. This is ten times the point value for forex symbols.
Returns:
float
- The pip value of the symbol.
compute_volume
async def compute_volume(*, amount: float, pips: float) -> float
Compute volume given an amount to risk and target pips. Round the computed volume to the nearest step.
Arguments:
amount
float - Amount to risk. Given in terms of the account currency.pips
float - Target pips.
Returns:
float
- volume
Raises:
VolumeError
- If the computed volume is less than the minimum volume or greater than the maximum volume.
aiomql.lib.symbols
aiomql.lib.traders.simple_deal_trader
DealTrader Objects
class DealTrader(Trader)
A base class for placing trades based on the number of pips to target
create_order
async def create_order(*, order_type: OrderType, pips: float)
Using the number of target pips it determines the lot size, stop loss and take profit for the order, and updates the order object with the values.
Arguments:
order_type
OrderType - Type of orderpips
float - Target pips
aiomql.lib.traders
aiomql.lib
aiomql.order
Order Class
Order Objects
class Order(TradeRequest)
Trade order related functions and properties. Subclass of TradeRequest.
__init__
def __init__(**kwargs)
Initialize the order object with keyword arguments, symbol must be provided. Provide default values for action, type_time and type_filling if not provided.
Arguments:
-
**kwargs
- Keyword arguments must match the attributes of TradeRequest as well as the attributes of Order class as specified in the annotations in the class definition.Default Values:
-
action
TradeAction.DEAL - Trade action -
type_time
OrderTime.DAY - Order time -
type_filling
OrderFilling.FOK - Order filling
Raises:
SymbolError
- If symbol is not provided
orders_total
async def orders_total()
Get the number of active orders.
Returns:
(int)
- total number of active orders
orders
async def orders() -> tuple[TradeOrder]
Get the list of active orders for the current symbol.
Returns:
tuple[TradeOrder]
- A Tuple of active trade orders as TradeOrder objects
check
async def check() -> OrderCheckResult
Check funds sufficiency for performing a required trading operation and the possibility to execute it at
Returns:
OrderCheckResult
- An OrderCheckResult object
Raises:
OrderError
- If not successful
send
async def send() -> OrderSendResult
Send a request to perform a trading operation from the terminal to the trade server.
Returns:
OrderSendResult
- An OrderSendResult object
Raises:
OrderError
- If not successful
calc_margin
async def calc_margin() -> float
Return the required margin in the account currency to perform a specified trading operation.
Returns:
float
- Returns float value if successful
Raises:
OrderError
- If not successful
calc_profit
async def calc_profit() -> float
Return profit in the account currency for a specified trading operation.
Returns:
float
- Returns float value if successful
Raises:
OrderError
- If not successful
aiomql.positions
Handle Open positions.
Positions Objects
class Positions()
Get Open Positions.
Attributes:
symbol
str - Financial instrument name.group
str - The filter for arranging a group of necessary symbols. Optional named parameter. If the group is specified, the function returns only positions meeting a specified criteria for a symbol name.ticket
int - Position ticket.mt5
MetaTrader - MetaTrader instance.
__init__
def __init__(*, symbol: str = "", group: str = "", ticket: int = 0)
Get Open Positions.
Arguments:
symbol
str - Financial instrument name.group
str - The filter for arranging a group of necessary symbols. Optional named parameter. If the group is specified, the function returns only positions meeting a specified criteria for a symbol name.ticket
int - Position ticket
positions_total
async def positions_total() -> int
Get the number of open positions.
Returns:
int
- Return total number of open positions
positions_get
async def positions_get()
Get open positions with the ability to filter by symbol or ticket.
Returns:
list[TradePosition]
- A list of open trade positions
close_all
async def close_all() -> int
Close all open positions for the trading account.
Returns:
int
- Return number of positions closed.
aiomql.ram
Risk Assessment and Management
RAM Objects
class RAM()
__init__
def __init__(**kwargs)
Risk Assessment and Management. All provided keyword arguments are set as attributes.
Arguments:
-
kwargs
Dict - Keyword arguments.Defaults:
-
risk_to_reward
float - Risk to reward ratio 1 -
risk
float - Percentage of account balance to risk per trade 0.01 # 1% -
amount
float - Amount to risk per trade in terms of base currency 10 -
pips
float - Target pips 10 -
volume
float - Volume to trade 0.05
get_amount
async def get_amount() -> float
Calculate the amount to risk per trade.
Returns:
float
- Amount to risk per trade
aiomql.records
This module contains the Records class, which is used to read and update trade records from csv files.
Records Objects
class Records()
This utility class read trade records from csv files, and update them based on their closing positions.
Attributes:
config
- Config objectrecords_dir(Path)
- Path to directory containing record of placed trades, If not given takes the default from the config
__init__
def __init__(records_dir: Path = '')
Initialize the Records class.
Arguments:
records_dir
Path - Path to directory containing record of placed trades.
get_records
async def get_records()
Get trade records from records_dir folder
Yields:
files
- Trade record files
read_update
async def read_update(file: Path)
Read and update trade records
Arguments:
file
- Trade record file
update_rows
async def update_rows(rows: list[dict]) -> list[dict]
Update the rows of entered trades in the csv file with the actual profit.
Arguments:
rows
- A list of dictionaries from the dictionary writer object of the csv file.
Returns:
list[dict]
- A list of dictionaries with the actual profit and win status.
update_records
async def update_records()
Update trade records in the records_dir folder.
update_record
async def update_record(file: Path | str)
Update a single trade record file.
aiomql.result
Result Objects
class Result()
A base class for handling trade results and strategy parameters for record keeping and reference purpose. The data property must be implemented in the subclass
Attributes:
config
Config - The configuration objectname
- Any desired name for the result file object
__init__
def __init__(result: OrderSendResult, parameters: dict = None, name: str = '')
Prepare result data
Arguments:
result: parameters: name:
to_csv
async def to_csv()
Record trade results and associated parameters as a csv file
save_csv
async def save_csv()
Save trade results and associated parameters as a csv file in a separate thread
aiomql.strategy
The base class for creating strategies.
Strategy Objects
class Strategy(ABC)
The base class for creating strategies.
Attributes:
-
symbol
Symbol - The Financial Instrument as a Symbol Object -
parameters
Dict - A dictionary of parameters for the strategy.Class Attributes:
-
name
str - A name for the strategy. -
account
Account - Account instance. -
mt5
MetaTrader - MetaTrader instance. -
config
Config - Config instance.
Notes:
Define the name of a strategy as a class attribute. If not provided, the class name will be used as the name.
__init__
def __init__(*, symbol: Symbol, params: dict = None)
Initiate the parameters dict and add name and symbol fields. Use class name as strategy name if name is not provided
Arguments:
symbol
Symbol - The Financial instrumentparams
Dict - Trading strategy parameters
sleep
@staticmethod
async def sleep(secs: float)
Sleep for the needed amount of seconds in between requests to the terminal. computes the accurate amount of time needed to sleep ensuring that the next request is made at the start of a new bar and making cooperative multitasking possible.
Arguments:
secs
float - The time in seconds. Usually the timeframe you are trading on.
trade
@abstractmethod
async def trade()
Place trades using this method. This is the main method of the strategy. It will be called by the strategy runner.
aiomql.symbol
Symbol class for handling a financial instrument.
Symbol Objects
class Symbol(SymbolInfo)
Main class for handling a financial instrument. A subclass of SymbolInfo and Base it has attributes and methods for working with a financial instrument.
Attributes:
tick
Tick - Price tick object for instrumentaccount
- An instance of the current trading account
Notes:
Full properties are on the SymbolInfo Object. Make sure Symbol is always initialized with a name argument
info_tick
async def info_tick(*, name: str = "") -> Tick
Get the current price tick of a financial instrument.
Arguments:
name
- if name is supplied get price tick of that financial instrument
Returns:
Tick
- Return a Tick Object
Raises:
ValueError
- If request was unsuccessful and None was returned
symbol_select
async def symbol_select(*, enable: bool = True) -> bool
Select a symbol in the MarketWatch window or remove a symbol from the window. Update the select property
Arguments:
enable
bool - Switch. Optional unnamed parameter. If 'false', a symbol should be removed from the MarketWatch window.
Returns:
bool
- True if successful, otherwise � False.
info
async def info() -> SymbolInfo
Get data on the specified financial instrument and update the symbol object properties
Returns:
(SymbolInfo)
- SymbolInfo if successful
Raises:
ValueError
- If request was unsuccessful and None was returned
init
async def init() -> bool
Initialized the symbol by pulling properties from the terminal
Returns:
bool
- Returns True if symbol info was successful initialized
book_add
async def book_add() -> bool
Subscribes the MetaTrader 5 terminal to the Market Depth change events for a specified symbol. If the symbol is not in the list of instruments for the market, This method will return False
Returns:
bool
- True if successful, otherwise � False.
book_get
async def book_get() -> tuple[BookInfo]
Returns a tuple of BookInfo featuring Market Depth entries for the specified symbol.
Returns:
tuple[BookInfo]
- Returns the Market Depth contents as a tuples of BookInfo Objects
Raises:
ValueError
- If request was unsuccessful and None was returned
book_release
async def book_release() -> bool
Cancels subscription of the MetaTrader 5 terminal to the Market Depth change events for a specified symbol.
Returns:
bool
- True if successful, otherwise � False.
compute_volume
async def compute_volume(*, amount: float, pips: float) -> float
Computes the volume of a trade based on the amount and the number of pips to target
Arguments:
amount
float - Amount to risk in the tradepips
float - Number of pips to target
Returns:
float
- Returns the volume of the trade
currency_conversion
async def currency_conversion(*, amount: float, base: str,
quote: str) -> float
Convert from one currency to the other.
Arguments:
amount
- amount to convert given in terms of the quote currencybase
- The base currency of the pairquote
- The quote currency of the pair
Returns:
float
- Amount in terms of the base currency or None if it failed to convert
Raises:
ValueError
- If conversion is impossible
copy_rates_from
async def copy_rates_from(*, timeframe: TimeFrame, date_from: datetime | int,
count: int) -> Candles
Get bars from the MetaTrader 5 terminal starting from the specified date.
Arguments:
-
timeframe
TimeFrame - Timeframe the bars are requested for. Set by a value from the TimeFrame enumeration. Required unnamed parameter. -
date_from
datetime | int - Date of opening of the first bar from the requested sample. Set by the 'datetime' object or as a number of seconds elapsed since 1970.01.01. Required unnamed parameter. -
count
int - Number of bars to receive. Required unnamed parameter.
Returns:
Candles
- Returns a Candles object as a collection of rates ordered chronologically
Raises:
ValueError
- If request was unsuccessful and None was returned
copy_rates_from_pos
async def copy_rates_from_pos(*,
timeframe: TimeFrame,
count: int = 500,
start_position: int = 0) -> Candles
Get bars from the MetaTrader 5 terminal starting from the specified index.
Arguments:
-
timeframe
TimeFrame - TimeFrame value from TimeFrame Enum. Required keyword only parameter -
count
int - Number of bars to return. Keyword argument defaults to 500 -
start_position
int - Initial index of the bar the data are requested from. The numbering of bars goes from present to past. Thus, the zero bar means the current one. Keyword argument defaults to 0.
Returns:
Candles
- Returns a Candles object as a collection of rates ordered chronologically.
Raises:
ValueError
- If request was unsuccessful and None was returned
copy_rates_range
async def copy_rates_range(*, timeframe: TimeFrame, date_from: datetime | int,
date_to: datetime | int) -> Candles
Get bars in the specified date range from the MetaTrader 5 terminal.
Arguments:
-
timeframe
TimeFrame - Timeframe for the bars using the TimeFrame enumeration. Required unnamed parameter. -
date_from
datetime | int - Date the bars are requested from. Set by the 'datetime' object or as a number of seconds elapsed since 1970.01.01. Bars with the open time >= date_from are returned. Required unnamed parameter. -
date_to
datetime | int - Date, up to which the bars are requested. Set by the 'datetime' object or as a number of seconds elapsed since 1970.01.01. Bars with the open time <= date_to are returned. Required unnamed parameter.
Returns:
Candles
- Returns a Candles object as a collection of rates ordered chronologically.
Raises:
ValueError
- If request was unsuccessful and None was returned
copy_ticks_from
async def copy_ticks_from(*,
date_from: datetime | int,
count: int = 100,
flags: CopyTicks = CopyTicks.ALL) -> Ticks
Get ticks from the MetaTrader 5 terminal starting from the specified date.
Args: date_from (datetime | int): Date the ticks are requested from. Set by the 'datetime' object or as a number of seconds elapsed since 1970.01.01.
count (int): Number of requested ticks. Defaults to 100
flags (CopyTicks): A flag to define the type of the requested ticks from CopyTicks enum. INFO is the default
Returns:
Candles
- Returns a Candles object as a collection of ticks ordered chronologically.
Raises:
ValueError
- If request was unsuccessful and None was returned
copy_ticks_range
async def copy_ticks_range(*,
date_from: datetime | int,
date_to: datetime | int,
flags: CopyTicks = CopyTicks.ALL) -> Ticks
Get ticks for the specified date range from the MetaTrader 5 terminal.
Arguments:
-
date_from
- Date the bars are requested from. Set by the 'datetime' object or as a number of seconds elapsed since 1970.01.01. Bars with the open time >= date_from are returned. Required unnamed parameter. -
date_to
- Date, up to which the bars are requested. Set by the 'datetime' object or as a number of seconds elapsed since 1970.01.01. Bars with the open time <= date_to are returned. Required unnamed parameter.flags (CopyTicks):
Returns:
Candles
- Returns a Candles object as a collection of ticks ordered chronologically.
Raises:
ValueError
- If request was unsuccessful and None was returned.
aiomql.terminal
Terminal related functions and properties
Terminal Objects
class Terminal(TerminalInfo)
Terminal Class. Get information about the MetaTrader 5 terminal. The class is a subclass of the TerminalInfo class. It inherits all the attributes and methods of the TerminalInfo class and adds some useful methods.
Notes:
Other attributes are defined in the TerminalInfo Class
initialize
async def initialize() -> bool
Establish a connection with the MetaTrader 5 terminal. There are three call options. Call without parameters. The terminal for connection is found automatically. Call specifying the path to the MetaTrader 5 terminal we want to connect to. word path as a keyword argument Call specifying the trading account path and parameters i.e login, password, server, as keyword arguments, path can be omitted.
Returns:
bool
- True if successful else False
version
async def version()
Get the MetaTrader 5 terminal version. This method returns the terminal version, build and release date as a tuple of three values
Returns:
Version
- version of tuple as Version object
Raises:
ValueError
- If the terminal version cannot be obtained
info
async def info()
Get the connected MetaTrader 5 client terminal status and settings. gets terminal info in the form of a named tuple structure (namedtuple). Return None in case of an error. The info on the error can be obtained using last_error().
Returns:
Terminal
- Terminal status and settings as a terminal object.
symbols_total
async def symbols_total() -> int
Get the number of all financial instruments in the MetaTrader 5 terminal.
Returns:
int
- Total number of available symbols
aiomql.ticks
Module for working with price ticks.
Tick Objects
class Tick()
Price Tick of a Financial Instrument.
Attributes:
time
int - Time of the last prices update for the symbolbid
float - Current Bid priceask
float - Current Ask pricelast
float - Price of the last deal (Last)volume
float - Volume for the current Last pricetime_msc
int - Time of the last prices update for the symbol in millisecondsflags
TickFlag - Tick flagsvolume_real
float - Volume for the current Last priceIndex
int - Custom attribute representing the position of the tick in a sequence.
set_attributes
def set_attributes(**kwargs)
Set attributes from keyword arguments
Ticks Objects
class Ticks()
Container data class for price ticks. Arrange in chronological order. Supports iteration, slicing and assignment
Arguments:
data
DataFrame | tuple[tuple] - Dataframe of price ticks or a tuple of tuples
Arguments:
flip
bool - If flip is True reverse data chronological order.
Attributes:
data
- Dataframe Object holding the ticks
__init__
def __init__(*, data: DataFrame | Iterable, flip=False)
Initialize the Ticks class. Creates a DataFrame of price ticks from the data argument.
Arguments:
data
DataFrame | Iterable - Dataframe of price ticks or any iterable object that can be converted to a pandas DataFrameflip
bool - If flip is True reverse data chronological order.
ta
@property
def ta()
Access to the pandas_ta library for performing technical analysis on the underlying data attribute.
Returns:
pandas_ta
- The pandas_ta library
ta_lib
@property
def ta_lib()
Access to the ta library for performing technical analysis. Not dependent on the underlying data attribute.
Returns:
ta
- The ta library
data
@property
def data() -> DataFrame
DataFrame of price ticks arranged in chronological order.
rename
def rename(inplace=True, **kwargs) -> _Ticks | None
Rename columns of the candle class.
Arguments:
inplace
bool - Rename the columns inplace or return a new instance of the class with the renamed columns**kwargs
- The new names of the columns
Returns:
Ticks
- A new instance of the class with the renamed columns if inplace is False.None
- If inplace is True
aiomql.trader
Trader class module. Handles the creation of an order and the placing of trades
Trader Objects
class Trader()
Base class for creating a Trader object. Handles the creation of an order and the placing of trades
Attributes:
-
symbol
Symbol - Financial instrument class Symbol class or any subclass of it. -
ram
RAM - RAM instance -
order
Order - Trade orderClass Attributes:
-
name
str - A name for the strategy. -
account
Account - Account instance. -
mt5
MetaTrader - MetaTrader instance. -
config
Config - Config instance.
__init__
def __init__(*, symbol: Symbol, ram: RAM = None)
Initializes the order object and RAM instance
Arguments:
symbol
Symbol - Financial instrumentram
RAM - Risk Assessment and Management instance
create_order
async def create_order(*, order_type: OrderType, **kwargs)
Complete the order object with the required values. The default trader object uses the values specified in the default RAM instance to determine the take profit, stop loss, volume, and number of pips to target.
Arguments:
order_type
OrderType - Type of orderkwargs
- keyword arguments as required for the specific trader
set_order_limits
async def set_order_limits(pips: float)
Sets the stop loss and take profit for the order. This method uses pips as defined for forex instruments.
Arguments:
pips
- Target pips
place_trade
async def place_trade(order_type: OrderType, params: dict = None, **kwargs)
Places a trade based on the order_type.
Arguments:
order_type
OrderType - Type of orderparams
- parameters to be saved with the tradekwargs
- keyword arguments as required for the specific trader
aiomql.utils
Utility functions for aiomql.
dict_to_string
def dict_to_string(data: dict, multi=False) -> str
Convert a dict to a string. Use for logging.
Arguments:
data
dict - The dict to convert.multi
bool, optional - If True, each key-value pair will be on a new line. Defaults to False.
Returns:
str
- The string representation of the dict.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.