Freqtrade Trade 与 Order 对象完全指南交易数据模型、属性速查与策略内查询方法【免费下载链接】freqtradeFree, open source crypto trading bot项目地址: https://gitcode.com/GitHub_Trending/fr/freqtradeTrade与Order是 Freqtrade 交易机器人的核心数据模型每一次机器人开仓都会生成一个Trade对象并被持久化到 SQLite 数据库同时通过一对一/一对多关系挂载若干Order对象。理解这两个对象是编写自定义策略回调、读懂回测与实盘日志、以及用 REST API / Telegram 命令分析持仓的关键前提。本文以 docs/trade-object.md 为主线结合仓库源码逐一讲解Trade的可用属性、类方法、Order对象的字段语义并给出可直接复用的查询代码与使用边界。Trade Object一笔仓位的完整生命周期记录在 Freqtrade 中一个被开出的仓位会以Trade对象的形式存在并且被持久化到数据库中。它是整个机器人最核心的概念之一文档的许多章节尤其是各类策略回调都会引用到它因此大多数文档会指引读者回到本文所在的位置。从源码结构看该模型被拆分成两部分定义在 freqtrade/persistence/trade_model.pyLocalTradetrade_model.py L385use_db False维护bt_trades、bt_trades_open等内存列表专供**回测backtesting与超参优化hyperopt**使用Trade(ModelBase, LocalTrade)trade_model.py L1704use_db True映射数据库表trades是实盘 / 模拟盘dry-run使用的模型代码注释明确要求Trade与LocalTrade的字段必须保持对齐。Trade通过 SQLAlchemy 与Order建立一对多关系trades↔orders外键ft_trade_id。也就是说一笔交易下可能挂有多张订单加仓入场、分批离场、止损单等而一张订单只能归属一笔交易。在策略回调中作为参数传递Trade对象会被作为参数传入很多策略回调详见 docs/strategy-callbacks.md。传入策略的 Trade 对象不能被直接修改——开发者不能改写其属性来作弊只有当回调返回特定结果如新的入场价、调整后的订单、止损参数等时机器人内部逻辑才会基于这些返回值间接更新交易状态。有一个重要的边界条件在custom_entry_price()等回调中只有当与该交易关联的第一张入场单创建之后Trade对象才可用对于首次入场trade参数可能为None见 docs/strategy-callbacks.md 的 Note。Trade 可用属性速查下面这些属性 / 派生属性对每一笔交易均可用在策略中写作trade.property如trade.pair即可访问。下表完整覆盖官方文档并给出数据类型与语义说明Attribute数据类型说明pairstring本笔交易对应的交易对。safe_base_currencystring基础货币的兼容层老交易可能没有该字段见源码 trade_model.py L570。safe_quote_currencystring计价货币的兼容层。is_openboolean交易当前是否仍未平仓。exchangestring执行这笔交易的交易所。open_ratefloat入场价格如有多次调整 / 加仓则为平均入场价。open_rate_requestedfloat开仓时请求的价格挂单价格。open_trade_valuefloat开仓时的仓位价值已含手续费。close_ratefloat平仓价格——仅在is_open False时被设置。close_rate_requestedfloat请求的平仓价格。safe_close_ratefloat依次取close_rate、close_rate_requested都不可用则为0.0仅在平仓后有意义。stake_amountfloat以 Stake计价货币计量的投入金额。max_stake_amountfloat本笔交易用到的最大投入金额所有已成交入场单的累计。amountfloat当前持有的资产基础货币数量在首张订单成交前为0.0。amount_requestedfloat第一张入场单最初请求的数量。open_datedatetime开仓时间戳——请改用open_date_utc。open_date_utcdatetime开仓时间戳UTC。close_datedatetime平仓时间戳——请改用close_date_utc。close_date_utcdatetime平仓时间戳UTC。close_profitfloat平仓时的相对收益0.01 1%。close_profit_absfloat平仓时的绝对收益以 Stake 货币计。realized_profitfloat交易仍开启时已兑现的绝对收益以 Stake 货币计。leveragefloat本笔交易使用的杠杆现货市场默认为1.0。enter_tagstring通过 dataframe 中的enter_tag列提供的入场标签。exit_reasonstring离场原因。exit_order_statusstring离场订单的状态。strategystring创建该交易时使用的策略名称。timeframeint本笔交易使用的时间周期。is_shortboolean做空为 True否则为 False。ordersOrder[]挂在本笔交易下的订单对象列表包含已成交与已取消订单。date_last_filled_utcdatetime最近一次成交订单的时间。date_entry_fill_utcdatetime第一张入场订单的成交日期。entry_sidebuy / sell交易入场的订单方向。exit_sidebuy / sell会导致离场 / 减仓的订单方向。trade_directionlong / short文字形式的交易方向。max_ratefloat本笔交易期间到达的最高价格并非 100% 精确。min_ratefloat本笔交易期间到达的最低价格并非 100% 精确。nr_of_successful_entriesint成功已成交的入场订单数量。nr_of_successful_exitsint成功已成交的离场订单数量。has_open_positionboolean本笔交易是否仍有敞口头寸amount 0仅当初始入场单未成交时为 False。has_open_ordersboolean交易是否有挂单不含止损单。has_open_sl_ordersboolean交易是否有尚未触发的止损单。open_ordersOrder[]交易当前所有挂单不含止损单。open_sl_ordersOrder[]交易当前所有未触发止损单。fully_canceled_entry_order_countint完全被取消的入场订单数量。canceled_exit_order_countint被取消的离场订单数量。提示旧版本中的buy_tag已由enter_tag取代源码中的buy_tag属性仅作兼容别名保留trade_model.py L482。数据来源与字段精度说明open_date/close_date为数据库原生存储值不含时区信息open_date_utc/close_date_utc派生属性会为其补上 UTC 时区trade_model.py L535。这也是官方推荐请改用*_utc版本的原因——UTC 时间在跨时区部署、与交易所时间对齐时不会产生歧义。entry_side/exit_side/trade_direction均为派生属性做空单entry_side sell、exit_side buy做多单则相反trade_model.py L549。max_rate/min_rate由adjust_min_max_rates()在每次行情处理时更新trade_model.py L801文档明确标注非 100% 精确因为其依赖机器人收到行情 tick 的采样频率。safe_base_currency/safe_quote_currency属于兼容层老交易可能没有落库的货币字段此时会回退到从pair字符串解析pair.split(/)[0]。止损Stop Loss相关属性Attribute数据类型说明stop_lossfloat止损价的绝对值。stop_loss_pctfloat止损价的相对值负数百分比如 -0.05 表示 -5%。initial_stop_lossfloat初始止损价的绝对值。initial_stop_loss_pctfloat初始止损价的相对值。stoploss_last_update_utcdatetime最后一次交易所端止损单更新的时间戳。stoploss_or_liquidationfloat返回止损价与强平价中更严格的那个即止损单实际会触发的价位。源码层面的几点佐证__set_stop_loss()只在首次设置时记录initial_stop_loss并始终将stop_loss_pct规范为负数绝对值trade_model.py L829adjust_stop_loss()实现了止损只上移不下移做多的逻辑并区分initial初始化与allow_refresh允许双向调整两种调用场景trade_model.py L839stoploss_last_update_utc取自当前未触发止损单中最晚的order_date_utctrade_model.py L539stoploss_or_liquidation若存在强平价做多取max(stop_loss, liquidation_price)、做空取min(stop_loss, liquidation_price)否则退回stop_losstrade_model.py L472。合约 / 保证金交易Futures / Margin属性Attribute数据类型说明liquidation_pricefloat杠杆交易的强平价格。interest_ratefloat保证金交易的利率。funding_feesfloat合约交易的累计资金费用。相关实现说明强平价通过set_liquidation_price()写入并且会经过交易所价格精度取整trade_model.py L808资金费用通过set_funding_fees()累计funding_fees 历史订单上的 funding_fee 之和 当前滚动中的 funding_feetrade_model.py L819保证金交易的利息按小时计算计算公式见calculate_interest()trade_model.py L1074订单上还会记录funding_fee字段便于回测按date_last_filled_utc结算资金费率。Trade 的类方法Class Methods以下方法属于类方法返回通用信息通常会对数据库发起一次显式查询。调用形式为Trade.method例如open_trades Trade.get_open_trade_count()Backtesting / Hyperopt 警告大多数类方法在回测 / 超参优化与实盘 / 模拟盘模式下都能工作。但在回测期间它们仅限用于策略回调见 docs/strategy-callbacks.md在populate_*()方法中使用将返回错误结果不受支持。从源码可以解释这一限制的根因Trade.use_db在回测模式下为False此时数据不落在数据库里而是保存在LocalTrade.bt_trades/bt_trades_open内存列表与bt_open_open_trade_count、bt_total_profit等计数器上trade_model.py L391-L399。类方法内部正是通过if Trade.use_db:分支来决定走SQLAlchemy 查询还是内存列表过滤如 get_trades_proxy。get_trades_proxy —— 查询历史/持仓交易的首选当你的策略需要了解已存在交易开仓或平仓的信息时最好使用Trade.get_trades_proxy()。from freqtrade.persistence import Trade from datetime import timedelta # ... trade_hist Trade.get_trades_proxy( pairETH/USDT, is_openFalse, open_datecurrent_date - timedelta(days2) )get_trades_proxy()支持以下关键字参数所有参数均为可选——不带参数调用将返回数据库中全部交易的列表pair例如pairETH/USDTis_open例如is_openFalseopen_date例如open_datecurrent_date - timedelta(days2)按trade.open_date 输入值过滤close_date例如close_datecurrent_date - timedelta(days5)按trade.close_date 输入值过滤会隐含只返回已平仓交易。源码细节实盘模式下会组装 SQLAlchemy 过滤器查询trade_model.py L1833回测模式下则直接对内存中的LocalTrade列表做 Python 过滤trade_model.py L1498。get_open_trade_count —— 当前持仓数量from freqtrade.persistence import Trade # ... open_trades Trade.get_open_trade_count()源码对应select(count(Trade.id)).filter(Trade.is_open.is_(True))回测模式直接返回维护好的bt_open_open_trade_count计数器trade_model.py L1572。get_total_closed_profit —— 累计已实现收益获取机器人迄今为止产生的总收益聚合所有已平仓交易的close_profit_absfrom freqtrade.persistence import Trade # ... profit Trade.get_total_closed_profit()源码对is_open False的交易求和close_profit_abstrade_model.py L1938。total_open_trades_stakes —— 当前持仓总投入获取当前仍在交易中的stake_amount总额from freqtrade.persistence import Trade # ... profit Trade.total_open_trades_stakes()源码对is_open True的交易求和stake_amounttrade_model.py L1954。回测 / 超参模式下不受支持的类方法以下类方法在回测 / 超参模式下不受支持NOTE: Not supported in Backtesting仅能在实盘live与模拟盘dry_run中安全调用。get_overall_performance —— 交易对总体表现获取整体表现效果类似于/performanceTelegram 命令。由于它查询的是数据库聚合官方示例会用runmode做运行模式守卫from freqtrade.persistence import Trade # ... if self.config[runmode].value in (live, dry_run): performance Trade.get_overall_performance()示例返回值ETH/BTC 共成交 5 笔总收益率为 1.5%比率 0.015{pair: ETH/BTC, profit: 0.015, count: 5}源码中返回结构实际包含更多字段profit_ratio、profit/profit_pct兼容模式的百分比 ×100 取两位、profit_abs与count按pair分组聚合trade_model.py L2026。get_trading_volume —— 累计成交量基于订单获取累计成交量from freqtrade.persistence import Trade # ... volume Trade.get_trading_volume()源码实现对status closed的订单按Order.cost求和并 inner join 到trades表trade_model.py L2174故同样依赖数据库而无法在回测中运行。Order 对象Order对象代表交易所上的一笔订单或在模拟盘中模拟的订单。一个Order对象始终关联到它所对应的Trade脱离交易上下文讨论订单没有意义——这也是orders作为Trade关系字段挂载、而trade作为订单反向引用存在的原因。关于数据库侧结构orders表通过(ft_pair, order_id)唯一约束保证同对订单不重复外键ft_trade_id指向trades.idtrade_model.py L77-L88。ft_order_side只允许buy、sell或stoploss三种取值ft_is_open是订单是否仍挂单的快捷标志status则镜像交易所ccxt原始状态。Order 可用属性订单对象通常挂在交易上。多数属性可能为None因为它们依赖交易所返回的数据。完整字段如下Attribute数据类型说明tradeTrade该订单所属的 Trade 对象。ft_pairstring该订单针对的交易对。ft_is_openboolean订单是否仍未完成。ft_order_sidestring订单方向buy、sell 或 stoploss。ft_cancel_reasonstring订单被取消的原因。ft_order_tagstring自定义订单标签。order_idstring交易所订单 ID。order_typestring订单类型通常为 market、limit 或 stoploss。statusstring状态遵循 ccxt 的 order structure通常为 open、closed、expired、canceled 或 rejected。sidestringbuy 或 sell。pricefloat下单时设定的价格。averagefloat订单实际成交的平均价。amountfloat以基础货币计的订单数量。filledfloat已成交数量基础货币——请改用safe_filled。safe_filledfloat已成交数量基础货币保证不为 None。safe_amountfloat数量为 None 时回退到ft_amount。safe_pricefloat价格依次回退average→price→stop_price→ft_price。safe_placement_pricefloat订单下达时的价格。remainingfloat剩余未成交数量——请改用safe_remaining。safe_remainingfloat剩余数量取交易所值或自行计算。safe_costfloat订单成本保证不为 None。safe_fee_basefloat以基础货币计的手续费保证不为 None。safe_amount_after_feefloat扣除手续费后的数量。costfloat订单成本通常为average * filled在合约交易中取决于交易所可能含或不含杠杆、可能以张数计。stop_pricefloat止损单的触发价非止损单为空。stake_amountfloat该订单使用的 Stake 金额。stake_amount_filledfloat该订单已成交的 Stake 金额。order_datedatetime订单创建时间——请改用order_date_utc。order_date_utcdatetime订单创建时间UTC。order_filled_datedatetime订单成交时间——请改用order_filled_utc。order_filled_utcdatetime订单成交时间UTC。order_update_datedatetime订单最近一次更新时间。safe_* 系列属性的意义交易所返回的数据经常出现字段缺失或为None为了让上层逻辑收益计算、仓位核算稳定运行Order定义了一组safe_*派生属性定义集中在 trade_model.py L130-L187safe_amount self.amount or self.ft_amount当交易所数量缺失时回退到 Freqtrade 本地保存的下单量safe_price按average → price → stop_price → ft_price优先级回退即已成交价优先于挂单价优先于止损触发价优先于本地记录价safe_placement_price不取average只描述下单那一刻的价格safe_filled self.filled if not None else 0.0、safe_remaining缺省时用safe_amount - filled推算、safe_cost/safe_fee_base缺省归零safe_amount_after_fee safe_filled - safe_fee_basestake_amount/stake_amount_filled是用高精度计算器FtPrecise依据amount × price / leverage换算得到的 Stake 货币金额。与交易所ccxt同步的数据流订单对象与交易所的对账通过两个方向的方法完成trade_model.py L197update_from_ccxt_object(order)把 ccxt 返回的订单字典逐字段安全地回填到本地Order并根据status是否落入NON_OPEN_EXCHANGE_STATES即cancelled / canceled / expired / rejected / closed见 constants.py L133-L134来切换ft_is_open同时首次成交时写入order_filled_dateto_ccxt_object(stopPriceNamestopPrice)把本地订单重新组织成 ccxt 兼容字典用于 API 展示、订单修改等场景若订单方向为stoploss会附带stopPrice与ft_order_type。需要注意filled之外的交易所字段可能以None落库这也是为什么文档特别强调多数Order属性可能为 None取决于交易所响应。在策略与外部工具中查阅 Trade 的实用建议运行模式区分实盘 / 模拟盘读数据库Trade.use_db True回测 / 超参读内存LocalTrade。因此面向实盘的分析代码请加runmode守卫回测代码只能写在策略回调内禁止用于populate_*()。优先用*_utc时间与safe_*字段时间比较、跨时区展示、以及订单数据可能缺失的场景下这些派生属性是官方推荐的安全取值方式。需要细粒度订单数据时遍历trade.orders例如自行统计入场成交时间可用select_filled_orders(self.entry_side)date_entry_fill_utc取其中最早的成交时间、date_last_filled_utc取最晚的trade_model.py L510-L533。timeframe是整数入库时由timeframe_to_minutes(self.config[timeframe])转换而来见 freqtradebot.py L1074即数据库中保存的是分钟数而非5m这样的字符串。直接查库如需 SQL 层面浏览trades/orders两表可参考 docs/sql_cheatsheet.md 中的常用查询示例。小结Trade与Order构成了 Freqtrade 所有开平仓逻辑与数据可视化的地基前者承载一笔仓位从哪里来、以什么价格进出、赚了多少后者细粒度记录每一张挂单/成交单的状态与金额。理解它们的数据类型、safe_*语义、运行模式差异数据库 vs 内存以及类方法的能力边界能让你在编写回调、接入外部监控、二次开发数据报表时少走弯路也能更准确地解读机器人日志与 API 输出。【免费下载链接】freqtradeFree, open source crypto trading bot项目地址: https://gitcode.com/GitHub_Trending/fr/freqtrade创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考