Execution 对象

Execution 对象描述一条真实成交。它不是订单对象，也不是订单状态对象，而是“这一笔成交具体在什么时候、什么交易所、什么价格、成交了多少”的明细。

execDetails(reqId, contract, execution) 回调里会同时给你 Contract 和 Execution。Contract 说明成交的是哪个合约，Execution 说明成交本身。

字段说明

字段	中文说明
`execId`	成交编号，用于成交去重，也用于关联佣金费用报告。
`time`	成交时间。不同账户地区和 TWS 设置下，字符串格式可能略有差异，保存时建议同时保留原始字符串。
`acctNumber`	账户号。多账户或顾问账户下尤其重要。
`exchange`	实际成交交易所。股票使用 SMART 下单时，成交交易所可能不是 `SMART`。
`side`	买卖方向，常见值为 `BOT` 或 `SLD`。
`shares`	本笔成交数量。Python API 中常以 Decimal 形式出现，保存前可按数据库类型转换。
`price`	本笔成交价格。
`permId`	IBKR 永久订单编号，适合跨客户端追踪同一订单。
`clientId`	下单客户端编号。不同 API 客户端同时连接时，用它区分订单来源。
`orderId`	API 客户端订单编号。它和 `clientId` 组合后更有意义。
`liquidation`	是否与强平相关。普通成交通常为 0。
`cumQty`	截至本笔成交后的累计成交数量。
`avgPrice`	截至本笔成交后的平均成交价。
`orderRef`	下单时自定义的订单引用字段，可用来标记策略、模块或业务单号。
`evRule`	与波动率、事件相关的规则字段，普通股票订单常为空。
`evMultiplier`	与 `evRule` 配套的倍率字段，普通场景通常不用。
`modelCode`	投资组合模型代码，顾问或组合模型账户可能用到。
`lastLiquidity`	流动性标记，用来区分增加流动性、移除流动性等执行属性。
`pendingPriceRevision`	成交价格是否存在后续修订可能。普通场景通常为 False。

读取示例

def execDetails(self, reqId, contract, execution) -> None:
    row = {
        "request_id": reqId,
        "symbol": contract.symbol,
        "security_type": contract.secType,
        "currency": contract.currency,
        "exec_id": execution.execId,
        "time": execution.time,
        "account": execution.acctNumber,
        "exchange": execution.exchange,
        "side": execution.side,
        "shares": float(execution.shares),
        "price": execution.price,
        "perm_id": execution.permId,
        "client_id": execution.clientId,
        "order_id": execution.orderId,
        "cumulative_quantity": float(execution.cumQty),
        "average_price": execution.avgPrice,
        "order_ref": execution.orderRef,
        "last_liquidity": execution.lastLiquidity,
    }

    save_execution(row)

和订单状态的区别

orderStatus() 可能告诉你 filled=1，但它不是成交流水。成交流水需要 Execution，费用需要 commissionAndFeesReport()。

如果你在做交易系统，建议把订单表和成交表分开设计。

保存注意事项

不要把 price 和 avgPrice 混用。price 是本笔成交价格，avgPrice 是累计平均成交价。
不要只保存 symbol。股票同名、期权、期货、不同交易所和不同币种都可能造成歧义，关键记录建议保存 conId。
side 的返回值通常不是 BUY / SELL，而是 BOT / SLD。展示给中文用户时可以再映射为“买入 / 卖出”。
shares、cumQty 在新版 Python API 里可能是 Decimal，写入 JSON 或数据库前要显式转换。