Option Exercise

Since v1.2.3, TradeClient provides 5 option exercise methods. All return web::json::value.

Exercise Type

Value	Description
`"Exercise"`	Early exercise — execute the option before expiration
`"Expire"`	Early waive — voluntarily waive the right to exercise before expiration

check_option_exercise Preview 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("")
)

Preview the stock position changes from an exercise or waive request. Call this before submitting to confirm the expected result.

Parameters

Parameter	Type	Required	Description
`contract_id`	`long long`	Yes	Option contract ID
`type`	`utility::string_t`	Yes	`"Exercise"` / `"Expire"`
`quantity`	`double`	Yes	Number of contracts (> 0)
`executing_date`	`utility::string_t`	No	Execution date `yyyy-MM-dd` (recommended for Exercise)
`is_force`	`int`	No	Force exercise: `1` = yes, `0` = no, `-1` = not set (recommended for Exercise)
`itm_rate`	`int`	No	In-the-money rate threshold 0–10 (Expire only), `-1` = not set
`account`	`utility::string_t`	No	Trading account; defaults to config account

Return

JSON object with the following fields:

Field	Type	Description
`available_quantity`	double	Available quantity for exercise
`position`	double	Current option position
`stk_position`	double	Current underlying stock position
`stk_position_change`	double	Change in underlying stock position after exercise
`stk_position_before`	double	Underlying stock position before exercise
`stk_position_after`	double	Underlying stock position after exercise
`symbol`	string	Underlying stock symbol

Example

// Preview early exercise
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;

// Preview waive with ITM rate
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 Query Exercisable Positions

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

Query option positions in the current account that are eligible for exercise or waive.

Parameters

Parameter	Type	Required	Description
`type`	`utility::string_t`	Yes	`"Exercise"` / `"Expire"`
`account`	`utility::string_t`	No	Trading account; defaults to config account

Return

JSON object with pagination fields page_num, page_size, item_count, page_count, and an items array. Each item contains:

Field	Type	Description
`contract_id`	int64	Option contract ID
`symbol`	string	Option contract code
`stk_symbol`	string	Underlying stock symbol
`expire_date`	string	Expiration date `yyyy-MM-dd`
`strike`	string	Strike price
`call_put`	string	`CALL` / `PUT`
`market`	string	Market
`account_id`	int64	Account ID
`position`	double	Position quantity
`available_quantity`	double	Available quantity for exercise

Example

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 Submit Exercise Request

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("")
)

Submit an early exercise or early waive request.

⚠️
Note

Call check_option_exercise first to confirm expected position changes

executing_date and is_force are only effective for Exercise type

itm_rate is only effective for Expire type

Parameters

Parameter	Type	Required	Description
`contract_id`	`long long`	Yes	Option contract ID
`type`	`utility::string_t`	Yes	`"Exercise"` / `"Expire"`
`quantity`	`double`	Yes	Number of contracts (> 0)
`executing_date`	`utility::string_t`	No	Execution date (required for Exercise)
`is_force`	`int`	No	Force exercise (required for Exercise): `1` = yes, `0` = no, `-1` = not set
`itm_rate`	`int`	No	In-the-money rate threshold 0–10 (Expire only), `-1` = not set
`account`	`utility::string_t`	No	Trading account; defaults to config account

Return

JSON object with a success (bool) field indicating whether the submission succeeded.

Example

// Early exercise
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("Submitted successfully") : U("Submission failed")) << endl;

// Early waive
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 Query 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("")
)

Query submitted option exercise records with pagination.

Parameters

Parameter	Type	Required	Description
`exercise_type`	`utility::string_t`	No	Type filter: `"Exercise"` / `"Expire"`, empty = all
`status`	`utility::string_t`	No	Status filter: `"New"` / `"Cancel"` / `"Success"` / `"Fail"`
`symbol`	`utility::string_t`	No	Underlying stock symbol filter
`order_by`	`utility::string_t`	No	Sort field: `"symbol"` / `"expire_date"` / `"strike"` / `"is_call"`
`page`	`int`	No	Page number (1-based), default 1
`size`	`int`	No	Page size (1–100), default 20
`account`	`utility::string_t`	No	Trading account; defaults to config account

Return

JSON object with pagination fields page_num, page_size, item_count, page_count, and an items array. Each item contains:

Field	Type	Description
`id`	int64	Exercise record ID
`contract_id`	int64	Option contract ID
`symbol`	string	Option contract code
`stk_symbol`	string	Underlying stock symbol
`expire_date`	string	Expiration date
`strike`	string	Strike price
`call_put`	string	`CALL` / `PUT`
`exercise_type`	string	`Exercise` / `Expire`
`request_quantity`	double	Requested quantity
`quantity`	double	Actual exercised quantity
`status`	string	`New` / `Cancel` / `Success` / `Fail`
`executing_date`	string	Execution date
`itm_rate`	int	In-the-money rate
`is_force`	bool	Whether forced exercise
`reason`	string	Rejection reason (if any)
`account_id`	int64	Account ID

Example

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 Cancel Exercise Request

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

Cancel a pending option exercise request.

Parameters

Parameter	Type	Required	Description
`exercise_id`	`long long`	Yes	Exercise record ID (from `get_option_exercise_records`)
`account`	`utility::string_t`	No	Trading account; defaults to config account

Return

JSON object with a success (bool) field.

Example

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("Cancelled successfully") : U("Cancellation failed")) << endl;