Option Exercise

Overview

The option exercise APIs are available since v0.4.2 and provide the following capabilities:

Exercise check: Estimate the underlying stock position change after exercise or waive
Query exercisable positions: Get the list of option positions eligible for exercise/waive requests
Submit exercise request: Submit an early exercise or early waive request
Query exercise records: Paginated query of submitted exercise request history
Cancel exercise request: Cancel a pending exercise request

Exercise Types (OptionExerciseType)

Value	Description
`Exercise`	Early exercise — exercise the option before expiry
`Expire`	Early waive — voluntarily waive the right to exercise before expiry

Exercise Check

Method: TradeClient.check_option_exercise()

Estimates the underlying stock position change after exercise or waive. Call this before submitting to confirm the expected result.

Parameters

Parameter	Type	Required	Description
contract_id	int	Yes	Option contract ID
exercise_type	OptionExerciseType \| str	Yes	Exercise type: `Exercise` / `Expire`
quantity	float	Yes	Exercise quantity (> 0)
account	str	No	Trading account (defaults to config account)
executing_date	str	Required for Exercise	Execution date, format `yyyy-MM-dd`
is_force	bool	Required for Exercise	Whether to force exercise
itm_rate	int	No	ITM rate threshold 0–10 (Expire only)
secret_key	str	No	Trader key for institutional/Prime accounts
lang	Language \| str	No	Language

Returns (OptionExerciseCheckResult)

Field	Type	Description
available_quantity	float	Exercisable quantity
position	float	Current option position
stk_position	float	Current underlying stock position
stk_position_change	float	Stock position change after exercise
stk_position_before	float	Stock position before exercise
stk_position_after	float	Stock position after exercise
symbol	str	Underlying stock symbol

Example

from tigeropen.common.consts import OptionExerciseType

# Exercise check (Exercise type — quantity, executing_date, is_force required)
result = client.check_option_exercise(
    contract_id=1234567890,
    exercise_type=OptionExerciseType.EXERCISE,
    quantity=1.0,
    executing_date='2025-06-20',
    is_force=False
)
print(f"available_quantity={result.available_quantity}")
print(f"stk_position_before={result.stk_position_before}")
print(f"stk_position_after={result.stk_position_after}")

# Expire type — set ITM rate (quantity required)
result = client.check_option_exercise(
    contract_id=1234567890,
    exercise_type=OptionExerciseType.EXPIRE,
    quantity=1.0,
    itm_rate=5
)

Response example

{
  "available_quantity": 10.0,
  "position": 10.0,
  "stk_position": 300.0,
  "stk_position_change": -100.0,
  "stk_position_before": 300.0,
  "stk_position_after": 200.0,
  "symbol": "AAPL"
}

Query Exercisable Positions

Method: TradeClient.get_option_exercise_positions()

Returns the list of option positions eligible for exercise or waive requests.

Parameters

Parameter	Type	Required	Description
exercise_type	OptionExerciseType \| str	Yes	Exercise type: `Exercise` / `Expire`
account	str	No	Trading account (defaults to config account)
secret_key	str	No	Trader key for institutional/Prime accounts
lang	Language \| str	No	Language

Returns (OptionExercisePositionPageResult)

Field	Type	Description
items	List[OptionExercisePosition]	Position list
page_num	int	Current page number
page_size	int	Page size
item_count	int	Total record count
page_count	int	Total page count

OptionExercisePosition fields

Field	Type	Description
contract_id	int	Option contract ID
symbol	str	Option contract symbol
stk_symbol	str	Underlying stock symbol
expire_date	str	Expiry date, format `yyyy-MM-dd`
strike	str	Strike price
call_put	str	`CALL` / `PUT`
market	str	Market
account_id	int	Account ID
position	float	Position quantity
available_quantity	float	Exercisable quantity

Example

result = client.get_option_exercise_positions(
    exercise_type=OptionExerciseType.EXERCISE
)
print(f"item_count={result.item_count}")
for pos in result.items:
    print(f"contract_id={pos.contract_id} symbol={pos.symbol} "
          f"expire_date={pos.expire_date} available_qty={pos.available_quantity}")

Response example

{
  "item_count": 4,
  "page_num": 1,
  "page_size": 10,
  "page_count": 1,
  "items": [
    {
      "contract_id": 1684414425,
      "symbol": "AAPL",
      "stk_symbol": "AAPL",
      "expire_date": "2026-04-17",
      "strike": "280.0",
      "call_put": "PUT",
      "market": "US",
      "account_id": 600021133765,
      "position": 10.0,
      "available_quantity": 10.0
    }
  ]
}

Submit Exercise Request

Method: TradeClient.submit_option_exercise()

Submits an early exercise or early waive request.

⚠️
Note

Call the exercise check API first to confirm the position impact before submitting

executing_date and is_force are only applicable to Exercise type and are required

itm_rate is only applicable to Expire type

To cancel after a successful submission, use the cancel exercise request API

Parameters

Parameter	Type	Required	Description
contract_id	int	Yes	Option contract ID
exercise_type	OptionExerciseType \| str	Yes	Exercise type: `Exercise` / `Expire`
quantity	float	Yes	Exercise quantity (> 0)
account	str	No	Trading account (defaults to config account)
executing_date	str	Required for Exercise	Execution date, format `yyyy-MM-dd`
is_force	bool	Required for Exercise	Whether to force exercise
itm_rate	int	No	ITM rate threshold 0–10 (Expire only)
secret_key	str	No	Trader key for institutional/Prime accounts
lang	Language \| str	No	Language

Returns

Returns True on success; raises ApiException on failure.

Example

# Early exercise
success = client.submit_option_exercise(
    contract_id=1234567890,
    exercise_type=OptionExerciseType.EXERCISE,
    quantity=1.0,
    executing_date='2025-06-20',
    is_force=False
)
print('Submitted successfully' if success else 'Submission failed')

# Early waive
success = client.submit_option_exercise(
    contract_id=1234567890,
    exercise_type=OptionExerciseType.EXPIRE,
    quantity=1.0
)

Query Exercise Records

Method: TradeClient.get_option_exercise_records()

Returns paginated exercise/waive request records.

Parameters

Parameter	Type	Required	Description
account	str	No	Trading account (defaults to config account)
page	int	No	Page number, starts from 1 (default 1)
size	int	No	Page size, 1–100 (default 20)
status	str	No	Status filter: `New` / `Cancel` / `Success` / `Fail`
exercise_type	OptionExerciseType \| str	No	Type filter: `Exercise` / `Expire`
symbol	str	No	Underlying symbol filter
order_by	str	No	Sort field: `symbol` / `expire_date` / `strike` / `is_call`
secret_key	str	No	Trader key for institutional/Prime accounts
lang	Language \| str	No	Language

Returns (OptionExercisePageResult)

Field	Type	Description
items	List[OptionExerciseRecord]	Record list
page_num	int	Current page number
page_size	int	Page size
item_count	int	Total record count
page_count	int	Total page count

OptionExerciseRecord fields

Field	Type	Description
id	int	Exercise record ID
contract_id	int	Option contract ID
symbol	str	Option contract symbol
stk_symbol	str	Underlying stock symbol
expire_date	str	Expiry date
strike	str	Strike price
call_put	str	`CALL` / `PUT`
type	str	`Exercise` / `Expire`
request_quantity	float	Requested quantity
quantity	float	Actual exercised quantity
status	str	Request status: `New` / `Cancel` / `Success` / `Fail`
executing_date	str	Execution date
itm_rate	int	ITM rate
is_force	bool	Force exercise flag
reason	str	Rejection reason (if any)
account_id	int	Account ID

Example

# Basic query
result = client.get_option_exercise_records(page=1, size=20)
print(f"item_count={result.item_count} page_count={result.page_count}")
for record in result.items:
    print(f"id={record.id} type={record.type} status={record.status}")

# With filters
result = client.get_option_exercise_records(
    exercise_type=OptionExerciseType.EXERCISE,
    order_by='symbol',
    page=1,
    size=20
)

Response example

{
  "item_count": 19,
  "page_num": 1,
  "page_size": 10,
  "page_count": 2,
  "items": [
    {
      "id": 315,
      "contract_id": 2701923713,
      "symbol": "AAPL",
      "stk_symbol": "AAPL",
      "expire_date": "2026-06-05",
      "strike": "305.0",
      "call_put": "PUT",
      "type": "Exercise",
      "request_quantity": 1.0,
      "quantity": 0.0,
      "status": "Cancel",
      "executing_date": "2026-06-01",
      "itm_rate": 0,
      "is_force": false,
      "reason": "Cancelled by manual",
      "account_id": 600021133765
    }
  ]
}

Cancel Exercise Request

Method: TradeClient.cancel_option_exercise()

Cancels a pending exercise request.

Parameters

Parameter	Type	Required	Description
exercise_id	int	Yes	Exercise record ID (from `get_option_exercise_records`)
account	str	No	Trading account (defaults to config account)
secret_key	str	No	Trader key for institutional/Prime accounts
lang	Language \| str	No	Language

Returns

Returns True on success; raises ApiException on failure.

Example

success = client.cancel_option_exercise(exercise_id=record_id)
print('Cancelled successfully' if success else 'Cancellation failed')