ptrade中如何使用API进行信用账户的直接还券（不通过买券还券）？

在ptrade量化交易平台中，针对融资融券（两融）业务，如果投资者账户中已经持有与融券负债相同的标的证券（现券），可以直接使用 直接还券 接口将持仓现券归还给券商，而无需通过“买券还券”产生新的交易费用和冲击成本。

以下是关于 marginsec_direct_refund 接口的详细使用指南及策略示例。

一、接口介绍

1. 接口定义

marginsec_direct_refund(security, amount)

2. 使用场景

• 仅支持两融交易模块（实盘/模拟盘信用账户环境），回测模块不支持。
• 仅支持 PTrade 客户端运行。

3. 参数说明

• security (str)：股票代码，例如 '600030.SS'（中信证券）。
• amount (int)：还券数量，输入正整数（通常为100的整数倍）。

4. 返回值

• None

二、核心注意事项

1. 现券来源：执行直接还券前，确保信用账户中已经有该证券的可用持仓（enable_amount）。
2. 负债查询：建议在还券前通过 get_margin_contract() 查询当前的融券合约负债情况，避免超额还券或无效操作。
3. 代码后缀：传入的股票代码需带上市场后缀，如上海证券交易所为 .SS，深圳证券交易所为 '000001.SZ' 中的 .SZ。

三、策略示例代码

以下是一个完整的 ptrade 策略示例。该策略在盘中检测到特定融券标的并拥有对应现券持仓时，自动触发直接还券操作。

# -*- coding: utf-8 -*-

def initialize(context):
    # 初始化策略，设置操作的股票池
    g.security = '600030.SS'  # 以中信证券为例
    set_universe(g.security)
    g.has_refunded = False    # 避免重复执行的标识

def handle_data(context, data):
    # 仅在交易（实盘/模拟）环境中运行直接还券
    if not is_trade():
        log.info("当前为回测环境，直接还券接口仅在交易/模拟盘环境生效。")
        return
        
    if not g.has_refunded:
        # 1. 获取当前标的的持仓信息
        position = get_position(g.security)
        
        if position is not None and position.enable_amount > 0:
            # 获取当前可用现券持仓数量
            hold_amount = position.enable_amount
            log.info(f"当前持有现券 {g.security} 可用数量: {hold_amount}")
            
            # 2. 查询信用资产与合约负债（可选，用于精准还券）
            # 这里假设我们直接将持有的100股现券用于直接还券
            refund_amount = min(hold_amount, 100) 
            
            log.info(f"正在对 {g.security} 执行直接还券，数量: {refund_amount}")
            
            # 3. 调用直接还券接口
            marginsec_direct_refund(g.security, refund_amount)
            
            g.has_refunded = True
            log.info("直接还券指令已发送。")
        else:
            log.warning(f"信用账户中未检测到 {g.security} 的可用现券持仓，无法执行直接还券。")