Option Exercise

C++ HTTP methods return the value of the complete response's data field. The outer code, message, and timestamp fields, and the data field name itself, are not part of the returned value.

Option Exercise

TradeClient provides 5 option exercise methods. All return web::json::value.

Exercise Type

Value	Description
`"Exercise"`	Exercise the option before expiration
`"Expire"`	Waive the right to exercise before expiration

Preview an Exercise Request

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

Previews the stock-position changes from an early exercise request or a request to waive the right to exercise before expiration. Call this method before submission 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 the configured account

Return

JSON object with the following fields:

Field	Type	Description
`availableQuantity`	double	Available quantity for exercise
`position`	double	Current option position
`stkPosition`	double	Current underlying stock position
`stkPositionChange`	double	Change in underlying stock position after exercise
`stkPositionBefore`	double	Underlying stock position before exercise
`stkPositionAfter`	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 a request to waive the right to exercise, using an 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
);

Response Example

{
  "availableQuantity": 5,
  "position": 5,
  "stkPosition": 0,
  "stkPositionChange": 500,
  "stkPositionBefore": 0,
  "stkPositionAfter": 500,
  "symbol": "AAPL"
}

Rate Limit

Base rate: 60 requests per minute (counted per TigerId and interface in a 60-second rolling window).

Get Exercisable Positions

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

Returns option positions in the current account that are eligible for early exercise or for waiving exercise rights before expiration.

Parameters

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

Return

JSON object with pagination fields pageNum, pageSize, itemCount, pageCount, and an items array. items is empty when no position matches. Each item contains:

Field	Type	Description
`contractId`	int64	Option contract ID
`symbol`	string	Option contract code
`stkSymbol`	string	Underlying stock symbol
`expireDate`	string	Expiration date in `yyyyMMdd` format
`strike`	string	Strike price
`callPut`	string	`CALL` / `PUT`
`market`	string	Market
`accountId`	int64	Account ID
`position`	double	Position quantity
`availableQuantity`	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("itemCount")).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("contractId")).as_number().to_int64()
              << U(" symbol=") << pos.at(U("symbol")).as_string()
              << U(" availableQty=") << pos.at(U("availableQuantity")).as_double()
              << endl;
    }
}

Response Example

{
  "pageNum": 1,
  "pageSize": 20,
  "itemCount": 1,
  "pageCount": 1,
  "items": [
    {
      "contractId": 55678,
      "symbol": "AAPL",
      "stkSymbol": "AAPL",
      "expireDate": "20250808",
      "strike": "230",
      "callPut": "CALL",
      "market": "US",
      "accountId": 123,
      "position": 5,
      "availableQuantity": 5
    }
  ]
}

Rate Limit

Base rate: 60 requests per minute (counted per TigerId and interface in a 60-second rolling window).

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

Submits an early exercise request or a request to waive the right to exercise before expiration.

⚠️
Note

Call check_option_exercise first to confirm expected position changes

executing_date and is_force apply only when type is "Exercise"

itm_rate applies only when type is "Expire"

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 the configured account

Return

Boolean; true means the request was accepted.

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.as_bool();
ucout << (ok ? U("Submitted successfully") : U("Submission failed")) << endl;

// Waive exercise rights before expiration
value result2 = trade_client->submit_option_exercise(
    1234567890LL,
    U("Expire"),
    1.0,
    U(""),  // executing_date = not set
    -1,
    5       // itm_rate = 5
);

Response Example

true

Rate Limit

Base rate: 60 requests per minute (counted per TigerId and interface in a 60-second rolling window).

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

Returns 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 the configured account

Return

JSON object with pagination fields pageNum, pageSize, itemCount, pageCount, and an items array. items is empty when no record matches. Each item contains:

Field	Type	Description
`id`	int64	Exercise record ID
`contractId`	int64	Option contract ID
`symbol`	string	Option contract code
`stkSymbol`	string	Underlying stock symbol
`expireDate`	string	Expiration date
`strike`	string	Strike price
`callPut`	string	`CALL` / `PUT`
`type`	string	`Exercise` / `Expire`
`requestQuantity`	double	Requested quantity
`quantity`	double	Actual exercised quantity
`status`	string	`New` / `Cancel` / `Success` / `Fail`
`executingDate`	string	Execution date in `yyyy-MM-dd` format
`itmRate`	int	In-the-money rate
`isForce`	bool	Indicates whether exercise is forced
`reason`	string	Rejection reason (if any)
`accountId`	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("type")).as_string()
              << U(" status=") << r.at(U("status")).as_string()
              << endl;
    }
}

Response Example

{
  "pageNum": 1,
  "pageSize": 20,
  "itemCount": 1,
  "pageCount": 1,
  "items": [
    {
      "id": 200001,
      "contractId": 55678,
      "symbol": "AAPL",
      "stkSymbol": "AAPL",
      "expireDate": "20250808",
      "strike": "230",
      "callPut": "CALL",
      "type": "Exercise",
      "requestQuantity": 5,
      "quantity": 5,
      "status": "New",
      "executingDate": "2025-08-08",
      "itmRate": 0,
      "isForce": false,
      "reason": "",
      "accountId": 123
    }
  ]
}

Rate Limit

Base rate: 60 requests per minute (counted per TigerId and interface in a 60-second rolling window).

Cancel an Exercise Request

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

Cancels 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 the configured account

Return

Boolean; true means the cancellation request was accepted.

Example

long long record_id = 987654321LL;  // from get_option_exercise_records
value result = trade_client->cancel_option_exercise(record_id);
bool ok = result.as_bool();
ucout << (ok ? U("Cancelled successfully") : U("Cancellation failed")) << endl;

Response Example

true

Rate Limit

Base rate: 60 requests per minute (counted per TigerId and interface in a 60-second rolling window).