Configuration options

The Config handles the loading of the configuration options. Either via

Dictionary (See simulator_simple_dict.py):

from tradeforce import Tradeforce
CONFIG = {...}
sim_result = Tradeforce(config=CONFIG).run_sim()

or YAML (See simulator_simple_yaml.py):

from tradeforce import Tradeforce
sim_result = Tradeforce(config_file="config.yaml").run_sim()

class tradeforce.config.Config(root, config_input, config_file)

Loads and stores the user config.

It gets passed to all other classes and allows us to access them via self.config.<config_key> Provides default values to fall back on if param is not specified in user config.

Parameters:

• root (Tradeforce) – The main Tradeforce instance. Provides access to logger or any other module.

• config_input (Optional[dict]) – Dictionary containing the configuration.

• config_file (Optional[str]) – Absolute path to the configuration file (yaml).

---

core

working_dir

Path to the working directory.

Default is the directory Tradeforce is executed from.

Type:

str

credentials_path

Absolute path to the credentials file for authentication to the private Bitfinex API (for live trading).

Note

This credentials file is SHA3_256 encrypted by a user defined password. See run_live for more information.

Default: working_dir

Type:

str

---

market_history

Determines how the market data is stored, updated, and retrieved. This includes specifying the entity and file names for data storage and defining the base currency. It also includes options for the frequency and mode of data updates, checks for database synchronization and consistency, and the choice of preferred data source on start.

name

Name of the “entity” which stores the candle history data.

In the example configs declared within the market_history category.

Note

Also determines the name of the local_cache file (.arrow in data folder).

Note

“Entity” is used as a unifying term to describe a TABLE in Postgres or COLLECTION in MongoDB.

Default gets generated from: exchange _history_ fetch_init_timeframe_days days

E.g. bitfinex_history_120days

Type:

str

exchange

Name of the exchange to use.

Note

Currently, only “bitfinex” is supported.

Default: bitfinex

Type:

str

base_currency

Base currency to trade against, such as “USD” or “BTC”.

Default: USD

Type:

str

candle_interval

Interval for update candles.

Shorter intervals result in more candles and increased precision, while longer intervals are more efficient but less precise.

Options: “1min”, “5min”, “15min”, “30min”, “1h”, “3h”, “6h”, “12h”, “1D”, “1W”

Default: 5min

Type:

str

update_mode

Determines method to update market candle data.

none: Do not update.

Just load data of present DB / cache. Useful for simulation mode or analysis to speed up the process and sufficient data is already present.

once: Only update once

via REST API. Useful for cases where there is already market data present (DB or local cache) and it should be updated to current date before starting the simulation.

live: Update continuously

via Websocket. Useful for live trading or running a dedicated market server.

Default: none

Type:

str

check_db_sync

Checks whether in-memory database is in sync

with the backend database. If not, it will try to sync bi-directionally by exchanging missing candles between the backend and in-memory database. During simulation mode, check_db_sync is usually not necessary and can be disabled for performance improvements (decreases load times).

Default: True

Type:

bool

check_db_consistency

Determines whether to check the in-memory database consistency

by verifying that no missing candles exist between the start and end timestamps. Useful to disable in hyperparameter search scenarios for performance reasons.

Default: True

Type:

bool

force_source

Specifies a particular data source for the candle history.

Options:

• none: Search in order: local_cache, backend, api.

• local_cache: “.arrow” dump of in-memory DB (working_dir/data).

• backend: Fetch history from DB.

• api: Fetch history from exchange via Websocket.

Default: none

Type:

str

---

initial_relevant_assets

Determines the parameters and constraints for initial loading and filtering of relevant assets for simulation and trading. It includes settings that define the timeframe for historical data fetching, the maximum number of assets to load, and criteria for asset relevancy based on candle data attributes (amount and sparsity). There is also an option to exclude specific assets, such as stable coins or those deemed unsuitable for trading.

fetch_init_timeframe_days

Number of days to load the candle history from.

Note

Timeframe is calculated from the current time backwards.

E.g. 120 days -> 120 days ago until now.

Default: 120

Type:

int

relevant_assets_cap

Maximum number of relevant assets to load initially.

If no data is present yet: either from the database or local_cache, a new dataset is fetched from the exchange. This setting limits the number of assets to fetch.

Note

This cap is applied after filtering for relevant asset constraints: See relevant_assets_min_amount_candles and relevant_assets_max_candle_sparsity.

Default: 100

Type:

int

relevant_assets_max_candle_sparsity

Maximum “sparcity” constraint of candles to be considered as relevant asset.

Note

“Relevant assets” get filtered while initially fetching the candle history via API.

Default: 500

Type:

int

relevant_assets_min_amount_candles

Minimum number of candles required for an asset to be considered relevant.

Note

“Relevant assets” get filtered while initially fetching the candle history via API.

Default: 2000

Type:

int

assets_excluded

list of symbols Assets that are stable coins or otherwise unsuitable for trading, to be excluded.

Default: ["UDC", "UST", "EUT", "EUS", "MIM", "PAX", "DAI", "TSD", "TERRAUST", "LEO", "WBT", "RBT", "ETHW", "SHIB", "ETH2X", "SPELL"]

Type:

assets_excluded

---

backend

Determines the Database Management System (DBMS) used for storing market history and trader-specific data. It includes options for selecting the DBMS, with support for Postgres and MongoDB, and defining the host and port for the DBMS connection. The specified database name will be created if it doesn’t exist. Additionally, provides the option to save the in-memory database to a local .arrow file for faster loading in future runs (especially useful in hyperparam optimizations with many parallel simulations).

dbms

Determines which “Database Management System” (DBMS) to use.

Note

Currently, Postgres and MongoDB are supported. Choose Postgres for full functionality, including hyperparameter search via Optuna.

Default: postgres

Type:

str

dbms_host

Fully qualified domain name (FQDN) of the Database Management System (DBMS) such as localhost or a remote address.

Note

The default host docker_db is defined by docker-compose.yml in the examples folder.

Default: docker_db

Type:

str

dbms_port

Port number of the DBMS.

The default port 5433 is defined by docker-compose.yml in the examples folder.

Note

Port 5433 is used instead of the default port 5432 of Postgres to avoid conflict with a potential present Postgres installation.

Default: 5433

Type:

int

dbms_db

Name of the database to use for storing candle history and trader specific data.

Note

Gets created if it does not exist.

Note

Optuna specific data including results of “Studies” is stored in a separate database “optuna”.

Default gets generated from exchange _db

E.g. bitfinex_db

Type:

str

dbms_connect_db

Name of an existing database to connect to when creating a new database.

Note

Specific for SQL DBMS like Postgres: To create a new database, a connection to an existing database with appropriate permissions is needed.

Default: postgres

Type:

str

dbms_user

Username of dbms_db.

Default user is defined by docker-compose.yml in the examples folder.

Default: postgres

Type:

str

dbms_pw

Password for dbms_db.

Default password is defined by docker-compose.yml in the examples folder.

Default: postgres

Type:

str

local_cache

Whether to save the in-memory database to a local .arrow file for faster loading in subsequent runs.

Note

Gets saved on every candle update (candle_interval) into working_dir/data.

Default: True

Type:

bool

---

trader

Determines the trader parameters which include the live trading mode, setting of unique identifiers for trader instances, and defining the initial trading budget for simulations. Settings apply to both, live trading and simulations.

run_live

Whether to run Tradeforce in live trading mode executing the configured strategies on the exchange.

Note

Needs valid credentials in credentials_path: If run_live is True Tradeforce will ask for the API key and secret to the exchange. On every live run the credentials will be decrypt after providing the correct password.

Caution

This is NOT a simulation! The strategy is executed on the exchange. Real money can be lost!

Default: False

Type:

bool

trader_id

Unique identifier for a trader instance. Useful when running multiple live trading strategies on the same database.

Default: 1

Type:

int

budget

Initial trading budget in base_currency (e.g. USD)

Only used for simulations. This value sets the initial budget balance.

Note

In live trading (run_live -> True) this setting will be ignored / overwritten. The budget balance will be dynamically derived from the wallet of the exchange.

Default: 0

Type:

float

maker_fee

Maker fee percentage used to calculate exchange maker fee in simulated trades.

Maker fee is the fee paid to the exchange for adding liquidity to the market. Usually lower than taker fee and paid for buy orders. (which are not instantly filled).

Note

In live trading, actual maker fee from exchange API is applied.

Default: 0.10

Type:

float

taker_fee

Taker fee percentage used to calculate exchange taker fee in simulated trades.

Taker fee is the fee paid to the exchange for removing liquidity from the market. Usually higher than maker fee and paid for market sell orders.

Note

In live trading, actual taker fee from exchange API is applied.

Default: 0.20

Type:

float

---

strategy

Determines the parameters of the default trading strategies (See Default strategies) which is applied to both, live trading and simulations. The optimal values of those parameters can be found by defining a search space and running simulations via Optuna hyperparameter tuning. For more information and an example see hyperparam_search.py.

amount_invest_per_asset

Amount of base_currency (e.g., USD) to invest in each asset upon purchase.

Default: 0.0

Type:

float

moving_window_hours

Timeframe (in hours) of the moving window, to calculate the buy_signal_score which is utilized in the buy_strategy

Default: 20

Type:

int

buy_signal_score

Target buy signal score to consider an asset for purchase at a given point in time.

Specifically, this point in time is the current params["row_idx"] processed by tradeforce.simulator.default_strategies.buy_strategy.

Note

Default implementation to calculate the buy_signal_score is the “sum of percentage changes” within the moving window range (moving_window_hours) See tradeforce.simulator.default_strategies._compute_buy_signals.

Type:

float

buy_signal_boundary

Target lower and upper limit of the buy_signal_score defining a range of acceptable scores for purchasing assets at a given point in time.

Specifically, this point in time is the current params["row_idx"] processed by tradeforce.simulator.default_strategies.buy_strategy.

e.g. buy_signal_boundary == 0.02 means +/-0.02 buy_signal_score to be considered for purchase.

Type:

float

buy_signal_preference

Target preference for buying assets with buy_signal_score values:

• 1 decending -> higher values prefered,

• -1 ascending -> lower values prefered,

• 0 closest -> to the buy_signal_score.

The assets with their respective buy_signal_score are chosen to be purchased in the order from left to right (lower index to higher index).

Note

The buy_signal_preference determines the order of values within the buy_signal_boundary. Thus it determines which asset is prefered to be purchased at a given point in time.

Default: 1

Type:

int

profit_factor_target

Target profit factor.

This value determines the targeted profit on each trade.

e.g. profit_factor_target == 1.05 represents a target of 5% profit on each trade. So if an asset would be purchased for 100 USD, it would be sold for 105 USD once the price is reached.

Default: 0.05

Type:

float

hold_time_days

Number of days to hold an asset before reducing the profit_factor_target to profit_factor_target_min.

Note

Internally _hold_time_increments (based on candle_interval and hold_time_days) is primarily used for any calculation or processing. One increment represents one data record / candle time stamp. (every record is one candle_interval appart from the next)

Default: 4

Type:

int

profit_factor_target_min

Minimum profit factor once hold_time_days is reached, allowing the trader to sell assets at lower profits or even losses (profit_factor_target_min < 1). This is useful to avoid holding assets for too long or to cut losses.

Note

This setting is only relevant if hold_time_days is set > 0.

Default: 1.01

Type:

float

investment_cap

Maximum amount of budget (in base_currency e.g. USD) that can be invested in the market simultaneously: Useful for limiting reinvestment of profits.

Note

Currently only implemented for simulations. Live trader ignores this setting: All potential profits are reinvested.

Note

0.0 equals unlimited investment, no cap. All potential profits are reinvested.

Default: 0.0

Type:

float

max_buy_per_asset

Maximum number of times a single asset can be bought. Useful for managing repeated purchases of an asset with a dropping price.

Note

Currently only 1 supported.

Default: 1

Type:

int

---

simulation

Determines simulation specific parameters.

subset_size_days

Size (in days) of subsets within the entire market candle history. Used to partition the market history data and test the strategy on different (start) conditions for robustness and generalizability.

Note

Partitioning into subsets increases the variance of simulated history data and lowers the risk of overfitting. In other words: if a strategy works well on most subsets, it should also work better on the whole market.

Note

-1 equals no subsets, the whole market is used.

Default: -1

Type:

int

subset_amount

Number of subsets to create (from the entire market history). Subset starting points (indices) are evenly distributed across the history.

Note

Overlapping subsets are possible if: subset_amount * subset_size_days > fetch_init_timeframe_days.

Default: 1

Type:

int

train_val_split_ratio

Ratio of training data (compared to validation data)

The whole market history can be split into a training and a validation set. The ratio defines the proportional size of the training set to the whole market history.

Note

Automatically the validation set will be the remaining part (1 - train_val_split_ratio). So in case of train_val_split_ratio = 0.8 the training data would be 80%, the validation data 0.2 (20%) of the whole market history.

Default: 0.8

Type:

float

---

logging

Sets the logging level for the different loggers.

log_level_ws_live

Log level for the private websocket connection during live trading.

Options: “DEBUG”, “INFO”, “WARNING”, “ERROR”, “CRITICAL”

Default: ERROR (only errors and critical messages are logged)

Type:

str

log_level_ws_update

Log level for the public websocket connection (candle/price updater).

Options: “DEBUG”, “INFO”, “WARNING”, “ERROR”, “CRITICAL”

Default: ERROR (only errors and critical messages are logged)

Type:

str