Papertrading 模拟交易 API

由small_q创建，最终由small_q更新于2025-12-15 08:14 被浏览 4 用户

1 模块概述

本模块提供模拟交易策略管理功能，包括策略列表查询、策略详情获取、绩效数据、交易订单、持仓信息等。支持本地/云端代码无缝切换。

主要功能：

• 获取个人策略和社区分享策略列表
• 获取策略详情对象（支持管理员特权）
• 查询策略绩效、订单、持仓、计划订单等数据

权限说明：

• 个人策略：仅创建者可访问
• 分享策略：所有用户可查看列表
• 管理员特权：特定空间管理员（拥有 community 权限）可访问该空间所有策略详情

2 API 介绍

2.1获取策略列表

方法名：papertrading.list()

功能：获取用户自己创建的模拟交易策略列表

参数：

• constraints: Union[Dict[str, Any], None]，非必填，查询约束条件，默认为 None
• order_by: Union[List[str], None]，非必填，排序字段列表，默认为 None
• include_fields: Union[List[str], None]，非必填，包含字段列表，默认为 None
• page: int，非必填，页码，默认为 1
• size: int，非必填，每页数量，默认为 1000
• order_by 使用 - 前缀表示降序，如 ["-created_at", "strategy_name"]
• include_fields 用于只返回指定字段，减少数据传输量

返回字段：

• id: 策略ID
• strategy_name: 策略名称
• status: 策略状态
• created_at: 创建时间
• updated_at: 更新时间
• space_id: 空间ID
• account_id: 账户ID（dict格式）
• first_trading_day: 首个交易日
• benchmark_instrument: 基准代码

注意：此方法只返回用户自己创建的策略，不包含社区分享策略

2.2 获取分享策略列表

方法名：papertrading.list_shared()

功能：获取社区分享的模拟交易策略列表

参数：

• space_id: Union[str, None]，非必填，空间ID，默认为 None
• constraints: Union[Dict[str, Any], None]，非必填，查询约束条件，默认为 None
• order_by: Union[List[str], None]，非必填，排序字段列表，默认为 None
• include_fields: Union[List[str], None]，非必填，包含字段列表，默认为 None
• isrelative: bool，非必填，是否相对收益，默认为 False
• benchmark: str，非必填，基准线代码，默认为 "000300.SH"
• page: int，非必填，页码，默认为 1
• size: int，非必填，每页数量，默认为 20

参数说明：

• space_id: 传入特定空间ID可查询该空间的分享策略，默认查询主空间
• isrelative:
  • False: 返回绝对收益率
  • True: 返回相对于 benchmark 的收益率
• benchmark 常用代码：
  • 000300.SH: 沪深300
  • 000905.SH: 中证500
  • 000852.SH: 中证1000
  • 000001.SH: 上证指数
• constraints、order_by、include_fields: 用法同 list() 方法

返回：Dict[str, Any]

• items: list，策略列表
• count: int，总数量
• page: int，当前页码
• size: int，每页数量
• total: int，总页数

返回字段：

• id: 策略ID
• strategy_id: 策略ID
• strategy_name: 策略名称
• strategy_desc: 策略描述
• strategy_article: 策略文章
• labels: 策略标签
• datasource: 使用的数据源列表
• creator: 创建者ID
• created_at: 创建时间
• updated_at: 更新时间
• first_trading_day: 首个交易日
• trading_day: 最新交易日
• cumulative_return: 累计收益率
• annualized_return: 年化收益率
• max_drawdown: 最大回撤
• sharpe: 夏普比率
• win_percent: 胜率
• today_return: 今日收益率
• week_return: 近一周收益率
• month_return: 近一月收益率
• three_month_return: 近三月收益率
• six_month_return: 近六月收益率
• year_return: 近一年收益率
• collection_count: 收藏数
• is_featured: 是否精选
• rank: 排序值

2.3 获取策略对象

方法名：papertrading.get()

功能：获取指定策略对象，用于访问策略详情数据

参数：

• strategy_id: str，必填，策略 ID

返回：Strategy 对象

权限说明：

• 策略创建者可以访问自己的策略
• 特定空间的管理员（拥有 community 权限）可以访问该空间所有策略

注意：

• 如果策略不存在或无权访问，将抛出 ValueError 异常
• 管理员权限通过 SPACE_ADMIN_PRIVILEGE_ENABLED_SPACES 配置控制

2.4 Strategy 类

类名：Strategy

功能：策略对象，封装策略基本信息并提供访问策略详情数据的方法

初始化：不能直接实例化，需通过 papertrading.get(strategy_id) 获取

属性：

strategy_info: dict，策略基本信息字典，包含：

• id: 策略ID
• strategy_name: 策略名称
• account_id: 账户ID（dict格式）
• space_id: 空间ID
• creator: 创建者ID
• created_at: 创建时间
• updated_at: 更新时间
• first_trading_day: 首个交易日
• benchmark_instrument: 基准代码

方法：见下

2.4.1 获取策略绩效数据

方法名：Strategy.get_performances()

功能：获取策略的历史绩效数据

参数：

• fields: Union[List[str], None]，非必填，绩效字段列表，默认为 None

说明：默认返回字段包括: trading_day, today_return, max_drawdown, annualized_return, risk_indicator, win_percent, cumulative_return, benchmark, total_market_value, balance, month_return, week_return, three_month_return, six_month_return, created_at, portfolio_value

返回：list，绩效数据列表（每个元素为一个列表，对应 fields 顺序）

返回字段：

• trading_day: 交易日
• today_return: 当日收益率
• cumulative_return: 累计收益率
• annualized_return: 年化收益率
• max_drawdown: 最大回撤
• win_percent: 胜率
• risk_indicator: 风险指标（dict），包含：
  • sharpe: 夏普比率
  • sortino: 索提诺比率
  • calmar: 卡玛比率
  • information_ratio: 信息比率
• benchmark: 基准数据（dict或None）
• total_market_value: 持仓市值
• balance: 当前现金
• portfolio_value: 总资产
• week_return: 近一周收益率
• month_return: 近一月收益率
• three_month_return: 近三月收益率
• six_month_return: 近六月收益率
• created_at: 创建时间

2.4.2 获取交易订单

方法名：Strategy.get_orders()

功能：获取策略的交易订单记录

参数：

• constraints: Union[Dict[str, Any], None]，非必填，查询条件字典，默认为 None
• order_by: Union[List[str], None]，非必填，排序字段列表，默认为 None
• include_fields: Union[List[str], None]，非必填，包含字段列表，默认为 None
• page: int，非必填，页码，默认为 1
• size: int，非必填，每页数量，默认为 100

返回：dict

• items: list，订单列表
• count: int，总数量
• page: int，当前页码
• size: int，每页数量
• total: int，总页数

返回字段：

• id: 订单ID
• strategy_id: 策略ID
• account_type: 账户类型
• account_id: 账户ID
• trading_day: 交易日
• exchange: 交易所
• instrument: 代码
• name: 代码名称
• direction: 买卖方向（1=买入，2=卖出）
• offset_flag: 开平标志（0=开仓，1=平仓，2=平今）
• order_qty: 委托数量
• order_price: 委托价格
• average_price: 成交均价
• filled_qty: 成交数量
• order_status: 委托状态
  • 0: 未成交
  • 1: 部分成交
  • 2: 全部成交
  • 3: 部分撤单
  • 4: 全部撤单
  • 5: 已拒绝
• status_msg: 状态信息
• order_type: 委托类型（0=限价单，U=市价单）
• order_property: 委托属性
• hedge_flag: 投保标记（1=投机）
• order_dt: 委托时间
• filled_dt: 成交时间
• cancel_dt: 撤单时间
• order_key: 本地订单标识
• order_sysid: 交易所报单编号
• entrust_no: 柜台委托编号
• algo_order_id: 算法单号
• commission: 交易费用
• realized_pnl: 平仓盈亏

2.4.3 获取计划订单

方法名：Strategy.get_planned_orders()

功能：获取策略的计划交易订单（交易信号）

参数：

• constraints: Union[Dict[str, Any], None]，非必填，查询条件字典，默认为 None
• order_by: Union[List[str], None]，非必填，排序字段列表，默认为 None
• include_fields: Union[List[str], None]，非必填，包含字段列表，默认为 None
• page: int，非必填，页码，默认为 1
• size: int，非必填，每页数量，默认为 100

返回：dict

• items: list，计划订单列表
• count: int，总数量
• page: int，当前页码
• size: int，每页数量
• total: int，总页数

返回字段：

• planned_order_id: 计划订单ID
• strategy_id: 策略ID
• account_type: 账户类型
• account_id: 账户ID
• trading_day: 交易日
• order_dt: 待下单时间
• exchange: 交易所
• instrument: 代码
• name: 代码名称
• direction: 买卖方向（1=买入，2=卖出）
• offset_flag: 开平标志（0=开仓，1=平仓，2=平今）
• original_order_qty: 原始委托数量
• order_qty: 委托数量
• order_price: 委托价格
• order_type: 委托类型（0=限价，U=市价）
• order_status: 委托状态
  • 0: 待执行
  • 1: 执行中
  • 2: 已执行
  • 3: 已取消
• status_msg: 状态描述
• order_params: 下单条件参数（dict）
• order_placed_dt: 实际发单时间
• order_key: 本地订单标识
• entrust_no: 委托号
• algo_order_id: 算法单号
• stop_loss_price: 止损价格
• stop_profit_price: 止盈价格
• created_at: 创建时间

字段说明：

• original_order_qty: 策略生成的原始委托数量
• order_qty: 实际执行的委托数量（可能因资金、风控等原因调整）

2.4.4 获取持仓信息

方法名：Strategy.get_positions()

功能：获取策略的持仓数据

参数：

• constraints: Union[Dict[str, Any], None]，非必填，查询条件字典，默认为 None
• order_by: Union[List[str], None]，非必填，排序字段列表，默认为 None
• include_fields: Union[List[str], None]，非必填，包含字段列表，默认为 None
• page: int，非必填，页码，默认为 1
• size: int，非必填，每页数量，默认为 100

返回：dict

• items: list，持仓列表
• count: int，总数量
• page: int，当前页码
• size: int，每页数量
• total: int，总页数

返回字段：

• id: 持仓记录ID
• account_type: 账户类型
• account_id: 账户ID
• trading_day: 交易日
• exchange: 交易所
• instrument: 代码
• name: 代码名称
• posi_direction: 持仓方向（1=多头，2=空头）
• current_qty: 持仓数量
• available_qty: 可用数量
• today_qty: 今日持仓数量
• today_available_qty: 今日可用数量
• cost_price: 持仓成本价格
• last_price: 持仓最新价
• market_value: 持仓市值
• margin: 保证金占用
• position_pnl: 盈亏金额
• hedge_flag: 投保标记（1=投机）
• sum_buy_value: 累计买入金额
• sum_sell_value: 累计卖出金额
• commission: 累计交易费用
• dividend_qty: 当日分红数量
• dividend_cash: 当日分红金额
• open_date: 开仓日期
• open_price: 开仓价格
• settlement_price: 结算价
• profit_ratio: 盈亏比率
• initial_qty: 日初持仓数量
• hold_days: 持有天数
• created_at: 创建时间
• updated_at: 更新时间

字段说明：

• current_qty: 当前总持仓数量
• available_qty: 可卖数量（股票T+1：current_qty - today_qty；期货T+0：current_qty）
• today_qty: 今日买入数量（T+1制度下不可卖）
• today_available_qty: 今日可用数量（期货可用）
• sum_buy_value / sum_sell_value / commission: 从开仓至今的累计值

\