账户与持仓 API

本页定义运行中的对象；保存后的DataFrame见结果参考。get_position/get_positions/deposit/withdraw从 localquant.apis 导入，context由框架传入回调。

账户及持仓查询可在init和日常回调中使用；行情估值与交易权限仍取决于回调阶段，见生命周期。

context

框架属性用于读取，策略可通过 context.xxx 保存自己的状态；不要覆盖下面的内置名称。

属性	类型	说明
now	datetime.datetime	当前自然时间
trading_date	datetime.date	当前交易日；夜盘可能与now.date()不同
universe	set[str]	当前订阅池，通过订阅API修改
config	配置对象	生效配置，使用属性访问，如context.config.base.frequency
portfolio	Portfolio	整个策略组合
stock_account / future_account	Account	已配置的对应账户；未启用该账户时不能访问

账户与持仓

Portfolio

通常通过 context.portfolio 读取。以下金额为元、比例为小数，数值属性只读：

属性	类型	说明
accounts	账户键到Account的字典	使用大写键STOCK/FUTURE，例如portfolio.accounts["STOCK"]
cash / frozen_cash	float	可用现金 / 活动订单冻结资金
total_value	float	总权益，包含应收及未结算损益等适用项目
market_value	float	股票基金市值；期货带方向净名义敞口
units	float	组合份额，出入金会改变份额
unit_net_value / static_unit_net_value	float	当前单位净值 / 前一结算单位净值
daily_pnl / daily_returns	float	当日金额盈亏 / 净值日收益率，定义见出入金
total_returns / annualized_returns	float	当前累计收益 / 年化收益；正式绩效取结算后summary
transaction_cost	float	当日交易费用，累计费用取每日结果求和
positions	代码到持仓代理的映射	与get_position返回的方向持仓对象不同，见后文

期货portfolio没有margin属性，保证金读取 context.future_account.margin。净名义敞口不能与现金相加当作权益；total_value直接表示权益。

Account

股票与基金共用stock账户；期货使用future账户。两个对象的公共属性：

属性	类型	说明
cash / frozen_cash	float	可用现金 / 活动订单冻结资金
total_cash	float	cash+frozen_cash；期货已扣持仓保证金，不是包含保证金的资金余额
total_value / market_value	float	总权益 / 股票市值或期货净名义敞口
transaction_cost / daily_pnl	float	当日交易费用 / 排除外部资金流的当日金额盈亏

期货账户另有 margin/buy_margin/sell_margin，分别为多空保证金合计/多头保证金/空头保证金，均为float元；position_pnl/trading_pnl为昨仓价格变动盈亏/当日交易盈亏，不能替代包含全部税费与结算影响的daily_pnl。

账户与持仓对象随成交、估值和结算变化；如果需要保存某时刻的状态，复制字段值，不只保存对象引用。估值刷新时点见生命周期。

get_position

摘要：查询指定标的和方向的持仓对象。

get_position(order_book_id, direction=POSITION_DIRECTION.LONG)

参数	类型 / 默认	说明
order_book_id	str，必填	已加载且当前有效的代码；可传期货系列；标的无效、未上市等会失败
direction	POSITION_DIRECTION，默认LONG	LONG为多头，SHORT为空头；股票基金只使用LONG

返回：StockPosition | FuturePosition | SeriesPosition — 各类对象字段分别见下面三节：

情况	返回
股票基金	StockPosition
期货月合约	FuturePosition
期货系列	SeriesPosition，期货系列归属视图

注意：

• 未持有的有效标的返回零数量对象，不返回None。
• 该示例放在期货策略回调内；净数量为0不代表双边仓位均为0。

from localquant.apis import POSITION_DIRECTION, get_position

long_pos = get_position("RB.SHF")
short_pos = get_position("RB.SHF", POSITION_DIRECTION.SHORT)
net_quantity = long_pos.quantity - short_pos.quantity

get_positions

摘要：查询持仓对象集合。

get_positions()

返回：list[Position] — 持仓对象集合。期货按真实月合约与方向返回，不返回系列归属视图，避免重复统计。

注意：集合中的对象可能仍为零数量，应以 position.quantity > 0筛选实际仓位；没有实际仓位时也不应只用列表长度判断空仓。

出入金

摘要：deposit增加资金，withdraw减少资金。

deposit(account_type, amount, receiving_days=0)
withdraw(account_type, amount)

参数	类型 / 默认	说明
account_type	str，必填	已配置账户，使用大写STOCK或FUTURE
amount	int | float，必填	正数元；deposit增加资金，withdraw减少资金
receiving_days	int，默认0，仅deposit	0立即到账；正整数表示在第n个后续交易日盘前到账，日历须覆盖该日期

返回：None — 两个接口均无返回值。

时机：可在盘前、竞价、handle_bar、盘后及scheduler回调使用，不能在init调用。

注意：

• 出金须有足够可用现金。
• 延迟入金在提交时已计入应收权益并增加组合份额，到账时转为可用现金。出入金改变权益与份额，不直接改变单位净值或构成投资收益。
• 组合与账户daily_pnl为当前权益减日初权益，再减当日净外部入金；费用、税费和结算损益均在实际入账后反映。组合daily_returns为当前单位净值相对前日结算净值的变动，不等同于有现金流时的总权益增长率。

股票基金持仓

get_position返回的方向对象提供以下只读字段。数量为股/份，金额为元：

属性	类型	说明
order_book_id / direction	str / POSITION_DIRECTION	代码 / LONG方向
quantity	int | float	总数量
closable	int | float	当前可平数量，扣除T+1限制与活动卖单冻结数量
avg_price / last_price	float	当前持仓成本 / 当前估值价格
market_value	float	当前数量对应市值
transaction_cost	float	当日该方向持仓承担的费用

portfolio.positions[code]返回持仓代理，常用字段为quantity、sellable、avg_price、last_price、market_value。代理的sellable对应可卖数量；get_position的结果使用closable，没有sellable属性。不要通过修改这些对象调整持仓，应提交订单。

期货真实合约持仓

get_position以LONG或SHORT分别返回方向对象；每个方向的数量都是非负手数。

属性	类型	说明
order_book_id / direction	str / POSITION_DIRECTION	真实代码 / 方向
quantity/old_quantity/today_quantity	int	总手数 / 昨仓 / 今仓
closable/today_closable	int	当前可平 / 可平今仓，扣除挂单冻结量
avg_price/last_price	float	当前成本 / 估值价；avg_price每日结算重置
contract_multiplier/margin_rate	float	乘数 / 已含base.margin_multiplier的该方向保证金率
margin/market_value	float元	该方向保证金 / 非负名义敞口；空头单方向市值也不是负数
pnl	float元	当前价相对当前avg_price的未结算盈亏，不是累计交易收益
position_pnl/trading_pnl	float元	昨仓相对前结算价的盈亏 / 当日成交相对当前估值价的盈亏
transaction_cost	float元	当日该方向持仓承担的交易费用

期货系列持仓

get_position(series, direction)返回只读归属视图。它与真实合约对象不是同一类，不提供独立累计收益、pnl或margin_rate。

属性	类型	说明
order_book_id/direction/instrument	str / POSITION_DIRECTION / Instrument	系列代码 / 方向 / 系列合约信息
contract_multiplier	float	合约乘数
quantity/old_quantity/today_quantity	int	同系列同方向所有真实合约的手数合计
closable/today_closable	int	本系列当前可平 / 可平今仓合计
avg_price	float	尚未平掉的归属仓位开仓成本加权
margin/market_value	float元	按本系列占真实持仓的数量分配的保证金 / 非负名义敞口

系列avg_price不随账户每日结算重置，但移仓平旧开新后会更新，不保存跨合约的最初入场基准。跨换月止损等策略状态应自行维护。

portfolio.positions[series]提供代理：buy_quantity/sell_quantity为两方向手数；buy_margin/sell_margin/margin为多头/空头/合计保证金；buy_avg_open_price/sell_avg_open_price为归属成本；long/short为两个方向视图。

遍历portfolio.positions或get_positions只返回真实月合约，系列视图不能再加到总持仓中。订单代码不等于系列身份；同合约多系列归属与直接交易限制见期货机制。

账户变化示例

期货初始权益 100,000 元，开多 1 手，价格 3500、乘数 10、保证金率 10%、开仓手续费 3.5 元。零滑点、无其他仓位或挂单时：权益 99,996.5 元，保证金 3500 元，可用现金 96,496.5 元。

当日结算价为 3520，价格盈亏 200 元，结算后权益 100,196.5 元，保证金 3520 元，可用现金 96,676.5 元，真实持仓 avg_price 重置为 3520。不能把 35,200 元名义市值加到现金中再算一次权益。