From 565b343dee73de8ecd5360105479b9c53c434afb Mon Sep 17 00:00:00 2001 From: mrpabloyeah Date: Mon, 22 Sep 2025 19:38:49 +0200 Subject: [PATCH 1/5] Update documentation for Trade and Order objects --- docs/trade-object.md | 173 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 171 insertions(+), 2 deletions(-) diff --git a/docs/trade-object.md b/docs/trade-object.md index 9843d8524..c31baba17 100644 --- a/docs/trade-object.md +++ b/docs/trade-object.md @@ -14,11 +14,22 @@ The following attributes / properties are available for each individual trade - | Attribute | DataType | Description | |------------|-------------|-------------| | `pair` | string | Pair of this trade. | +| `base_currency` | string | Base currency of the trading pair. | +| `stake_currency` | string | Stake/quote currency of the trading pair. | +| `safe_base_currency` | string | Compatibility layer for base currency - falls back to pair split if empty. | +| `safe_quote_currency` | string | Compatibility layer for quote currency - falls back to pair split if empty. | | `is_open` | boolean | Is the trade currently open, or has it been concluded. | +| `exchange` | string | Exchange where this trade was executed. | | `open_rate` | float | Rate this trade was entered at (Avg. entry rate in case of trade-adjustments). | +| `open_rate_requested` | float | The rate that was requested when the trade was opened. | +| `open_trade_value` | float | Value of the open trade including fees. | | `close_rate` | float | Close rate - only set when is_open = False. | +| `close_rate_requested` | float | The close rate that was requested. | +| `safe_close_rate` | float | Close rate or close_rate_requested or 0.0 if neither is available. | | `stake_amount` | float | Amount in Stake (or Quote) currency. | +| `max_stake_amount` | float | Maximum stake amount that was used in this trade (including DCA orders). | | `amount` | float | Amount in Asset / Base currency that is currently owned. Will be 0.0 until the initial order fills. | +| `amount_requested` | float | Amount that was originally requested for this trade. | | `open_date` | datetime | Timestamp when trade was opened **use `open_date_utc` instead** | | `open_date_utc` | datetime | Timestamp when trade was opened - in UTC. | | `close_date` | datetime | Timestamp when trade was closed **use `close_date_utc` instead** | @@ -27,16 +38,90 @@ The following attributes / properties are available for each individual trade - | `close_profit_abs` | float | Absolute profit (in stake currency) at the time of trade closure. | | `realized_profit` | float | Absolute already realized profit (in stake currency) while the trade is still open. | | `leverage` | float | Leverage used for this trade - defaults to 1.0 in spot markets. | +| `has_no_leverage` | boolean | Returns true if this is a non-leverage, non-short trade. | +| `borrowed` | float | The amount of currency borrowed from the exchange for leverage trades. | | `enter_tag` | string | Tag provided on entry via the `enter_tag` column in the dataframe. | +| `buy_tag` | string | **Deprecated** - use `enter_tag` instead. | +| `exit_reason` | string | Reason why the trade was exited. | +| `sell_reason` | string | **Deprecated** - use `exit_reason` instead. | +| `exit_order_status` | string | Status of the exit order. | +| `strategy` | string | Strategy name that was used for this trade. | +| `timeframe` | int | Timeframe used for this trade. | | `is_short` | boolean | True for short trades, False otherwise. | +| `trading_mode` | TradingMode | Trading mode (SPOT, MARGIN, FUTURES). | | `orders` | Order[] | List of order objects attached to this trade (includes both filled and cancelled orders). | | `date_last_filled_utc` | datetime | Time of the last filled order. | +| `date_entry_fill_utc` | datetime | Date of the first filled entry order. | | `entry_side` | "buy" / "sell" | Order Side the trade was entered. | | `exit_side` | "buy" / "sell" | Order Side that will result in a trade exit / position reduction. | | `trade_direction` | "long" / "short" | Trade direction in text - long or short. | | `nr_of_successful_entries` | int | Number of successful (filled) entry orders. | | `nr_of_successful_exits` | int | Number of successful (filled) exit orders. | +| `nr_of_successful_buys` | int | **Deprecated** - use `nr_of_successful_entries` for short support. | +| `nr_of_successful_sells` | int | **Deprecated** - use `nr_of_successful_exits` for short support. | | `has_open_orders` | boolean | Has the trade open orders (excluding stoploss orders). | +| `has_open_position` | boolean | True if there is an open position for this trade. | +| `has_open_sl_orders` | boolean | True if there are open stoploss orders for this trade. | +| `open_orders` | Order[] | All open orders for this trade excluding stoploss orders. | +| `open_sl_orders` | Order[] | All open stoploss orders for this trade. | +| `sl_orders` | Order[] | All stoploss orders for this trade (open and closed). | +| `open_orders_ids` | string[] | List of open order IDs (excluding stoploss orders). | + +### Fee related attributes + +| Attribute | DataType | Description | +|------------|-------------|-------------| +| `fee_open` | float | Fee rate that was paid for opening the trade. | +| `fee_open_cost` | float | Absolute fee cost that was paid for opening the trade. | +| `fee_open_currency` | string | Currency the open fee was paid in. | +| `fee_close` | float | Fee rate that was paid for closing the trade. | +| `fee_close_cost` | float | Absolute fee cost that was paid for closing the trade. | +| `fee_close_currency` | string | Currency the close fee was paid in. | + +### Stop Loss related attributes + +| Attribute | DataType | Description | +|------------|-------------|-------------| +| `stop_loss` | float | Absolute value of the stop loss. | +| `stop_loss_pct` | float | Percentage value of the stop loss. | +| `initial_stop_loss` | float | Absolute value of the initial stop loss. | +| `initial_stop_loss_pct` | float | Percentage value of the initial stop loss. | +| `is_stop_loss_trailing` | boolean | True if the stop loss is trailing. | +| `stoploss_last_update_utc` | datetime | Timestamp of the last stoploss update. | +| `stoploss_or_liquidation` | float | Returns the more restrictive of stoploss or liquidation price. | + +### Price tracking attributes + +| Attribute | DataType | Description | +|------------|-------------|-------------| +| `max_rate` | float | Highest price reached during this trade. | +| `min_rate` | float | Lowest price reached during this trade. | + +### Futures/Margin trading attributes + +| Attribute | DataType | Description | +|------------|-------------|-------------| +| `liquidation_price` | float | Liquidation price for leveraged trades. | +| `interest_rate` | float | Interest rate for margin trades. | +| `funding_fees` | float | Total funding fees for futures trades. | +| `funding_fee_running` | float | Running funding fees between last filled order and now. | + +### Precision attributes + +| Attribute | DataType | Description | +|------------|-------------|-------------| +| `amount_precision` | float | Amount precision for the pair. | +| `price_precision` | float | Price precision for the pair. | +| `precision_mode` | int | Precision mode for amounts. | +| `precision_mode_price` | int | Precision mode for prices. | +| `contract_size` | float | Contract size for futures trading. | + +### Trade counters (for canceled orders) + +| Attribute | DataType | Description | +|------------|-------------|-------------| +| `fully_canceled_entry_order_count` | int | Number of fully canceled entry orders. | +| `canceled_exit_order_count` | int | Number of canceled exit orders. | ## Class methods @@ -120,6 +205,72 @@ Sample return value: ETH/BTC had 5 trades, with a total profit of 1.5% (ratio of {"pair": "ETH/BTC", "profit": 0.015, "count": 5} ``` +### stoploss_reinitialization + +Adjust initial Stoploss to desired stoploss for all open trades. + +``` python +from freqtrade.persistence import Trade + +# ... +Trade.stoploss_reinitialization(desired_stoploss=-0.1) +``` + +### get_enter_tag_performance + +Returns performance grouped by enter_tag. + +``` python +from freqtrade.persistence import Trade + +# ... +performance = Trade.get_enter_tag_performance('ETH/USDT') # or None for all pairs +``` + +### get_exit_reason_performance + +Returns performance grouped by exit_reason. + +``` python +from freqtrade.persistence import Trade + +# ... +performance = Trade.get_exit_reason_performance('ETH/USDT') # or None for all pairs +``` + +### get_mix_tag_performance + +Returns performance grouped by enter_tag + exit_reason combination. + +``` python +from freqtrade.persistence import Trade + +# ... +performance = Trade.get_mix_tag_performance('ETH/USDT') # or None for all pairs +``` + +### get_best_pair + +Get the best performing pair with closed trades. + +``` python +from freqtrade.persistence import Trade + +# ... +best_pair = Trade.get_best_pair() +``` + +### get_trading_volume + +Get total trading volume based on orders. + +``` python +from freqtrade.persistence import Trade + +# ... +volume = Trade.get_trading_volume() +``` + ## Order Object An `Order` object represents an order on the exchange (or a simulated order in dry-run mode). @@ -133,22 +284,40 @@ Most properties here can be None as they are dependent on the exchange response. | Attribute | DataType | Description | |------------|-------------|-------------| | `trade` | Trade | Trade object this order is attached to | +| `ft_trade_id` | int | ID of the trade this order belongs to | | `ft_pair` | string | Pair this order is for | | `ft_is_open` | boolean | is the order still open? | +| `ft_amount` | float | Amount in base currency (freqtrade's internal amount) | +| `ft_price` | float | Price the order was placed at (freqtrade's internal price) | +| `ft_order_side` | string | Order side ('buy', 'sell', or 'stoploss') | +| `ft_cancel_reason` | string | Reason why the order was canceled | +| `ft_order_tag` | string | Custom order tag | +| `ft_fee_base` | float | Fee paid in base currency | +| `order_id` | string | Exchange order ID | | `order_type` | string | Order type as defined on the exchange - usually market, limit or stoploss | | `status` | string | Status as defined by [ccxt's order structure](https://docs.ccxt.com/#/README?id=order-structure). Usually open, closed, expired, canceled or rejected | +| `symbol` | string | Symbol/pair as defined by the exchange | | `side` | string | buy or sell | | `price` | float | Price the order was placed at | | `average` | float | Average price the order filled at | | `amount` | float | Amount in base currency | | `filled` | float | Filled amount (in base currency) (use `safe_filled` instead) | | `safe_filled` | float | Filled amount (in base currency) - guaranteed to not be None | +| `safe_amount` | float | Amount - falls back to ft_amount if None | +| `safe_price` | float | Price - falls back through average, price, stop_price, ft_price | +| `safe_placement_price` | float | Price at which the order was placed | | `remaining` | float | Remaining amount (use `safe_remaining` instead) | | `safe_remaining` | float | Remaining amount - either taken from the exchange or calculated. | +| `safe_cost` | float | Cost of the order - guaranteed to not be None | +| `safe_fee_base` | float | Fee in base currency - guaranteed to not be None | +| `safe_amount_after_fee` | float | Amount after deducting fees | | `cost` | float | Cost of the order - usually average * filled (*Exchange dependent on futures, may contain the cost with or without leverage and may be in contracts.*) | +| `stop_price` | float | Stop price for stop orders | | `stake_amount` | float | Stake amount used for this order. *Added in 2023.7.* | | `stake_amount_filled` | float | Filled Stake amount used for this order. *Added in 2024.11.* | | `order_date` | datetime | Order creation date **use `order_date_utc` instead** | | `order_date_utc` | datetime | Order creation date (in UTC) | -| `order_fill_date` | datetime | Order fill date **use `order_fill_utc` instead** | -| `order_fill_date_utc` | datetime | Order fill date | +| `order_filled_date` | datetime | Order fill date **use `order_filled_utc` instead** | +| `order_filled_utc` | datetime | Order fill date | +| `order_update_date` | datetime | Last order update date | +| `funding_fee` | float | Funding fee for this order (futures trading) | From c1cd14cad2933fd9cbfaf89f9c4ae9697b126f51 Mon Sep 17 00:00:00 2001 From: mrpabloyeah Date: Tue, 23 Sep 2025 01:01:36 +0200 Subject: [PATCH 2/5] Remove internal or useless attributes and unnecessary text --- docs/trade-object.md | 98 -------------------------------------------- 1 file changed, 98 deletions(-) diff --git a/docs/trade-object.md b/docs/trade-object.md index c31baba17..7dd01cfe2 100644 --- a/docs/trade-object.md +++ b/docs/trade-object.md @@ -16,20 +16,11 @@ The following attributes / properties are available for each individual trade - | `pair` | string | Pair of this trade. | | `base_currency` | string | Base currency of the trading pair. | | `stake_currency` | string | Stake/quote currency of the trading pair. | -| `safe_base_currency` | string | Compatibility layer for base currency - falls back to pair split if empty. | -| `safe_quote_currency` | string | Compatibility layer for quote currency - falls back to pair split if empty. | | `is_open` | boolean | Is the trade currently open, or has it been concluded. | -| `exchange` | string | Exchange where this trade was executed. | | `open_rate` | float | Rate this trade was entered at (Avg. entry rate in case of trade-adjustments). | -| `open_rate_requested` | float | The rate that was requested when the trade was opened. | -| `open_trade_value` | float | Value of the open trade including fees. | | `close_rate` | float | Close rate - only set when is_open = False. | -| `close_rate_requested` | float | The close rate that was requested. | -| `safe_close_rate` | float | Close rate or close_rate_requested or 0.0 if neither is available. | | `stake_amount` | float | Amount in Stake (or Quote) currency. | -| `max_stake_amount` | float | Maximum stake amount that was used in this trade (including DCA orders). | | `amount` | float | Amount in Asset / Base currency that is currently owned. Will be 0.0 until the initial order fills. | -| `amount_requested` | float | Amount that was originally requested for this trade. | | `open_date` | datetime | Timestamp when trade was opened **use `open_date_utc` instead** | | `open_date_utc` | datetime | Timestamp when trade was opened - in UTC. | | `close_date` | datetime | Timestamp when trade was closed **use `close_date_utc` instead** | @@ -38,17 +29,9 @@ The following attributes / properties are available for each individual trade - | `close_profit_abs` | float | Absolute profit (in stake currency) at the time of trade closure. | | `realized_profit` | float | Absolute already realized profit (in stake currency) while the trade is still open. | | `leverage` | float | Leverage used for this trade - defaults to 1.0 in spot markets. | -| `has_no_leverage` | boolean | Returns true if this is a non-leverage, non-short trade. | -| `borrowed` | float | The amount of currency borrowed from the exchange for leverage trades. | | `enter_tag` | string | Tag provided on entry via the `enter_tag` column in the dataframe. | -| `buy_tag` | string | **Deprecated** - use `enter_tag` instead. | | `exit_reason` | string | Reason why the trade was exited. | -| `sell_reason` | string | **Deprecated** - use `exit_reason` instead. | -| `exit_order_status` | string | Status of the exit order. | -| `strategy` | string | Strategy name that was used for this trade. | -| `timeframe` | int | Timeframe used for this trade. | | `is_short` | boolean | True for short trades, False otherwise. | -| `trading_mode` | TradingMode | Trading mode (SPOT, MARGIN, FUTURES). | | `orders` | Order[] | List of order objects attached to this trade (includes both filled and cancelled orders). | | `date_last_filled_utc` | datetime | Time of the last filled order. | | `date_entry_fill_utc` | datetime | Date of the first filled entry order. | @@ -57,31 +40,8 @@ The following attributes / properties are available for each individual trade - | `trade_direction` | "long" / "short" | Trade direction in text - long or short. | | `nr_of_successful_entries` | int | Number of successful (filled) entry orders. | | `nr_of_successful_exits` | int | Number of successful (filled) exit orders. | -| `nr_of_successful_buys` | int | **Deprecated** - use `nr_of_successful_entries` for short support. | -| `nr_of_successful_sells` | int | **Deprecated** - use `nr_of_successful_exits` for short support. | | `has_open_orders` | boolean | Has the trade open orders (excluding stoploss orders). | -| `has_open_position` | boolean | True if there is an open position for this trade. | -| `has_open_sl_orders` | boolean | True if there are open stoploss orders for this trade. | | `open_orders` | Order[] | All open orders for this trade excluding stoploss orders. | -| `open_sl_orders` | Order[] | All open stoploss orders for this trade. | -| `sl_orders` | Order[] | All stoploss orders for this trade (open and closed). | -| `open_orders_ids` | string[] | List of open order IDs (excluding stoploss orders). | - -### Fee related attributes - -| Attribute | DataType | Description | -|------------|-------------|-------------| -| `fee_open` | float | Fee rate that was paid for opening the trade. | -| `fee_open_cost` | float | Absolute fee cost that was paid for opening the trade. | -| `fee_open_currency` | string | Currency the open fee was paid in. | -| `fee_close` | float | Fee rate that was paid for closing the trade. | -| `fee_close_cost` | float | Absolute fee cost that was paid for closing the trade. | -| `fee_close_currency` | string | Currency the close fee was paid in. | - -### Stop Loss related attributes - -| Attribute | DataType | Description | -|------------|-------------|-------------| | `stop_loss` | float | Absolute value of the stop loss. | | `stop_loss_pct` | float | Percentage value of the stop loss. | | `initial_stop_loss` | float | Absolute value of the initial stop loss. | @@ -89,40 +49,9 @@ The following attributes / properties are available for each individual trade - | `is_stop_loss_trailing` | boolean | True if the stop loss is trailing. | | `stoploss_last_update_utc` | datetime | Timestamp of the last stoploss update. | | `stoploss_or_liquidation` | float | Returns the more restrictive of stoploss or liquidation price. | - -### Price tracking attributes - -| Attribute | DataType | Description | -|------------|-------------|-------------| | `max_rate` | float | Highest price reached during this trade. | | `min_rate` | float | Lowest price reached during this trade. | -### Futures/Margin trading attributes - -| Attribute | DataType | Description | -|------------|-------------|-------------| -| `liquidation_price` | float | Liquidation price for leveraged trades. | -| `interest_rate` | float | Interest rate for margin trades. | -| `funding_fees` | float | Total funding fees for futures trades. | -| `funding_fee_running` | float | Running funding fees between last filled order and now. | - -### Precision attributes - -| Attribute | DataType | Description | -|------------|-------------|-------------| -| `amount_precision` | float | Amount precision for the pair. | -| `price_precision` | float | Price precision for the pair. | -| `precision_mode` | int | Precision mode for amounts. | -| `precision_mode_price` | int | Precision mode for prices. | -| `contract_size` | float | Contract size for futures trading. | - -### Trade counters (for canceled orders) - -| Attribute | DataType | Description | -|------------|-------------|-------------| -| `fully_canceled_entry_order_count` | int | Number of fully canceled entry orders. | -| `canceled_exit_order_count` | int | Number of canceled exit orders. | - ## Class methods The following are class methods - which return generic information, and usually result in an explicit query against the database. @@ -205,17 +134,6 @@ Sample return value: ETH/BTC had 5 trades, with a total profit of 1.5% (ratio of {"pair": "ETH/BTC", "profit": 0.015, "count": 5} ``` -### stoploss_reinitialization - -Adjust initial Stoploss to desired stoploss for all open trades. - -``` python -from freqtrade.persistence import Trade - -# ... -Trade.stoploss_reinitialization(desired_stoploss=-0.1) -``` - ### get_enter_tag_performance Returns performance grouped by enter_tag. @@ -284,35 +202,19 @@ Most properties here can be None as they are dependent on the exchange response. | Attribute | DataType | Description | |------------|-------------|-------------| | `trade` | Trade | Trade object this order is attached to | -| `ft_trade_id` | int | ID of the trade this order belongs to | | `ft_pair` | string | Pair this order is for | | `ft_is_open` | boolean | is the order still open? | -| `ft_amount` | float | Amount in base currency (freqtrade's internal amount) | -| `ft_price` | float | Price the order was placed at (freqtrade's internal price) | -| `ft_order_side` | string | Order side ('buy', 'sell', or 'stoploss') | -| `ft_cancel_reason` | string | Reason why the order was canceled | -| `ft_order_tag` | string | Custom order tag | -| `ft_fee_base` | float | Fee paid in base currency | -| `order_id` | string | Exchange order ID | | `order_type` | string | Order type as defined on the exchange - usually market, limit or stoploss | | `status` | string | Status as defined by [ccxt's order structure](https://docs.ccxt.com/#/README?id=order-structure). Usually open, closed, expired, canceled or rejected | -| `symbol` | string | Symbol/pair as defined by the exchange | | `side` | string | buy or sell | | `price` | float | Price the order was placed at | | `average` | float | Average price the order filled at | | `amount` | float | Amount in base currency | | `filled` | float | Filled amount (in base currency) (use `safe_filled` instead) | | `safe_filled` | float | Filled amount (in base currency) - guaranteed to not be None | -| `safe_amount` | float | Amount - falls back to ft_amount if None | -| `safe_price` | float | Price - falls back through average, price, stop_price, ft_price | -| `safe_placement_price` | float | Price at which the order was placed | | `remaining` | float | Remaining amount (use `safe_remaining` instead) | | `safe_remaining` | float | Remaining amount - either taken from the exchange or calculated. | -| `safe_cost` | float | Cost of the order - guaranteed to not be None | -| `safe_fee_base` | float | Fee in base currency - guaranteed to not be None | -| `safe_amount_after_fee` | float | Amount after deducting fees | | `cost` | float | Cost of the order - usually average * filled (*Exchange dependent on futures, may contain the cost with or without leverage and may be in contracts.*) | -| `stop_price` | float | Stop price for stop orders | | `stake_amount` | float | Stake amount used for this order. *Added in 2023.7.* | | `stake_amount_filled` | float | Filled Stake amount used for this order. *Added in 2024.11.* | | `order_date` | datetime | Order creation date **use `order_date_utc` instead** | From f529b7b52633876e6d8666253f2e9409b352bd03 Mon Sep 17 00:00:00 2001 From: Matthias Date: Sun, 12 Oct 2025 10:25:56 +0200 Subject: [PATCH 3/5] docs: Update trade-object documentation partially reverts c1cd14 - includes a few enhancements to it --- docs/trade-object.md | 64 ++++++++++++++++++++++++++++++++++++-------- 1 file changed, 53 insertions(+), 11 deletions(-) diff --git a/docs/trade-object.md b/docs/trade-object.md index 7dd01cfe2..fb96d1df9 100644 --- a/docs/trade-object.md +++ b/docs/trade-object.md @@ -14,13 +14,20 @@ The following attributes / properties are available for each individual trade - | Attribute | DataType | Description | |------------|-------------|-------------| | `pair` | string | Pair of this trade. | -| `base_currency` | string | Base currency of the trading pair. | -| `stake_currency` | string | Stake/quote currency of the trading pair. | +| `safe_base_currency` | string | Compatibility layer for base currency . | +| `safe_quote_currency` | string | Compatibility layer for quote currency. | | `is_open` | boolean | Is the trade currently open, or has it been concluded. | +| `exchange` | string | Exchange where this trade was executed. | | `open_rate` | float | Rate this trade was entered at (Avg. entry rate in case of trade-adjustments). | +| `open_rate_requested` | float | The rate that was requested when the trade was opened. | +| `open_trade_value` | float | Value of the open trade including fees. | | `close_rate` | float | Close rate - only set when is_open = False. | +| `close_rate_requested` | float | The close rate that was requested. | +| `safe_close_rate` | float | Close rate or close_rate_requested or 0.0 if neither is available. | | `stake_amount` | float | Amount in Stake (or Quote) currency. | +| `max_stake_amount` | float | Maximum stake amount that was used in this trade (including DCA orders). | | `amount` | float | Amount in Asset / Base currency that is currently owned. Will be 0.0 until the initial order fills. | +| `amount_requested` | float | Amount that was originally requested for this trade in the first entry order. | | `open_date` | datetime | Timestamp when trade was opened **use `open_date_utc` instead** | | `open_date_utc` | datetime | Timestamp when trade was opened - in UTC. | | `close_date` | datetime | Timestamp when trade was closed **use `close_date_utc` instead** | @@ -31,6 +38,9 @@ The following attributes / properties are available for each individual trade - | `leverage` | float | Leverage used for this trade - defaults to 1.0 in spot markets. | | `enter_tag` | string | Tag provided on entry via the `enter_tag` column in the dataframe. | | `exit_reason` | string | Reason why the trade was exited. | +| `exit_order_status` | string | Status of the exit order. | +| `strategy` | string | Strategy name that was used for this trade. | +| `timeframe` | int | Timeframe used for this trade. | | `is_short` | boolean | True for short trades, False otherwise. | | `orders` | Order[] | List of order objects attached to this trade (includes both filled and cancelled orders). | | `date_last_filled_utc` | datetime | Time of the last filled order. | @@ -38,19 +48,37 @@ The following attributes / properties are available for each individual trade - | `entry_side` | "buy" / "sell" | Order Side the trade was entered. | | `exit_side` | "buy" / "sell" | Order Side that will result in a trade exit / position reduction. | | `trade_direction` | "long" / "short" | Trade direction in text - long or short. | +| `max_rate` | float | Highest price reached during this trade. Not 100% accurate. | +| `min_rate` | float | Lowest price reached during this trade. Not 100% accurate. | | `nr_of_successful_entries` | int | Number of successful (filled) entry orders. | | `nr_of_successful_exits` | int | Number of successful (filled) exit orders. | +| `has_open_position` | boolean | True if there is an open position (amount > 0) for this trade. Only false while the initial entry order is unfilled. | | `has_open_orders` | boolean | Has the trade open orders (excluding stoploss orders). | +| `has_open_sl_orders` | boolean | True if there are open stoploss orders for this trade. | | `open_orders` | Order[] | All open orders for this trade excluding stoploss orders. | +| `open_sl_orders` | Order[] | All open stoploss orders for this trade. | +| `fully_canceled_entry_order_count` | int | Number of fully canceled entry orders. | +| `canceled_exit_order_count` | int | Number of canceled exit orders. | + +### Stop Loss related attributes + +| Attribute | DataType | Description | +|------------|-------------|-------------| | `stop_loss` | float | Absolute value of the stop loss. | -| `stop_loss_pct` | float | Percentage value of the stop loss. | +| `stop_loss_pct` | float | Relative value of the stop loss. | | `initial_stop_loss` | float | Absolute value of the initial stop loss. | -| `initial_stop_loss_pct` | float | Percentage value of the initial stop loss. | +| `initial_stop_loss_pct` | float | Relative value of the initial stop loss. | | `is_stop_loss_trailing` | boolean | True if the stop loss is trailing. | | `stoploss_last_update_utc` | datetime | Timestamp of the last stoploss update. | -| `stoploss_or_liquidation` | float | Returns the more restrictive of stoploss or liquidation price. | -| `max_rate` | float | Highest price reached during this trade. | -| `min_rate` | float | Lowest price reached during this trade. | +| `stoploss_or_liquidation` | float | Returns the more restrictive of stoploss or liquidation price and corresponds to the price a stoploss would trigger at. | + +### Futures/Margin trading attributes + +| Attribute | DataType | Description | +|------------|-------------|-------------| +| `liquidation_price` | float | Liquidation price for leveraged trades. | +| `interest_rate` | float | Interest rate for margin trades. | +| `funding_fees` | float | Total funding fees for futures trades. | ## Class methods @@ -116,6 +144,10 @@ from freqtrade.persistence import Trade profit = Trade.total_open_trades_stakes() ``` +## Class methods not supported in backtesting/hyperopt + +The following class methods are not supported in backtesting/hyperopt mode. + ### get_overall_performance Retrieve the overall performance - similar to the `/performance` telegram command. @@ -204,6 +236,10 @@ Most properties here can be None as they are dependent on the exchange response. | `trade` | Trade | Trade object this order is attached to | | `ft_pair` | string | Pair this order is for | | `ft_is_open` | boolean | is the order still open? | +| `ft_order_side` | string | Order side ('buy', 'sell', or 'stoploss') | +| `ft_cancel_reason` | string | Reason why the order was canceled | +| `ft_order_tag` | string | Custom order tag | +| `order_id` | string | Exchange order ID | | `order_type` | string | Order type as defined on the exchange - usually market, limit or stoploss | | `status` | string | Status as defined by [ccxt's order structure](https://docs.ccxt.com/#/README?id=order-structure). Usually open, closed, expired, canceled or rejected | | `side` | string | buy or sell | @@ -212,14 +248,20 @@ Most properties here can be None as they are dependent on the exchange response. | `amount` | float | Amount in base currency | | `filled` | float | Filled amount (in base currency) (use `safe_filled` instead) | | `safe_filled` | float | Filled amount (in base currency) - guaranteed to not be None | +| `safe_amount` | float | Amount - falls back to ft_amount if None | +| `safe_price` | float | Price - falls back through average, price, stop_price, ft_price | +| `safe_placement_price` | float | Price at which the order was placed | | `remaining` | float | Remaining amount (use `safe_remaining` instead) | | `safe_remaining` | float | Remaining amount - either taken from the exchange or calculated. | -| `cost` | float | Cost of the order - usually average * filled (*Exchange dependent on futures, may contain the cost with or without leverage and may be in contracts.*) | -| `stake_amount` | float | Stake amount used for this order. *Added in 2023.7.* | -| `stake_amount_filled` | float | Filled Stake amount used for this order. *Added in 2024.11.* | +| `safe_cost` | float | Cost of the order - guaranteed to not be None | +| `safe_fee_base` | float | Fee in base currency - guaranteed to not be None | +| `safe_amount_after_fee` | float | Amount after deducting fees | +| `cost` | float | Cost of the order - usually average * filled (*Exchange dependent on futures trading, may contain the cost with or without leverage and may be in contracts.*) | +| `stop_price` | float | Stop price for stop orders. Empty for non-stoploss orders. | +| `stake_amount` | float | Stake amount used for this order. | +| `stake_amount_filled` | float | Filled Stake amount used for this order. | | `order_date` | datetime | Order creation date **use `order_date_utc` instead** | | `order_date_utc` | datetime | Order creation date (in UTC) | | `order_filled_date` | datetime | Order fill date **use `order_filled_utc` instead** | | `order_filled_utc` | datetime | Order fill date | | `order_update_date` | datetime | Last order update date | -| `funding_fee` | float | Funding fee for this order (futures trading) | From bb6e33c8c4cc7020a14e54fae47f72f1827d969d Mon Sep 17 00:00:00 2001 From: Matthias Date: Sun, 12 Oct 2025 10:29:07 +0200 Subject: [PATCH 4/5] docs: remove methods that are not considered as public interface --- docs/trade-object.md | 44 -------------------------------------------- 1 file changed, 44 deletions(-) diff --git a/docs/trade-object.md b/docs/trade-object.md index fb96d1df9..f6a3accfc 100644 --- a/docs/trade-object.md +++ b/docs/trade-object.md @@ -166,50 +166,6 @@ Sample return value: ETH/BTC had 5 trades, with a total profit of 1.5% (ratio of {"pair": "ETH/BTC", "profit": 0.015, "count": 5} ``` -### get_enter_tag_performance - -Returns performance grouped by enter_tag. - -``` python -from freqtrade.persistence import Trade - -# ... -performance = Trade.get_enter_tag_performance('ETH/USDT') # or None for all pairs -``` - -### get_exit_reason_performance - -Returns performance grouped by exit_reason. - -``` python -from freqtrade.persistence import Trade - -# ... -performance = Trade.get_exit_reason_performance('ETH/USDT') # or None for all pairs -``` - -### get_mix_tag_performance - -Returns performance grouped by enter_tag + exit_reason combination. - -``` python -from freqtrade.persistence import Trade - -# ... -performance = Trade.get_mix_tag_performance('ETH/USDT') # or None for all pairs -``` - -### get_best_pair - -Get the best performing pair with closed trades. - -``` python -from freqtrade.persistence import Trade - -# ... -best_pair = Trade.get_best_pair() -``` - ### get_trading_volume Get total trading volume based on orders. From ca76ccb6af34eac6e18e20bbf93daf8a99f5392c Mon Sep 17 00:00:00 2001 From: Matthias Date: Sun, 12 Oct 2025 15:22:36 +0200 Subject: [PATCH 5/5] docs: improve some documentation wording --- docs/trade-object.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/trade-object.md b/docs/trade-object.md index f6a3accfc..b21c447ec 100644 --- a/docs/trade-object.md +++ b/docs/trade-object.md @@ -23,11 +23,11 @@ The following attributes / properties are available for each individual trade - | `open_trade_value` | float | Value of the open trade including fees. | | `close_rate` | float | Close rate - only set when is_open = False. | | `close_rate_requested` | float | The close rate that was requested. | -| `safe_close_rate` | float | Close rate or close_rate_requested or 0.0 if neither is available. | +| `safe_close_rate` | float | Close rate or `close_rate_requested` or 0.0 if neither is available. Only makes sense once the trade is closed. | | `stake_amount` | float | Amount in Stake (or Quote) currency. | -| `max_stake_amount` | float | Maximum stake amount that was used in this trade (including DCA orders). | +| `max_stake_amount` | float | Maximum stake amount that was used in this trade (sum of all filled Entry orders). | | `amount` | float | Amount in Asset / Base currency that is currently owned. Will be 0.0 until the initial order fills. | -| `amount_requested` | float | Amount that was originally requested for this trade in the first entry order. | +| `amount_requested` | float | Amount that was originally requested for this trade as part of the first entry order. | | `open_date` | datetime | Timestamp when trade was opened **use `open_date_utc` instead** | | `open_date_utc` | datetime | Timestamp when trade was opened - in UTC. | | `close_date` | datetime | Timestamp when trade was closed **use `close_date_utc` instead** | @@ -68,8 +68,7 @@ The following attributes / properties are available for each individual trade - | `stop_loss_pct` | float | Relative value of the stop loss. | | `initial_stop_loss` | float | Absolute value of the initial stop loss. | | `initial_stop_loss_pct` | float | Relative value of the initial stop loss. | -| `is_stop_loss_trailing` | boolean | True if the stop loss is trailing. | -| `stoploss_last_update_utc` | datetime | Timestamp of the last stoploss update. | +| `stoploss_last_update_utc` | datetime | Timestamp of the last stoploss on exchange order update. | | `stoploss_or_liquidation` | float | Returns the more restrictive of stoploss or liquidation price and corresponds to the price a stoploss would trigger at. | ### Futures/Margin trading attributes