期权行权
期权行权
自 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_id | long long | Yes | 期权合约 ID |
type | utility::string_t | Yes | "Exercise" / "Expire" |
quantity | double | Yes | 行权数量(> 0) |
executing_date | utility::string_t | No | 行权执行日期 yyyy-MM-dd(Exercise 建议填) |
is_force | int | No | 是否强制行权:1 = 是,0 = 否,-1 = 不设置(Exercise 建议填) |
itm_rate | int | No | 价内率阈值 0–10(Expire 专用),-1 = 不设置 |
account | utility::string_t | No | 交易账户,默认使用配置中的账户 |
返回
JSON 对象,包含以下字段:
| 字段 | 类型 | 说明 |
|---|---|---|
available_quantity | double | 可行权数量 |
position | double | 当前期权持仓 |
stk_position | double | 正股当前持仓 |
stk_position_change | double | 行权后正股持仓变化量 |
stk_position_before | double | 行权前正股持仓 |
stk_position_after | double | 行权后正股持仓 |
symbol | string | 正股代码 |
示例
// 提前行权检验
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("")
)查询当前账户下可提交行权或放弃行权申请的期权持仓列表。
参数
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
type | utility::string_t | Yes | "Exercise" / "Expire" |
account | utility::string_t | No | 交易账户,默认使用配置中的账户 |
返回
JSON 对象,包含分页字段 page_num、page_size、item_count、page_count,以及 items 数组,每项包含:
| 字段 | 类型 | 说明 |
|---|---|---|
contract_id | int64 | 期权合约 ID |
symbol | string | 期权合约代码 |
stk_symbol | string | 正股代码 |
expire_date | string | 到期日 yyyy-MM-dd |
strike | string | 行权价 |
call_put | string | CALL / PUT |
market | string | 市场 |
account_id | int64 | 账户 ID |
position | double | 持仓数量 |
available_quantity | double | 可行权数量 |
示例
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_date与is_force仅在 Exercise 类型时有效itm_rate仅在 Expire 类型时有效
参数
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
contract_id | long long | Yes | 期权合约 ID |
type | utility::string_t | Yes | "Exercise" / "Expire" |
quantity | double | Yes | 行权数量(> 0) |
executing_date | utility::string_t | No | 行权执行日期(Exercise 必填) |
is_force | int | No | 是否强制行权(Exercise 必填),1 = 是,0 = 否,-1 = 不设置 |
itm_rate | int | No | 价内率阈值 0–10(Expire 专用),-1 = 不设置 |
account | utility::string_t | No | 交易账户,默认使用配置中的账户 |
返回
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_type | utility::string_t | No | 类型过滤:"Exercise" / "Expire",空字符串 = 全部 |
status | utility::string_t | No | 状态过滤:"New" / "Cancel" / "Success" / "Fail" |
symbol | utility::string_t | No | 正股代码过滤 |
order_by | utility::string_t | No | 排序字段:"symbol" / "expire_date" / "strike" / "is_call" |
page | int | No | 页码,从 1 开始,默认 1 |
size | int | No | 每页数量,1–100,默认 20 |
account | utility::string_t | No | 交易账户,默认使用配置中的账户 |
返回
JSON 对象,包含分页字段 page_num、page_size、item_count、page_count,以及 items 数组,每项包含:
| 字段 | 类型 | 说明 |
|---|---|---|
id | int64 | 行权申请记录 ID |
contract_id | int64 | 期权合约 ID |
symbol | string | 期权合约代码 |
stk_symbol | string | 正股代码 |
expire_date | string | 到期日 |
strike | string | 行权价 |
call_put | string | CALL / PUT |
exercise_type | string | Exercise / Expire |
request_quantity | double | 申请数量 |
quantity | double | 实际行权数量 |
status | string | New / Cancel / Success / Fail |
executing_date | string | 行权执行日期 |
itm_rate | int | 价内率 |
is_force | bool | 是否强制行权 |
reason | string | 拒绝原因(如有) |
account_id | int64 | 账户 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_id | long long | Yes | 行权申请记录 ID(从 get_option_exercise_records 获取) |
account | utility::string_t | No | 交易账户,默认使用配置中的账户 |
返回
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;