期权行权

概述

期权行权接口自 v0.4.2 起提供以下功能:

  • 行权检验:预估行权或放弃行权后正股持仓的变化
  • 查询可行权持仓:获取可提交行权/放弃行权申请的期权持仓列表
  • 提交行权申请:提交提前行权或提前放弃行权申请
  • 查询行权记录:分页查询已提交的行权申请历史
  • 撤销行权申请:撤销尚未执行的行权申请

行权类型(OptionExerciseType)

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

行权检验

对应请求类:OptionExerciseCheckRequest

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

参数

参数类型必填说明
accountstring交易账户
contractIdlong期权合约 ID
typestring行权类型:Exercise / Expire
quantitydouble行权数量(> 0)
executingDatestringExercise 必填行权执行日期,格式 yyyy-MM-dd
isForcebooleanExercise 必填是否强制行权
itmRateint价内率阈值 0–10(仅 Expire 类型可用)
secretKeystring机构账户交易员密钥

返回(OptionExerciseCheckItem)

字段类型说明
availableQuantitydouble可行权数量
positiondouble当前期权持仓
stkPositiondouble正股当前持仓
stkPositionChangedouble行权后正股持仓变化量
stkPositionBeforedouble行权前正股持仓
stkPositionAfterdouble行权后正股持仓
symbolstring正股代码

示例

// 行权检验(Exercise 类型,quantity/executingDate/isForce 必填)
OptionExerciseCheckRequest request =
    OptionExerciseCheckRequest.buildRequest(account, contractId, OptionExerciseType.Exercise)
        .setQuantity(1.0)
        .setExecutingDate("2025-06-20")
        .setIsForce(false);
OptionExerciseCheckResponse response = client.execute(request);
if (response.isSuccess()) {
    OptionExerciseCheckItem item = response.getItem();
    System.out.println("availableQuantity=" + item.getAvailableQuantity()
        + " stkPositionBefore=" + item.getStkPositionBefore()
        + " stkPositionAfter=" + item.getStkPositionAfter());
} else {
    System.out.println("Error: " + response.getMessage());
}

// 行权检验(Expire 类型,quantity 必填,可设置价内率)
OptionExerciseCheckRequest expireCheck =
    OptionExerciseCheckRequest.buildRequest(account, contractId, OptionExerciseType.Expire)
        .setQuantity(1.0)
        .setItmRate(5);
OptionExerciseCheckResponse expireResp = client.execute(expireCheck);

返回示例

{
  "availableQuantity": 10.0,
  "position": 10.0,
  "stkPosition": 300.0,
  "stkPositionChange": -100.0,
  "stkPositionBefore": 300.0,
  "stkPositionAfter": 200.0,
  "symbol": "AAPL"
}

查询可行权持仓

对应请求类:OptionExercisePositionRequest

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

参数

参数类型必填说明
accountstring交易账户
typestring行权类型:Exercise / Expire
secretKeystring机构账户交易员密钥

返回(OptionExercisePositionPageItem)

分页 wrapper,包含:

字段类型说明
pageNumint当前页码
pageSizeint每页数量
itemCountint总记录数
pageCountint总页数
itemsList<OptionExercisePositionItem>持仓列表

OptionExercisePositionItem 字段

字段类型说明
contractIdlong期权合约 ID
symbolstring期权合约代码
stkSymbolstring正股代码
expireDatestring到期日,格式 yyyy-MM-dd
strikestring行权价
callPutstringCALL / PUT
marketstring市场
accountIdlong账户 ID
positiondouble持仓数量
availableQuantitydouble可行权数量

示例

OptionExercisePositionRequest request =
    OptionExercisePositionRequest.buildRequest(account, OptionExerciseType.Exercise);
OptionExercisePositionResponse response = client.execute(request);
if (response.isSuccess()) {
    OptionExercisePositionPageItem page = response.getItem();
    System.out.println("itemCount=" + page.getItemCount());
    for (OptionExercisePositionItem item : page.getItems()) {
        System.out.println("contractId=" + item.getContractId()
            + " symbol=" + item.getSymbol()
            + " expireDate=" + item.getExpireDate()
            + " availableQty=" + item.getAvailableQuantity());
    }
} else {
    System.out.println("Error: " + response.getMessage());
}

返回示例

{
  "itemCount": 4,
  "pageNum": 1,
  "pageSize": 10,
  "pageCount": 1,
  "items": [
    {
      "contractId": 1684414425,
      "symbol": "AAPL",
      "stkSymbol": "AAPL",
      "expireDate": "2026-04-17",
      "strike": "280.0",
      "callPut": "PUT",
      "market": "US",
      "accountId": 600021133765,
      "position": 10.0,
      "availableQuantity": 10.0
    }
  ]
}

提交行权申请

对应请求类:OptionExerciseSubmitRequest

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

⚠️

注意

  • 提交前建议先调用行权检验接口确认持仓变化
  • executingDateisForce 仅在 Exercise 类型时有效
  • itmRate 仅在 Expire 类型时有效
  • 提交成功后如需撤销,请使用撤销行权申请接口

参数(Exercise 类型)

参数类型必填说明
accountstring交易账户
contractIdlong期权合约 ID
quantitydouble行权数量
executingDatestring行权执行日期,格式 yyyy-MM-dd
isForceboolean是否强制行权
secretKeystring机构账户交易员密钥

参数(Expire 类型)

参数类型必填说明
accountstring交易账户
contractIdlong期权合约 ID
quantitydouble放弃行权数量
itmRateint价内率阈值 0–10
secretKeystring机构账户交易员密钥

示例

// 提前行权
OptionExerciseSubmitRequest exerciseRequest =
    OptionExerciseSubmitRequest.buildExerciseRequest(
        account, contractId, 1.0, "2025-06-20", false);
OptionExerciseSubmitResponse exerciseResp = client.execute(exerciseRequest);
System.out.println(exerciseResp.isSuccess() ? "提交成功" : "提交失败: " + exerciseResp.getMessage());

// 提前放弃行权
OptionExerciseSubmitRequest expireRequest =
    OptionExerciseSubmitRequest.buildExpireRequest(account, contractId, 1.0, null);
OptionExerciseSubmitResponse expireResp = client.execute(expireRequest);
System.out.println(expireResp.isSuccess() ? "提交成功" : "提交失败: " + expireResp.getMessage());

查询行权记录

对应请求类:OptionExerciseRecordRequest

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

参数

参数类型必填说明
accountstring交易账户
pageint页码,从 1 开始
sizeint每页数量,1–100
statusstring行权状态过滤,如 New
typestring行权类型过滤:Exercise / Expire
symbolstring正股代码过滤
orderBystring排序字段:symbol / expire_date / strike / is_call
secretKeystring机构账户交易员密钥

返回(OptionExerciseRecordPageItem)

分页 wrapper,items 为 List<OptionExerciseRecordItem>

OptionExerciseRecordItem 字段

字段类型说明
idlong行权申请记录 ID
contractIdlong期权合约 ID
symbolstring期权合约代码
stkSymbolstring正股代码
expireDatestring到期日
strikestring行权价
callPutstringCALL / PUT
typestringExercise / Expire
requestQuantitydouble申请数量
quantitydouble实际行权数量
statusstring申请状态
executingDatestring行权执行日期
itmRateint价内率
isForceboolean是否强制行权
reasonstring拒绝原因(如有)
accountIdlong账户 ID

示例

// 基本查询
OptionExerciseRecordRequest request =
    OptionExerciseRecordRequest.buildRequest(account, 1, 20);
OptionExerciseRecordResponse response = client.execute(request);
if (response.isSuccess()) {
    OptionExerciseRecordPageItem page = response.getItem();
    System.out.println("itemCount=" + page.getItemCount() + " pageCount=" + page.getPageCount());
    for (OptionExerciseRecordItem item : page.getItems()) {
        System.out.println("id=" + item.getId() + " type=" + item.getType()
            + " status=" + item.getStatus());
    }
}

// 带过滤条件
OptionExerciseRecordRequest filtered =
    OptionExerciseRecordRequest.buildRequest(account, 1, 20)
        .setType(OptionExerciseType.Exercise.name())
        .setOrderBy("symbol");

返回示例

{
  "itemCount": 19,
  "pageNum": 1,
  "pageSize": 10,
  "pageCount": 2,
  "items": [
    {
      "id": 315,
      "contractId": 2701923713,
      "symbol": "AAPL",
      "stkSymbol": "AAPL",
      "expireDate": "2026-06-05",
      "strike": "305.0",
      "callPut": "PUT",
      "type": "Exercise",
      "requestQuantity": 1.0,
      "quantity": 0.0,
      "status": "Cancel",
      "executingDate": "2026-06-01",
      "itmRate": 0,
      "isForce": false,
      "reason": "Cancelled by manual",
      "accountId": 600021133765
    }
  ]
}

撤销行权申请

对应请求类:OptionExerciseCancelRequest

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

参数

参数类型必填说明
accountstring交易账户
idlong行权申请记录 ID(从查询行权记录接口获取)
secretKeystring机构账户交易员密钥

示例

OptionExerciseCancelRequest request =
    OptionExerciseCancelRequest.buildRequest(account, recordId);
OptionExerciseCancelResponse response = client.execute(request);
System.out.println(response.isSuccess() ? "撤销成功" : "撤销失败: " + response.getMessage());