期货下单 API

从 localquant.apis 导入，适用于纯 future 账户的真实月合约与连续系列。保证金、手续费和系列归属见期货机制。

真实月合约在竞价、handle_bar或盘中scheduler的普通交易阶段使用；期货分钟没有竞价回调。系列只允许在 handle_bar 下单，不允许在竞价或scheduler下单。盘中路由与日线信号边界见日频或分钟。

共用参数

参数	类型 / 默认	说明
id_or_ins	str | Instrument，必填	已加载月合约或系列，例如 RB2609.SHF、RB.SHF
amount	int，必填	四向接口的非负手数，实际下单传正整数；不是股数、名义金额或保证金金额。系列下单要求数量大于0，否则报错
price_or_style	数值 / MarketOrder / LimitOrder / None，默认 None	原始价格或订单样式，见价格与样式
price / style	float | None / 样式对象或 None，均默认 None	另有这两个价格参数位置，调用时统一使用 price_or_style
close_today	bool，默认 False	仅平仓接口：False按默认今昨仓规则，True只平今仓；按交易日区分

buy_open、sell_open、sell_close、buy_close 的返回规则见四向接口返回值。

注意：不要依赖非整数数量的隐式截断。真实月合约数量为0可能返回None。

buy_open

摘要：开多：BUY + OPEN，增加LONG方向持仓。

buy_open(id_or_ins, amount, price_or_style=None, price=None, style=None)

注意：不自动平空。

sell_open

摘要：开空：SELL + OPEN，增加SHORT方向持仓。

sell_open(id_or_ins, amount, price_or_style=None, price=None, style=None)

注意：不自动平多。

sell_close

摘要：平多：SELL + CLOSE，close_today=True 时为 CLOSE_TODAY。

sell_close(id_or_ins, amount, price_or_style=None, price=None, style=None, close_today=False)

注意：

• 真实月合约默认先平昨仓，超过昨仓部分拆为平今单。系列可跨其归属的多个真实合约拆单，并在每个合约中优先昨仓；不能平其他系列或直接月合约的归属仓位。
• close_today 在 price/style 之后，使用关键字传入：

from localquant.apis import sell_close

# 在 handle_bar 中，且该系列确有至少1手可平今多仓时：
result = sell_close("RB.SHF", 1, close_today=True)

buy_close

摘要：平空：BUY + CLOSE，close_today=True 时只平SHORT方向今仓。

buy_close(id_or_ins, amount, price_or_style=None, price=None, style=None, close_today=False)

注意：拆单规则同 sell_close。

四向接口返回值

返回：Order | list[Order] | None — 根据本次实际提交决定：

情况	返回
提交一张订单	Order，仍须检查状态及成交量
拆分后提交多张订单	list[Order]；可能只通过其中部分订单的校验
没有订单通过提交校验	空列表 []
真实月合约数量为0、无有效报价等创建失败	可能为 None

注意：

• 直接月合约平仓量不足会记录原因并返回空列表；系列可平归属不足抛出异常。系列与直接月合约混用受归属互斥规则限制。
• 返回列表不表示各腿同时成交。逐张读取 filled_quantity/status/message，以实际持仓确认是否完成；行情、费用或参数错误仍可抛异常。

order

摘要：按本次净手数变化下单。

order(id_or_ins, quantity, price_or_style=None, price=None, style=None)

参数	类型 / 默认	说明
quantity	int，必填	本次净手数变化。正数先平空、再开多；负数先平多、再开空

共用标的和价格参数同上。

返回：list[Order | list[Order] | None] — quantity为0返回 []；其中各开平请求又可能返回Order、列表或None，因此结果可能嵌套。

注意：例如已有2手空仓，order(code, 3)请求平空2手并开多1手，不是额外开多3手。

order_to

摘要：按目标净手数调整持仓。

order_to(id_or_ins, quantity, price_or_style=None, price=None, style=None)

参数	类型 / 默认	说明
quantity	int，必填	目标净手数：正数净多、负数净空、0净零；先用目标减当前净手数，再执行order的开平规则

返回：list[Order | list[Order] | None] — 已经达到净目标时返回 []，其他返回形状同order。

注意：

• 净目标不是双边清仓指令：多2手、空2手的净手数为0，此时order_to(code, 0)可不提交订单，但仍持有双边风险。要清空两边，应分别按各方向可平量调用sell_close和buy_close。
• 反转不是原子操作，平仓失败后开仓腿仍可能被提交。要求“先平完再开反向仓”时，显式平仓、确认实际原方向数量为0后再开仓；next_bar模式应等后续成交，不能在同一回调假定完成。

读取拆单结果

from localquant.apis import buy_open

def iter_orders(value):
    if value is None:
        return
    if isinstance(value, list):
        for child in value:
            yield from iter_orders(child)
    else:
        yield value

# 在handle_bar中调用。该函数只展开返回值，不代表等待成交。
result = buy_open("RB.SHF", 1)
for order in iter_orders(result):
    real_contract = order.order_book_id
    filled = order.filled_quantity

get_open_orders() 查询活动订单，cancel_order(order) 撤销余单；对象字段与日终有效期见订单与成交。真实仓位和系列归属视图见账户与持仓。