数据类型与字段 · 易行量化

单位、缺失值和时间含义都是接口的一部分。交易视图字段未知时为 None，行情数值初始为 NaN；不要把未知值当作 0。

Quote

合约行情快照；通过观察句柄的 data() 获取，不随后续更新改变。

Attributes: symbol: 合约代码，如 SHFE.rb2610 或 DCE.a2611-C-3700。 trading_day: 交易日，格式 YYYYMMDD。 timestamp: 行情时间，Unix 毫秒。 open: 开盘价。 highest: 最高价。 lowest: 最低价。 last_price: 最新价。 pre_settlement: 昨结算价。 pre_close: 昨收盘价。 upper_limit: 涨停价。 lower_limit: 跌停价。 volume: 成交量。 turnover: 成交额。 open_interest: 持仓量。 bids: 买盘档位，每档为（价格，数量）。 asks: 卖盘档位，每档为（价格，数量）。

字段	类型	含义
`symbol`	`str`	合约代码，如 SHFE.rb2610 或 DCE.a2611-C-3700。
`trading_day`	`str`	交易日，格式 YYYYMMDD。
`timestamp`	`int`	行情时间，Unix 毫秒。
`open`	`float`	开盘价。
`highest`	`float`	最高价。
`lowest`	`float`	最低价。
`last_price`	`float`	最新价。
`pre_settlement`	`float`	昨结算价。
`pre_close`	`float`	昨收盘价。
`upper_limit`	`float`	涨停价。
`lower_limit`	`float`	跌停价。
`volume`	`float`	成交量。
`turnover`	`float`	成交额。
`open_interest`	`float`	持仓量。
`bids`	`list`	买盘档位，每档为（价格，数量）。
`asks`	`list`	卖盘档位，每档为（价格，数量）。

初始 symbol 由订阅决定，trading_day=""，timestamp=0，数值字段为 NaN，盘口为空列表。对象字段只读，快照不随后续更新变化。盘口不保证固定档数。

ExError

SDK 数据或交易服务异常，status 为可选的响应状态码。

ExError(message: str, *, status: int | None = None)

继承 Exception；str(error) 为可供业务读取的提示，error.status 为可选 HTTP 状态码。内部重新包装异常时 status 可能为 None，不能只依赖此字段分类所有故障。

CtpAccount

CTP 直连账户配置，交易凭据不会发送至行情服务。

Args: broker_id: 期货公司代码。 user_id: 资金账号。 password: 交易密码。 front_url: 交易前置地址，格式为 tcp://地址:端口。 app_id: 期货公司提供的客户端标识。 auth_code: 期货公司提供的客户端授权码。

字段	类型	含义
`broker_id`	`str`	期货公司代码。
`user_id`	`str`	资金账号。
`password`	`str`	交易密码。
`front_url`	`str`	交易前置地址，格式为 tcp://地址:端口。
`app_id`	`str`	期货公司提供的客户端标识。
`auth_code`	`str`	期货公司提供的客户端授权码。

全部参数必填，front_url 必须以 tcp:// 开头。password/auth_code 不出现在默认 repr 中；仍不要输出整个配置。校验失败抛 ValueError。

Account

只读资金快照；金额单位为人民币元，未知字段为 None。

金额仅由完整柜台查询更新，不根据行情或成交估算；交易日来自登录回报。

字段	类型	含义
`account_id`	`str \| None`	资金账号。
`trading_day`	`str \| None`	交易日，格式 YYYYMMDD。
`balance`	`float \| None`	账户权益。
`available`	`float \| None`	可用资金。
`margin`	`float \| None`	已占用保证金。
`frozen_margin`	`float \| None`	冻结保证金。
`commission`	`float \| None`	当日累计实际手续费。
`frozen_commission`	`float \| None`	冻结手续费。
`close_profit`	`float \| None`	当日平仓盈亏。
`position_profit`	`float \| None`	持仓盈亏。
`deposit`	`float \| None`	当日入金。
`withdraw`	`float \| None`	当日出金。
`updated_at`	`int \| None`	最近一次完整查询完成的本地时间，Unix 毫秒。

Position

只读持仓快照；数量单位为手。

登录查询建立基线，之后根据真实成交本地更新；未知数量为 None。

字段	类型	含义
`symbol`	`str`	合约代码，如 SHFE.rb2610。
`pos_long`	`int \| None`	多头持仓。
`pos_short`	`int \| None`	空头持仓。
`pos_long_today`	`int \| None`	剩余多头今仓。
`pos_short_today`	`int \| None`	剩余空头今仓。
`available_long`	`int \| None`	本地参考可平多头手数：多头持仓减已知有效卖出平仓委托的冻结量；最终由柜台校验。
`available_short`	`int \| None`	本地参考可平空头手数：空头持仓减已知有效买入平仓委托的冻结量；最终由柜台校验。

Order

只读订单快照；断线后观察句柄保留最后一次已提交的数据。

字段	类型	含义
`order_id`	`str`	FrontID:SessionID:OrderRef 格式的本地订单标识。
`order_sys_id`	`str \| None`	CTP 返回的交易所订单号 OrderSysID，尚未收到时为 None。
`symbol`	`str`	合约代码。
`direction`	`str \| None`	BUY 买入，SELL 卖出。
`offset`	`str \| None`	实际委托开平标志：OPEN、CLOSE、CLOSE_TODAY 或 CLOSE_YESTERDAY。
`limit_price`	`float \| None`	委托限价。
`volume_original`	`int \| None`	原始委托数量，单位为手。
`volume_traded`	`int \| None`	已成交数量，单位为手。
`volume_left`	`int \| None`	未成交数量；撤单结束后仍可大于零。
`status`	`Literal['PENDING', 'ALIVE', 'FILLED', 'CANCELLED', 'REJECTED'] \| None`	待回报、尚未确认终态、全部成交、未全成且不再排队、提交失败或被拒；未知时为 None。
`status_msg`	`str \| None`	最近一次订单状态说明。
`cancel_pending`	`bool`	撤单请求待发送或等待柜台结果时为 True。
`cancel_error`	`str \| None`	撤单失败原因；没有失败时为 None。
`insert_time`	`int \| None`	委托时间，Unix 毫秒。

status 允许 PENDING、ALIVE、FILLED、CANCELLED、REJECTED。CANCELLED 不代表剩余数量为零；cancel_pending / cancel_error 反映撤单过程，不是新的成交。

Trade

只读真实成交快照，不包含估算手续费；断线后保留最后一次已提交的数据。

字段	类型	含义
`trade_id`	`str`	CTP 返回的原始成交号 TradeID。
`order_sys_id`	`str`	CTP 返回的交易所订单号 OrderSysID。
`symbol`	`str`	合约代码。
`direction`	`str \| None`	BUY 买入，SELL 卖出。
`offset`	`str \| None`	OPEN 开仓，CLOSE 普通平仓，CLOSE_TODAY 平今，CLOSE_YESTERDAY 平昨。
`price`	`float \| None`	实际成交价格。
`volume`	`int \| None`	实际成交数量，单位为手。
`trade_time`	`int \| None`	成交时间，Unix 毫秒。

trade_id 为原始 CTP TradeID；通过 order_sys_id 关联 Order.order_sys_id。成交不包含估算手续费。

TradingResult

一次交易操作的即时提交结果；不是最终委托或撤单结果。

字段	类型	含义
`status`	`Literal['SUBMITTED', 'REJECTED', 'UNKNOWN']`	SUBMITTED / REJECTED / UNKNOWN，即时提交结果。
`order_id`	`str \| None`	关联本地订单号；下单本地拒绝为 None。
`message`	`str`	即时结果说明，默认空字符串。

K 线 DataFrame

列	含义
timestamp	K 线周期结束时间，Unix 毫秒；日线使用交易日北京时间零点
trading_day	YYYYMMDD 交易日
open / high / low / close	开盘 / 最高 / 最低 / 收盘价
volume	成交量
turnover	成交额
open_interest	持仓量

frame.attrs 包含 symbol 与 period。数据为独立快照，最新一行可能仍在变化；新建指标列不会进入下一份 SDK 快照。

合约详情字典

query_symbol_info() 顶层固定含 symbol、exchange_id、product_id、ins_class、is_main、data。data 的内部键按服务实际返回读取，SDK 不承诺固定的静态字段集合。

只读集合

watch_position、watch_order、watch_trade 的 data() 返回只读 Mapping。分别按 symbol、order_id、trade_id 索引；即使指定单个合约也返回映射。不要向映射或交易快照字段赋值。