交易API

取到数据、算出信号后，就到了下单环节。米筐为股票和期货分别提供了语义化的下单接口：股票用「股数/金额/比例/目标仓位」系列，期货用「买开/卖开/买平/卖平」四方向。本章梳理这两组 API 以及持仓查询和核心对象。

一、股票下单

股票和场内基金共享以下六个接口，都支持市价单 MarketOrder() 和限价单 LimitOrder(price)：

函数	含义	示例
`order_shares(id, amount, style)`	按股数下单（正买负卖）	`order_shares('000001.XSHE', 2000)` 买 2000 股
`order_lots(id, amount, style)`	按手数下单	`order_lots('000001.XSHE', 20)` 买 20 手
`order_value(id, cash, style)`	按金额下单	`order_value('000001.XSHE', 10000)` 买 1 万元
`order_percent(id, pct, style)`	按组合比例下单	`order_percent('000001.XSHE', 0.5)` 占组合 50%
`order_target_value(id, target, style)`	调到目标市值	`order_target_value('000001.XSHE', 10000)`
`order_target_percent(id, pct, style)`	调到目标比例	`order_target_percent('000001.XSHE', 0.15)`

def handle_bar(context, bar_dict):
    s = context.s1
    # 买入 2000 股，市价单
    order_shares(s, 2000)
    # 限价单买入，价格 10 元
    order_shares(s, 1000, style=LimitOrder(10))
    # 把仓位调到组合的 30%
    order_target_percent(s, 0.3)

要点：

amount 正数买入、负数卖出，系统自动按一手股数（A 股 100 股）向下取整。
order_percent / order_target_percent 的 pct 是占投资组合总价值的比例。
order_value / order_percent / order_target_* 系列暂不支持卖空（需有持仓才能卖出）。

二、期货下单

期货采用双向交易，用四个方向函数，参数为合约、手数、可选价格/订单类型：

函数	含义
`buy_open(id, amount, price=None)`	买入开仓（做多）
`sell_close(id, amount, close_today=False)`	卖出平仓（平多）
`sell_open(id, amount, price=None)`	卖出开仓（做空）
`buy_close(id, amount, close_today=False)`	买入平仓（平空）

# 限价单开仓买入 2 张 AG1607
buy_open('AG1607', amount=2, price=3500)
# 市价单平仓 2 张 IF1603 空头
buy_close('IF1603', 2)

price 填写则为限价单，不填为市价单。
close_today=True 表示平今仓（上期所部分品种需显式指定）。
平仓默认按先进先出规则，若持仓含昨仓和今仓，可能返回多个订单。

三、撤单与订单查询

# 撤销指定订单
cancel_order(order)
# 获取所有未成交且未撤的活跃订单
open_orders = get_open_orders()

在分钟回测中，撮合方式影响撤单行为：若选「下一开盘价」撮合，handle_bar 内发单后立刻 cancel_order 一定能撤成功；若选「当前收盘价」则下单后立即成交，撤单可能失败。

四、持仓查询

函数	含义
`get_position(id, direction)`	查单只合约某方向持仓
`get_positions()`	查全部持仓列表

# 查股票多头持仓
pos = get_position('000001.XSHE', POSITION_DIRECTION.LONG)
logger.info('持仓量 %d，市值 %.2f' % (pos.quantity, pos.market_value))

# 遍历所有持仓
for pos in get_positions():
    logger.info(pos.order_book_id, pos.quantity)

即使未持仓，get_position 也会返回对象，只是数量和市值为 0。

五、行权（期权/可转债）

exercise(id_or_ins, amount, convert=False)

对含权合约行权。期权行权只填前两个参数；可转债转股设 convert=True，回售设 convert=False：

exercise('M1905C2350', 1)                # 行权 1 张豆粕期权
exercise('132003.XSHG', 100, convert=True)  # 可转债转股

六、核心对象

下单和持仓查询都会返回对象，常用属性：

Order 对象

属性	含义
`order_book_id`	合约代码
`side`	买卖方向（`SIDE.BUY` / `SIDE.SELL`）
`quantity` / `filled_quantity`	委托数量 / 已成交数量
`avg_price`	成交均价
`status`	订单状态（`FILLED` 全成、`CANCELLED` 已撤、`REJECTED` 拒单）
`message`	拒单原因

Portfolio 对象（`context.portfolio`）

属性	含义
`total_value`	总权益
`cash`	可用现金
`positions`	持仓字典（以 `order_book_id` 为键）
`total_returns`	累计收益率
`daily_returns`	当日收益率

Position 对象

属性	含义
`quantity`	当前持仓数量
`market_value`	实时市值
`last_price`	最新价
`position_pnl` / `trading_pnl`	持仓盈亏 / 交易盈亏

期货持仓还有 old_quantity（昨仓）、margin（保证金）、direction（多空方向）。

小结

股票下单六件套：order_shares/lots/value/percent/target_value/target_percent。
期货四方向：buy_open/sell_close/sell_open/buy_close，平今设 close_today=True。
get_position(s) 查持仓，cancel_order / get_open_orders 管订单。
Order / Portfolio / Position 三大对象承载交易的全量状态。

下单逻辑跑通后，下一步配置回测参数、理解风险指标：回测与模拟交易。