exsdk Python API 接口参考

Literal 表示允许值集合，Mapping 表示只读映射。示例中的 api、token、symbol、limit_price 和 order_id 由调用方提供。

通用调用约定#

所有实例方法在创建实例的线程使用，不可在运行中的 asyncio 事件循环内直接调用。观察数据通过 wait_update() 推进，data() 读取快照。完整说明见更新模型与生命周期，字段与单位见数据字典。

行情验证 Token 和使用权益；交易还验证绑定的 user_id，运行期间会重新验证。认证与运行故障可能抛 ExError；参数类型或取值错误可能抛 TypeError、ValueError，调用方式错误可能抛 RuntimeError。下单、撤单的业务拒绝另通过 TradingResult 报告，见错误处理。

ExApi#

ExApi(token: str, account: CtpAccount | None=None)

创建同步实例；不传 account 时仅启用行情。token 使用个人中心获取的完整 Token。创建实例不代表已通过服务验证或交易账户已就绪。

with ExApi(token) as api:
    print(api.query_symbols("FUTURE"))

优先用 with 管理资源；退出不会撤销委托。账户配置见 CtpAccount。

ExApi.trading_status#

ExApi.trading_status() -> Literal['SYNCING', 'READY', 'DISCONNECTED', 'ERROR']

读取最近一次更新发布的交易状态，不主动查询。需要配置交易账户；状态含义与恢复操作见交易状态。READY 表示登录同步完成，不保证资金和行情即时。

ExApi.watch_account#

ExApi.watch_account() -> Watch[Account]

观察资金，需要配置交易账户。未知字段为 None，默认每 5 秒安排一次资金查询，实际完成可能更晚。

funds = api.watch_account()
while api.wait_update():
    if api.trading_status() == "READY" and funds.is_changing("updated_at"):
        print(funds.data().available)
        break

金额未变时默认变化检测可能为 False；查询完成的判断见资金刷新。

ExApi.watch_position#

ExApi.watch_position(symbol: str | None=None) -> Watch[Mapping[str, Position]]

观察全部或单个合约持仓，需要配置交易账户。symbol 不传表示全部；传入时使用有效的 交易所.合约 格式。

data() 返回以合约代码为键的映射，即使指定单个合约也一样。可提前观察尚无持仓的合约，归零对象继续保留；格式无效或在已加载合约中找不到时抛 ValueError。

positions = api.watch_position(symbol)
while api.trading_status() != "READY":
    api.wait_update()
position = positions.data().get(symbol)

ExApi.watch_order#

ExApi.watch_order(symbol: str | None=None) -> Watch[Mapping[str, Order]]

观察当前交易日全部或某合约订单，需要配置交易账户。symbol 不传表示全部，格式无效抛 ValueError。data() 按本地 order_id 索引，包括同一账户其他客户端的普通投机订单；不会按策略自动隔离。

ExApi.watch_trade#

ExApi.watch_trade(symbol: str | None=None) -> Watch[Mapping[str, Trade]]

观察当前交易日全部或某合约真实成交，需要配置交易账户。symbol 不传表示全部，格式无效抛 ValueError。data() 按 CTP TradeID 索引，包括其他客户端的普通投机成交，不根据订单提交估算成交。

订单、成交和持仓的访问示例见交易数据。

ExApi.insert_order#

ExApi.insert_order(symbol: str, direction: Literal['BUY', 'SELL'], offset: Literal['OPEN', 'CLOSE'], volume: int, limit_price: float) -> list[TradingResult]

提交普通投机限价委托，可能按平仓规则拆成多个子单。

参数	要求
`symbol`	当前支持且可交易的期货或期权合约代码
`direction`	`BUY` 买入，`SELL` 卖出
`offset`	`OPEN` 开仓，`CLOSE` 平仓
`volume`	正整数手数，各子单须符合合约委托数量限制
`limit_price`	有限且大于 0，符合合约最小变动价位

每个子单返回一个只读即时结果。未配置账户、非就绪状态、参数无效等通常返回 REJECTED；明确未提交的下单不创建订单，order_id=None。账户验证失败仍可能抛 ExError。

results = api.insert_order(symbol, "BUY", "OPEN", 1, limit_price)
for result in results:
    print(result.status, result.order_id, result.message)

SUBMITTED 不表示柜台接受或成交；UNKNOWN 不应盲目重发。平仓拆单、结果跟踪和恢复处理见订单教程。

ExApi.cancel_order#

ExApi.cancel_order(order_id: str) -> list[TradingResult]

传入本地订单号，不是 order_sys_id。返回即时结果列表；不存在、已结束、已有撤单在处理的订单返回 []，未配置账户时也返回 []。空列表不证明订单已撤销。

非就绪状态、订单尚未确认或缺少系统编号等返回 REJECTED，保留原订单号，不缓存撤单意图。账户验证失败仍可能抛 ExError。最终通过更新循环检查 status、volume_traded、cancel_pending 和 cancel_error，见撤单。

ExApi.query_symbols#

ExApi.query_symbols(ins_class: Literal['FUTURE', 'OPTION'], exchange_id: str | None=None, product_id: str | None=None, is_main: bool | None=None) -> list[str]

一次性查询合约代码列表，可能为空。

参数	要求
`ins_class`	必填；`FUTURE` 查询期货，`OPTION` 查询期权
`exchange_id`、`product_id`	不传或 `None` 表示不限；传入时须为非空字符串
`is_main`	`True` 仅主力，`False` 仅非主力，`None` 不限；期权均为非主力

无效筛选参数抛 ValueError；查询故障或响应格式无效抛 ExError。主力筛选不会使已有订阅自动换月，见合约查询。

symbols = api.query_symbols("FUTURE", exchange_id="SHFE", is_main=True)

ExApi.query_symbol_info#

ExApi.query_symbol_info(symbol: str) -> dict

查询单个合约详情，返回一次性字典，顶层包含 symbol、exchange_id、product_id、ins_class、is_main 和详情字典 data。常用详情字段见合约详情字典。

合约格式无效抛 ValueError，查询失败或响应无效抛 ExError。两个 query 方法都不需要调用 wait_update()，结果不会随更新循环自动变化。

ExApi.watch_quote#

ExApi.watch_quote(symbol: str) -> Watch[Quote]

创建期货或期权实时行情观察句柄，相同合约复用同一句柄；合约格式无效抛 ValueError。初始时间戳为 0，数值可能为 NaN，盘口可为空；通过更新循环等待数据。

这是快照订阅，不保证逐条观察全部中间行情，见实时行情。

ExApi.watch_kline#

ExApi.watch_kline(symbol: str, period: Literal['1m', '5m', '10m', '15m', '30m', '1h', '4h', '1d', '1w', 'mn'], data_length: int=200) -> Watch[pd.DataFrame]

初始化并订阅期货固定长度 K 线窗口，期权暂不支持。合约格式、周期或窗口长度无效抛 ValueError；data_length 为 1–10000 的整数。

初始化同步完成，可能等待网络，故障抛 ExError。相同合约、周期和长度复用句柄，不同长度对应不同窗口。

bars = api.watch_kline(symbol, "1m", data_length=200)
frame = bars.data()
valid = frame.loc[frame["timestamp"] > 0]
if not valid.empty:
    print(valid.iloc[-1])

不足的历史行以 0 时间戳和 NaN 等值补齐，不能以表是否为空判断数据有效性。指标和完成 K 线示例见 K 线教程。

ExApi.wait_update#

ExApi.wait_update(deadline: float | None=None) -> bool

推进 I/O 并发布下一批更新。deadline 是有限的 Unix 秒绝对时间，如 time.time() + 5；None 表示不设置本次等待期限。

返回 True 表示发布一批更新，False 表示本次期限到达，不等于连接故障。一个批次不保证所有观察对象都有字段变化。无效期限抛 ValueError；没有行情订阅且未配置交易账户时抛 RuntimeError；运行故障抛 ExError。

持续等待和任务总期限的写法见有限等待。

ExApi.close#

ExApi.close() -> None

关闭连接并释放资源，可重复调用。关闭不撤销已提交订单。优先用 with，异常退出时也会清理资源。

Watch.data#

Watch.data() -> T

读取当前独立快照，不触发查询。返回类型由句柄决定：Quote、pd.DataFrame、Account 或只读 Mapping[str, Position/Order/Trade]。数据缺失、快照保存及断线语义见快照说明。

Watch.is_changing#

Watch.is_changing(key: str | list[str] | None=None) -> bool

检查最近一次 wait_update() 中的变化。key 可为字段名、字段名列表或 None；列表按任意字段变化判断，未知字段或无效参数抛 ValueError。刚创建句柄时，不将已有初始数据视为变化。

K 线只比较末行；集合成员增减也构成变化；默认检测不包含资金的 updated_at。详细规则见变化检测。

api.tools.download_kline_data#

api.tools.download_kline_data(symbol: str, period: Literal['1m', '5m', '10m', '15m', '30m', '1h', '4h', '1d', '1w', 'mn'], start: str, end: str, limit: int=10000) -> pandas.DataFrame

按交易日范围查询期货 K 线，同步返回 DataFrame，无需 wait_update()。

参数	要求
`symbol`	期货合约代码，不支持期权
`period`	支持周期与 `watch_kline()` 相同
`start`、`end`	`YYYYMMDD` 格式的有效交易日范围，包含首尾两天，须满足 `start <= end`
`limit`	单次最多返回的根数，1–10000 的整数，默认 10000

从起始交易日向后取数，周月线返回相交周期的整根 K 线。结果按时间升序，同一时间戳保留最后一条；无数据返回空表，不补齐到 limit 行，attrs 包含合约和周期。单次结果可能未覆盖整个范围，完整下载见历史 K 线下载。

无效参数抛 TypeError 或 ValueError，查询故障或响应无效抛 ExError。

上下文管理与 Watch 类型#

使用 with ExApi(...) as api: 管理实例生命周期。watch_*() 返回 Watch[T] 观察句柄，历史下载工具通过 api.tools 使用。

完整接口参考