PTrade API 教程：如何查询融资融券合约的详细信息？

在PTrade中，查询当前所有融资融券合约并筛选未还清合约，主要使用 get_margin_contract() 接口。

该接口返回一个 DataFrame，其中包含了合约状态（compact_status）和负债总额（total_debit）等关键信息。

核心逻辑

1. 调用接口：使用 get_margin_contract() 获取所有合约记录。
2. 筛选条件：根据 compact_status（合约状态）进行筛选。
   • "0"：开仓未归还（完全未还）
   • "1"：部分归还（还有剩余负债）
3. 输出结果：打印或处理筛选后的数据。

策略代码实现

以下代码展示了如何在策略中查询并打印未还清的合约列表：

def initialize(context):
    # 初始化，设置一个标的以保证策略正常启动
    g.security = '600570.SS'
    set_universe(g.security)
    
    # 设定一个标志位，防止在handle_data中重复打印
    g.checked = False

def handle_data(context, data):
    # 仅执行一次查询
    if g.checked:
        return

    # 1. 获取所有融资融券合约
    # 注意：该函数仅在两融交易模块可用
    df_contracts = get_margin_contract()

    # 2. 检查是否有数据返回
    if df_contracts is None or df_contracts.empty:
        log.info("当前没有查询到任何融资融券合约记录。")
        g.checked = True
        return

    # 3. 筛选未还清的合约
    # compact_status: '0'代表开仓未归还，'1'代表部分归还
    # 也可以通过 total_debit (负债总额) > 0 来判断
    outstanding_contracts = df_contracts[
        (df_contracts['compact_status'] == '0') | 
        (df_contracts['compact_status'] == '1')
    ]

    # 4. 打印结果
    if not outstanding_contracts.empty:
        log.info("发现 %d 条未还清合约：" % len(outstanding_contracts))
        # 打印关键字段：合约编号、证券代码、合约类别(0融资/1融券)、合约状态、负债总额、开仓日期
        log.info(outstanding_contracts[['compact_id', 'stock_code', 'compact_type', 
                                      'compact_status', 'total_debit', 'open_date']])
    else:
        log.info("当前所有合约均已结清。")

    g.checked = True

关键字段说明

在 get_margin_contract() 返回的 DataFrame 中，以下字段用于判断还款情况：

• compact_status (合约状态):
  • "0": 开仓未归还 (需要关注)
  • "1": 部分归还 (需要关注)
  • "2": 合约已过期
  • "3": 客户自行归还 (已结清)
  • "4": 手工了结
  • "5": 未形成负债
• compact_type (合约类别):
  • "0": 融资
  • "1": 融券
• total_debit: 负债总额，即当前该合约还需要归还的金额。

注意事项

1. 适用环境：get_margin_contract() 仅支持 Ptrade客户端，且必须在 两融交易模块（实盘或两融模拟盘）中运行。普通股票回测中调用可能会返回 None 或报错。
2. 数据类型：返回的 compact_status 是字符串类型（str），筛选时请使用引号，如 '0' 而不是数字 0。

Q&A

Q: 如何查询当天的实时合约流水？
A: 可以使用 get_margin_contractreal() 接口查询当天的实时合约流水，包含发生金额、费用和利息等变动详情。

Q: 如果我想直接查询账户的总负债金额而不是具体合约，用哪个函数？
A: 使用 get_margin_assert() 函数，它返回一个字典，其中的 total_debit 字段即为账户的负债总额。

Q: 融资合约和融券合约在查询结果中如何区分？
A: 在 get_margin_contract() 返回的数据中，查看 compact_type 字段。"0" 代表融资合约，"1" 代表融券合约。