期权行权

期权行权

v1.2.3 起,TradeClient 提供 5 个期权行权方法,返回值均为 web::json::value

行权类型

说明
"Exercise"提前行权 — 在到期日前提前执行期权
"Expire"提前放弃行权 — 在到期日前主动放弃行权

check_option_exercise 行权检验

value TradeClient::check_option_exercise(
    long long contract_id,
    utility::string_t type,
    double quantity,
    utility::string_t executing_date = U(""),
    int is_force = -1,
    int itm_rate = -1,
    utility::string_t account = U("")
)

预估行权或放弃行权后正股持仓变化,可在提交前确认结果。

参数

参数类型是否必填说明
contract_idlong longYes期权合约 ID
typeutility::string_tYes"Exercise" / "Expire"
quantitydoubleYes行权数量(> 0)
executing_dateutility::string_tNo行权执行日期 yyyy-MM-dd(Exercise 建议填)
is_forceintNo是否强制行权:1 = 是,0 = 否,-1 = 不设置(Exercise 建议填)
itm_rateintNo价内率阈值 0–10(Expire 专用),-1 = 不设置
accountutility::string_tNo交易账户,默认使用配置中的账户

返回

JSON 对象,包含以下字段:

字段类型说明
available_quantitydouble可行权数量
positiondouble当前期权持仓
stk_positiondouble正股当前持仓
stk_position_changedouble行权后正股持仓变化量
stk_position_beforedouble行权前正股持仓
stk_position_afterdouble行权后正股持仓
symbolstring正股代码

示例

// 提前行权检验
value result = trade_client->check_option_exercise(
    1234567890LL,    // contract_id
    U("Exercise"),   // type
    1.0,             // quantity
    U("2025-06-20"), // executing_date
    0,               // is_force = false
    -1               // itm_rate = not set
);
ucout << result << endl;

// 提前放弃行权检验,设置价内率
value result2 = trade_client->check_option_exercise(
    1234567890LL,
    U("Expire"),
    1.0,
    U(""),  // executing_date = not set
    -1,     // is_force = not set
    5       // itm_rate = 5
);

get_option_exercise_positions 查询可行权持仓

value TradeClient::get_option_exercise_positions(
    utility::string_t type,
    utility::string_t account = U("")
)

查询当前账户下可提交行权或放弃行权申请的期权持仓列表。

参数

参数类型是否必填说明
typeutility::string_tYes"Exercise" / "Expire"
accountutility::string_tNo交易账户,默认使用配置中的账户

返回

JSON 对象,包含分页字段 page_numpage_sizeitem_countpage_count,以及 items 数组,每项包含:

字段类型说明
contract_idint64期权合约 ID
symbolstring期权合约代码
stk_symbolstring正股代码
expire_datestring到期日 yyyy-MM-dd
strikestring行权价
call_putstringCALL / PUT
marketstring市场
account_idint64账户 ID
positiondouble持仓数量
available_quantitydouble可行权数量

示例

value result = trade_client->get_option_exercise_positions(U("Exercise"));
if (result.has_field(U("items")) && result.at(U("items")).is_array()) {
    int64_t item_count = result.at(U("item_count")).as_number().to_int64();
    ucout << U("itemCount=") << item_count << endl;
    for (auto &pos : result.at(U("items")).as_array()) {
        ucout << U("contractId=") << pos.at(U("contract_id")).as_number().to_int64()
              << U(" symbol=") << pos.at(U("symbol")).as_string()
              << U(" availableQty=") << pos.at(U("available_quantity")).as_double()
              << endl;
    }
}

submit_option_exercise 提交行权申请

value TradeClient::submit_option_exercise(
    long long contract_id,
    utility::string_t type,
    double quantity,
    utility::string_t executing_date = U(""),
    int is_force = -1,
    int itm_rate = -1,
    utility::string_t account = U("")
)

提交提前行权或提前放弃行权申请。

⚠️

注意

  • 提交前建议先调用 check_option_exercise 确认持仓变化
  • executing_dateis_force 仅在 Exercise 类型时有效
  • itm_rate 仅在 Expire 类型时有效

参数

参数类型是否必填说明
contract_idlong longYes期权合约 ID
typeutility::string_tYes"Exercise" / "Expire"
quantitydoubleYes行权数量(> 0)
executing_dateutility::string_tNo行权执行日期(Exercise 必填)
is_forceintNo是否强制行权(Exercise 必填),1 = 是,0 = 否,-1 = 不设置
itm_rateintNo价内率阈值 0–10(Expire 专用),-1 = 不设置
accountutility::string_tNo交易账户,默认使用配置中的账户

返回

JSON 对象,包含 success(bool)字段表示提交是否成功。

示例

// 提前行权
value result = trade_client->submit_option_exercise(
    1234567890LL,
    U("Exercise"),
    1.0,
    U("2025-06-20"),
    0,   // is_force = false
    -1
);
bool ok = result.at(U("success")).as_bool();
ucout << (ok ? U("提交成功") : U("提交失败")) << endl;

// 提前放弃行权
value result2 = trade_client->submit_option_exercise(
    1234567890LL,
    U("Expire"),
    1.0,
    U(""),  // executing_date = not set
    -1,
    5       // itm_rate = 5
);

get_option_exercise_records 查询行权记录

value TradeClient::get_option_exercise_records(
    utility::string_t exercise_type = U(""),
    utility::string_t status = U(""),
    utility::string_t symbol = U(""),
    utility::string_t order_by = U(""),
    int page = 1,
    int size = 20,
    utility::string_t account = U("")
)

分页查询已提交的行权申请记录。

参数

参数类型是否必填说明
exercise_typeutility::string_tNo类型过滤:"Exercise" / "Expire",空字符串 = 全部
statusutility::string_tNo状态过滤:"New" / "Cancel" / "Success" / "Fail"
symbolutility::string_tNo正股代码过滤
order_byutility::string_tNo排序字段:"symbol" / "expire_date" / "strike" / "is_call"
pageintNo页码,从 1 开始,默认 1
sizeintNo每页数量,1–100,默认 20
accountutility::string_tNo交易账户,默认使用配置中的账户

返回

JSON 对象,包含分页字段 page_numpage_sizeitem_countpage_count,以及 items 数组,每项包含:

字段类型说明
idint64行权申请记录 ID
contract_idint64期权合约 ID
symbolstring期权合约代码
stk_symbolstring正股代码
expire_datestring到期日
strikestring行权价
call_putstringCALL / PUT
exercise_typestringExercise / Expire
request_quantitydouble申请数量
quantitydouble实际行权数量
statusstringNew / Cancel / Success / Fail
executing_datestring行权执行日期
itm_rateint价内率
is_forcebool是否强制行权
reasonstring拒绝原因(如有)
account_idint64账户 ID

示例

value result = trade_client->get_option_exercise_records(
    U(""),     // exercise_type = all
    U(""),     // status = all
    U(""),     // symbol = all
    U(""),     // order_by = default
    1, 20
);
if (result.has_field(U("items")) && result.at(U("items")).is_array()) {
    for (auto &r : result.at(U("items")).as_array()) {
        ucout << U("id=") << r.at(U("id")).as_number().to_int64()
              << U(" type=") << r.at(U("exercise_type")).as_string()
              << U(" status=") << r.at(U("status")).as_string()
              << endl;
    }
}

cancel_option_exercise 撤销行权申请

value TradeClient::cancel_option_exercise(
    long long exercise_id,
    utility::string_t account = U("")
)

撤销尚未执行的行权申请。

参数

参数类型是否必填说明
exercise_idlong longYes行权申请记录 ID(从 get_option_exercise_records 获取)
accountutility::string_tNo交易账户,默认使用配置中的账户

返回

JSON 对象,包含 success(bool)字段。

示例

long long record_id = 987654321LL;  // from get_option_exercise_records
value result = trade_client->cancel_option_exercise(record_id);
bool ok = result.at(U("success")).as_bool();
ucout << (ok ? U("撤销成功") : U("撤销失败")) << endl;