LocalQuant 文档

外观

合约查询与 Instrument ​

从 localquant.apis 导入以下查询函数。查询范围仅限本次bundle已加载的合约，不代表全市场；系列自动扩展的真实月份可能也在范围内。代码格式和加载方法见数据加载。查询可在 init 及日常策略回调使用，系列路由另有限制。

active_instrument ​

摘要：查询当前交易时点有效的合约对象。

python
active_instrument(order_book_id)
参数类型 / 默认说明
order_book_idstr | Instrument，必填合约代码或对象；不存在、尚未上市或已失效时抛出参数错误

返回：Instrument — 当前交易时点有效的合约对象。

注意：只需要当前可用对象时优先使用它。

active_instruments ​

摘要：批量查询当前交易时点有效的合约对象。

python
active_instruments(order_book_ids)
参数类型 / 默认说明
order_book_idsstr | Instrument | Iterable[str | Instrument]，必填单个代码/Instrument，或二者组成的可迭代集合；未知代码在参数检查时失败

返回：dict[str, Instrument] — 键为代码。已加载但当前不活跃的合约不出现在结果中；全无活跃合约返回 {}。

python
from localquant.apis import active_instruments

active = active_instruments(["600000.SH", "510300.SH"])
for code, instrument in active.items():
    lot_size = instrument.round_lot

instruments ​

摘要：读取已加载的合约基础信息，不限定当前已上市。

python
instruments(id_or_symbols)
参数类型 / 默认说明
id_or_symbolsstr | Iterable[str]，必填传代码或代码集合

返回：Instrument | list[Instrument] | None — 按实际找到的对象数量决定，与输入是不是列表无关：

情况返回
0个None
1个Instrument
多个list[Instrument]

注意：例如 instruments(["600000.SH"]) 通常返回单对象。需要固定列表形状时使用下面的历史查询。

instrument_history 与 instruments_history ​

摘要：查询合约基础信息的历史记录。

python
instrument_history(order_book_id)
instruments_history(order_book_ids)
参数类型 / 默认说明
order_book_idstr，必填instrument_history的单代码；未知代码会在检查时失败
order_book_idsstr | Instrument | Iterable[str | Instrument]，必填instruments_history接受单代码/Instrument或可迭代集合；未知代码会在检查时失败

返回：list[Instrument] — 包括已加载的失效记录。

注意：“历史”指同一代码的合约基础信息记录，不是行情序列，也不保证供应商历史修订版本齐全；行情使用history_bars。

all_instruments ​

摘要：按类型和日期筛选已加载的合约。

python
all_instruments(type=None, date=None)
参数类型 / 默认说明
typestr | Iterable[str] | None，默认 None按类型筛选；当前链路使用CS、ETF、INDX、Future。None取全部；Stock等价CS，Fund包含ETF/LOF
date日期字符串 / date / datetime / Timestamp / None，默认 None该日有效的合约，默认当前交易时点；请求未来日期时按当前交易时点截断

返回：pandas.DataFrame — 普通整数索引，固定以下五列；无匹配时为空表但保留列名：

列值类型说明
order_book_id / symbolstr代码 / 名称
typeINSTRUMENT_TYPE枚举合约类型，.value取得CS、ETF、INDX、Future等标签
listed_date / de_listed_date日期时间值上市 / 失效日期；DataFrame通常使用datetime64列

注意：详细交易参数从Instrument属性查询，不通过改变type参数取得额外字段。当前基金链路统一为ETF类型；type="LOF"不表示能筛出本链路的场内LOF。

get_future_contracts ​

摘要：查询当前时点有效、已加载的真实月合约代码。

python
get_future_contracts(underlying_symbol)
参数类型 / 默认说明
underlying_symbolstr，必填品种代码如 "RB"、"IF"

返回：list[str] — 当前时点有效、已加载的真实月合约代码，排除连续系列，按合约代码排序；没有匹配为 []。

注意：不加载未在bundle内的远月合约，也不挑选主力合约。

get_future_series_contract ​

摘要：查询期货系列当前执行的真实合约代码。

python
get_future_series_contract(order_book_id)
参数类型 / 默认说明
order_book_idstr，必填已加载的期货系列代码，例如 "RB.SHF"；传普通月合约或未加载系列会失败

返回：str — 当前执行真实合约代码。

时机：日频仅在handle_bar返回当日路由；分钟可在before_trading、handle_bar、after_trading查询全日固定路由。不能在init、竞价或scheduler查询。

注意：当前路由不表示已有系列仓位都已移到同一合约，归属仓位仍通过get_position查看。

symbol ​

摘要：生成用于日志显示的代码与名称字符串。

python
symbol(order_book_id, sep=", ")
参数类型 / 默认说明
order_book_idstr | Iterable[str]，必填代码字符串或代码字符串的可迭代集合
sepstr，默认 ", "连接符，默认逗号加空格

返回：str — 单个为 代码[名称]，多个用sep连接。

注意：用于日志显示，不改变订单代码。

Instrument 属性 ​

通过上面的查询获取，不自行构造。以下公开属性在策略中作为只读数据使用；示例代码应读取实际对象，不能凭证券代码推断规则。

属性类型说明
order_book_id / symbolstr原生代码 / 名称
typeINSTRUMENT_TYPECS、ETF、INDX或Future对应枚举
exchangestr框架交易所标识，不是代码后缀
listed_date / de_listed_datedatetime.datetime上市 / 失效日期；未提供实际日期的输入可使用数据源占位日期
round_lotint每手数量，当前股票基金100、期货1
min_order_quantity / order_step_sizeint最小申报量 / 数量递增步长
market_tplusint合约买入到可卖的交易日间隔；当前股票基金统一1，账户开关另行控制
contract_multiplierfloat价格乘数量换成名义金额的乘数；股票基金为1
underlying_symbolstr，期货品种代码，如RB

股票申报单位未按板块区分，基金T+0未逐只识别，详见股票模型、基金模型。不要将空行业/板块信息解释为真实分类。

期货合约参数 ​

以下方法在运行中的策略回调使用，保证金查询针对真实月合约；系列没有独立保证金率。

方法参数返回
instrument.tick_size()无float，最小价格变动单位
instrument.get_long_margin_ratio(dt)dt为交易日datefloat，多头保证金比例小数，不含margin_multiplier
instrument.get_short_margin_ratio(dt)dt同上float，空头保证金比例小数，不含倍率
instrument.calc_cash_occupation(price, quantity, direction, dt)price为原始价格float；quantity为整数手；direction为POSITION_DIRECTION.LONG/SHORT；dt为交易日datefloat元，已包含合约乘数和base.margin_multiplier，不含手续费
instrument.is_future_continuous_contract(order_book_id)代码strre.Match | None，仅按代码格式识别；使用bool判断，不据此确认数据已加载

通常传 dt=context.trading_date。分钟保证金按盘中与结算阶段切换，不应查询未来日；数据来源和资金模型见期货保证金。

下面是日频空仓初次开多的预算片段，放在 handle_bar 中；示例手续费假设与期货日频示例一致：

python
from localquant.apis import POSITION_DIRECTION, active_instrument, buy_open, get_future_series_contract

def open_with_budget(context, bars):
    contract = get_future_series_contract("RB.SHF")
    instrument = active_instrument(contract)
    price = bars[contract].close
    one_margin = instrument.calc_cash_occupation(
        price, 1, POSITION_DIRECTION.LONG, context.trading_date,
    )
    one_fee = price * instrument.contract_multiplier * 0.0001
    budget = min(context.future_account.cash, context.portfolio.total_value * 0.1)
    quantity = int(budget // (one_margin + one_fee))
    if quantity > 0:
        buy_open("RB.SHF", quantity)

这里 10% 是示例开仓预算，不是框架默认风控。组合已有仓位时应先扣除所定义的已用预算和活动订单占用；手续费、保证金率、滑点及未来结算变化都可能影响最终可成交量。读取实际订单与持仓确认结果，不以预算计算代替成交确认。

localquant documentation

Copyright © 2026 localquant