PTrade 期货 API：如何获取合约的保证金比例 (get_instruments)？

在 PTrade 量化交易平台中，获取某个期货合约当前的交易所保证金比例主要有两种方式。最常用且推荐的方式是使用 get_instruments 函数，因为它适用于回测和实盘，并且针对具体合约。另一种方式是使用 get_margin_rate，主要用于回测中获取品种的保证金设置。

以下是具体的实现方法和代码示例：

方法一：使用 get_instruments (推荐)

该函数用于获取合约的详细信息对象，其中包括保证金比例字段 margin_rate。

• 适用范围：回测、交易模块。
• 参数：具体的合约代码（如 'IF2309.CCFX'）。
• 返回值：FutureParams 对象，通过 .margin_rate 属性获取比例（小数形式，如 0.10 代表 10%）。

代码示例

def initialize(context):
    # 设置我们要查询的期货合约，例如中证500股指期货
    g.security = 'IC2209.CCFX'
    set_universe(g.security)

def before_trading_start(context, data):
    # 获取合约详细信息对象
    # 注意：这里传入的是完整的合约代码
    instrument_info = get_instruments(g.security)
    
    if instrument_info is not None:
        # 获取保证金比例
        margin_rate = instrument_info.margin_rate
        
        # 打印结果
        log.info("合约: %s" % g.security)
        log.info("交易所保证金比例: %s" % margin_rate)
        # 转换为百分比显示
        log.info("保证金比例(百分比): %.2f%%" % (margin_rate * 100))
    else:
        log.info("未获取到合约信息")

def handle_data(context, data):
    pass

方法二：使用 get_margin_rate

该函数主要用于获取用户在策略中设置的保证金比例。如果用户没有通过 set_margin_rate 手动设置，它通常返回交易所设定的默认保证金比例。

• 适用范围：主要是回测模块。
• 参数：交易品种代码（Transaction Code），而不是具体的合约代码。例如沪铜 'CU2112.XSGE' 的交易代码是 'CU'。
• 返回值：浮点数（float）。

代码示例

def initialize(context):
    # 以前面提到的沪铜为例
    g.contract = 'CU2112.XSGE'
    g.trans_code = 'CU' # 交易品种代码
    set_universe(g.contract)

def handle_data(context, data):
    # 获取该品种的保证金比例
    # 注意：这里传入的是品种代码 'CU'，而不是合约代码
    rate = get_margin_rate(g.trans_code)
    
    log.info("品种: %s, 保证金比例: %s" % (g.trans_code, rate))

总结与注意事项

1. 数据格式：返回的保证金比例通常是小数。例如返回 0.08 表示保证金比例为 8%。
2. 参数区别：
   • get_instruments 接收完整的合约代码（如 'IF2309.CCFX'）。
   • get_margin_rate 接收品种代码（如 'IF'）。
3. 实盘建议：在实盘交易中，建议优先使用 get_instruments，因为它直接反映了该具体合约的属性信息。

Q&A

Q: get_instruments 返回的 margin_rate 是交易所的最低标准还是期货公司实际收取的标准？
A: 在 PTrade 的回测环境中，这通常是交易所规定的标准保证金比例。在实盘环境中，这取决于柜台推送的数据，通常是交易所标准，但也可能包含期货公司的上浮部分，具体需以柜台实际返回为准。

Q: 如果我想在回测中手动修改保证金比例进行压力测试，应该用哪个函数？
A: 您应该使用 set_margin_rate(transaction_code, margin_rate) 函数。例如 set_margin_rate('IF', 0.15) 将该品种的保证金调整为 15%。

Q: 为什么 get_instruments 返回 None？
A: 这通常是因为传入的合约代码错误（例如后缀不对，或者合约已过期/未上市），或者在 initialize 阶段过早调用导致数据尚未准备好。建议在 before_trading_start 或 handle_data 中调用。