# Positions ## Get Positions `PositionGetPositionsResponse v1().positions().getPositions(PositionGetPositionsParamsparams = PositionGetPositionsParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` **get** `/v1/accounts/{account_id}/positions` Retrieves all positions for the specified trading account. ### Parameters - `PositionGetPositionsParams params` - `Optional accountId` - `Optional> instrumentIds` Comma-separated OEMS instrument UUIDs - `Optional pageSize` The number of items to return per page. Only used when page_token is not provided. - `Optional pageToken` Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored. - `Optional sortBy` Field to sort by - `SYMBOL("SYMBOL")` - `INSTRUMENT_TYPE("INSTRUMENT_TYPE")` - `QUANTITY("QUANTITY")` - `MARKET_VALUE("MARKET_VALUE")` - `POSITION_TYPE("POSITION_TYPE")` - `UNREALIZED_PNL("UNREALIZED_PNL")` - `DAILY_UNREALIZED_PNL("DAILY_UNREALIZED_PNL")` - `Optional sortDirection` Sort direction - `ASC("ASC")` - `DESC("DESC")` ### Returns - `class PositionGetPositionsResponse:` - `List data` - `long accountId` The account this position belongs to - `String availableQuantity` The quantity of a position that is free to be operated on. - `String instrumentId` OEMS instrument UUID - `SecurityType instrumentType` Type of security - `COMMON_STOCK("COMMON_STOCK")` - `PREFERRED_STOCK("PREFERRED_STOCK")` - `OPTION("OPTION")` - `CASH("CASH")` - `OTHER("OTHER")` - `String marketValue` The current market value of the position - `PositionType positionType` The type of position - `LONG("LONG")` - `SHORT("SHORT")` - `LONG_CALL("LONG_CALL")` - `SHORT_CALL("SHORT_CALL")` - `LONG_PUT("LONG_PUT")` - `SHORT_PUT("SHORT_PUT")` - `String quantity` The number of shares or contracts. Can be positive (long) or negative (short) - `String symbol` The trading symbol for the instrument - `Optional avgPrice` The average price paid per share or contract for this position - `Optional closingPrice` The closing price used to value the position for the last trading day - `Optional closingPriceDate` The market date associated with `closing_price` - `Optional costBasis` The total cost basis for this position - `Optional dailyUnrealizedPnl` The unrealized profit or loss for this position relative to the previous close - `Optional dailyUnrealizedPnlPct` The unrealized profit/loss for the position for the current day, expressed as a percentage of the baseline value (range: 0-100). - `Optional instrumentPrice` The current market price of the instrument - `Optional underlyingInstrumentId` OEMS instrument identifier of the underlying instrument, if resolvable - `Optional unrealizedPnl` The total unrealized profit or loss for this position based on current market value - `Optional unrealizedPnlPct` The unrealized profit/loss for the position, expressed as a percentage of the position's cost basis (range: 0-100). ### Example ```java package com.clear_street.api.example; import com.clear_street.api.client.ClearStreetClient; import com.clear_street.api.client.okhttp.ClearStreetOkHttpClient; import com.clear_street.api.models.v1.positions.PositionGetPositionsParams; import com.clear_street.api.models.v1.positions.PositionGetPositionsResponse; public final class Main { private Main() {} public static void main(String[] args) { ClearStreetClient client = ClearStreetOkHttpClient.builder() .fromEnv() .apiKey("My API Key") .build(); PositionGetPositionsResponse response = client.v1().positions().getPositions(0L); } } ``` #### Response ```json { "data": [ { "account_id": 19816, "available_quantity": "100", "avg_price": "145.00", "closing_price": "150.50", "closing_price_date": "2025-10-31", "cost_basis": "14500.00", "instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8", "instrument_price": "151.00", "instrument_type": "COMMON_STOCK", "market_value": "15050.00", "position_type": "LONG", "quantity": "100", "symbol": "AAPL", "unrealized_pnl": "550.00" }, { "account_id": 19816, "available_quantity": "100", "avg_price": "180.00", "closing_price": "180.00", "closing_price_date": "2025-10-30", "cost_basis": "-9000.00", "instrument_id": "d4d5d6d7-e4e5-f4f5-a4a5-a6a7a8a9aaab", "instrument_price": "178.50", "instrument_type": "COMMON_STOCK", "market_value": "-9000.00", "position_type": "SHORT", "quantity": "-50", "symbol": "TSLA", "unrealized_pnl": "75.00" }, { "account_id": 19816, "available_quantity": "100", "avg_price": "2.50", "closing_price": "2.70", "closing_price_date": "2025-10-30", "cost_basis": "2500.00", "instrument_id": "e5e6e7e8-f5f6-a5a6-b5b6-b7b8b9babcbe", "instrument_price": "2.72", "instrument_type": "OPTION", "market_value": "2700.00", "position_type": "LONG_CALL", "quantity": "10", "symbol": "AAPL250117C00190000", "underlying_instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8", "unrealized_pnl": "200.00" } ], "error": null, "metadata": { "next_page_token": "cGFnZT0yJmxhc3Rfc3ltYm9sPVRTM0E=", "page_number": 1, "request_id": "3f4a5b6c-7d8e-9f0a-1b2c-3d4e5f6a7b8c", "total_items": 25, "total_pages": 3 } } ``` ## Close Positions `PositionClosePositionsResponse v1().positions().closePositions(PositionClosePositionsParamsparams = PositionClosePositionsParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` **delete** `/v1/accounts/{account_id}/positions` Delete all positions within an account. Closes all positions for the specified trading account. ### Parameters - `PositionClosePositionsParams params` - `Optional accountId` - `Optional cancelOrders` Whether to cancel existing open orders for the position before submitting closing orders. ### Returns - `class PositionClosePositionsResponse:` - `List data` - `String id` Engine-assigned unique identifier for this order (UUID). - `long accountId` Account placing the order - `String clientOrderId` Client-provided identifier echoed back (FIX tag 11). - `LocalDateTime createdAt` Timestamp when order was created (UTC) - `String filledQuantity` Cumulative filled quantity - `String instrumentId` OEMS instrument UUID for the traded instrument. - `SecurityType instrumentType` Type of security - `COMMON_STOCK("COMMON_STOCK")` - `PREFERRED_STOCK("PREFERRED_STOCK")` - `OPTION("OPTION")` - `CASH("CASH")` - `OTHER("OTHER")` - `String leavesQuantity` Remaining unfilled quantity - `OrderType orderType` Type of order (MARKET, LIMIT, etc.) - `MARKET("MARKET")` - `LIMIT("LIMIT")` - `STOP("STOP")` - `STOP_LIMIT("STOP_LIMIT")` - `TRAILING_STOP("TRAILING_STOP")` - `TRAILING_STOP_LIMIT("TRAILING_STOP_LIMIT")` - `OTHER("OTHER")` - `String quantity` Total order quantity - `Side side` Side of the order (BUY, SELL, SELL_SHORT) - `BUY("BUY")` - `SELL("SELL")` - `SELL_SHORT("SELL_SHORT")` - `OTHER("OTHER")` - `OrderStatus status` Current status of the order - `PENDING_NEW("PENDING_NEW")` - `NEW("NEW")` - `PARTIALLY_FILLED("PARTIALLY_FILLED")` - `FILLED("FILLED")` - `CANCELED("CANCELED")` - `REJECTED("REJECTED")` - `EXPIRED("EXPIRED")` - `PENDING_CANCEL("PENDING_CANCEL")` - `PENDING_REPLACE("PENDING_REPLACE")` - `REPLACED("REPLACED")` - `DONE_FOR_DAY("DONE_FOR_DAY")` - `STOPPED("STOPPED")` - `SUSPENDED("SUSPENDED")` - `CALCULATED("CALCULATED")` - `OTHER("OTHER")` - `String symbol` Trading symbol - `TimeInForce timeInForce` Time in force instruction - `DAY("DAY")` - `GOOD_TILL_CANCEL("GOOD_TILL_CANCEL")` - `IMMEDIATE_OR_CANCEL("IMMEDIATE_OR_CANCEL")` - `FILL_OR_KILL("FILL_OR_KILL")` - `GOOD_TILL_DATE("GOOD_TILL_DATE")` - `AT_THE_OPENING("AT_THE_OPENING")` - `AT_THE_CLOSE("AT_THE_CLOSE")` - `GOOD_TILL_CROSSING("GOOD_TILL_CROSSING")` - `GOOD_THROUGH_CROSSING("GOOD_THROUGH_CROSSING")` - `AT_CROSSING("AT_CROSSING")` - `OTHER("OTHER")` - `LocalDateTime updatedAt` Timestamp of the most recent update (UTC) - `String venue` MIC code of the venue where the order is routed - `Optional averageFillPrice` Average fill price across all executions - `Optional> details` Contains execution, rejection or cancellation details, if any - `Optional expiresAt` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `Optional extendedHours` Whether the order is eligible for extended-hours trading. - `Optional limitOffset` Limit offset for trailing stop-limit orders (signed) - `Optional limitPrice` Limit price (for LIMIT and STOP_LIMIT orders) - `Optional queueState` Parent order queue state, present when the order is awaiting release or released. - `AWAITING_RELEASE("AWAITING_RELEASE")` - `RELEASED("RELEASED")` - `Optional releasesAt` Scheduled release time for orders awaiting release. - `Optional stopPrice` Stop price (for STOP and STOP_LIMIT orders) - `Optional trailingLimitPx` Current trailing limit price computed by the trailing strategy - `Optional trailingOffset` Trailing offset amount for trailing orders - `Optional trailingOffsetType` Trailing offset type for trailing orders - `PRICE("PRICE")` - `BPS("BPS")` - `Optional trailingStopPx` Current trailing stop price computed by the trailing strategy - `Optional trailingWatermarkPx` Trailing watermark price for trailing orders - `Optional trailingWatermarkTs` Trailing watermark timestamp for trailing orders - `Optional underlyingInstrumentId` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Example ```java package com.clear_street.api.example; import com.clear_street.api.client.ClearStreetClient; import com.clear_street.api.client.okhttp.ClearStreetOkHttpClient; import com.clear_street.api.models.v1.positions.PositionClosePositionsParams; import com.clear_street.api.models.v1.positions.PositionClosePositionsResponse; public final class Main { private Main() {} public static void main(String[] args) { ClearStreetClient client = ClearStreetOkHttpClient.builder() .fromEnv() .apiKey("My API Key") .build(); PositionClosePositionsResponse response = client.v1().positions().closePositions(0L); } } ``` #### Response ```json { "data": [ { "account_id": 19816, "average_fill_price": null, "created_at": "2025-10-03T14:01:15.000000000Z", "filled_quantity": "0", "id": "019c0b57-0850-7b0b-8a2c-5ee3fb5a5876", "instrument_id": "c3c4c5c6-d3d4-e3e4-f3f4-f5f6f7f8f9fa", "instrument_type": "COMMON_STOCK", "leaves_quantity": "25", "limit_price": null, "order_type": "MARKET", "quantity": "25", "side": "SELL", "status": "PENDING_NEW", "stop_price": null, "symbol": "GOOG", "time_in_force": "DAY", "updated_at": "2025-10-03T14:01:15.000000000Z", "venue": "XNMS" } ], "error": null, "metadata": { "request_id": "3f4a5b6c-7d8e-9f0a-1b2c-3d4e5f6a7b8c" } } ``` ## Close Position `PositionClosePositionResponse v1().positions().closePosition(PositionClosePositionParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` **delete** `/v1/accounts/{account_id}/positions/{instrument_id}` Delete a position within an account for an instrument. Retrieves orders generated to close the position. ### Parameters - `PositionClosePositionParams params` - `long accountId` - `Optional instrumentId` OEMS instrument UUID - `Optional cancelOrders` Whether to cancel existing open orders for the position before submitting closing orders. ### Returns - `class PositionClosePositionResponse:` - `List data` - `String id` Engine-assigned unique identifier for this order (UUID). - `long accountId` Account placing the order - `String clientOrderId` Client-provided identifier echoed back (FIX tag 11). - `LocalDateTime createdAt` Timestamp when order was created (UTC) - `String filledQuantity` Cumulative filled quantity - `String instrumentId` OEMS instrument UUID for the traded instrument. - `SecurityType instrumentType` Type of security - `COMMON_STOCK("COMMON_STOCK")` - `PREFERRED_STOCK("PREFERRED_STOCK")` - `OPTION("OPTION")` - `CASH("CASH")` - `OTHER("OTHER")` - `String leavesQuantity` Remaining unfilled quantity - `OrderType orderType` Type of order (MARKET, LIMIT, etc.) - `MARKET("MARKET")` - `LIMIT("LIMIT")` - `STOP("STOP")` - `STOP_LIMIT("STOP_LIMIT")` - `TRAILING_STOP("TRAILING_STOP")` - `TRAILING_STOP_LIMIT("TRAILING_STOP_LIMIT")` - `OTHER("OTHER")` - `String quantity` Total order quantity - `Side side` Side of the order (BUY, SELL, SELL_SHORT) - `BUY("BUY")` - `SELL("SELL")` - `SELL_SHORT("SELL_SHORT")` - `OTHER("OTHER")` - `OrderStatus status` Current status of the order - `PENDING_NEW("PENDING_NEW")` - `NEW("NEW")` - `PARTIALLY_FILLED("PARTIALLY_FILLED")` - `FILLED("FILLED")` - `CANCELED("CANCELED")` - `REJECTED("REJECTED")` - `EXPIRED("EXPIRED")` - `PENDING_CANCEL("PENDING_CANCEL")` - `PENDING_REPLACE("PENDING_REPLACE")` - `REPLACED("REPLACED")` - `DONE_FOR_DAY("DONE_FOR_DAY")` - `STOPPED("STOPPED")` - `SUSPENDED("SUSPENDED")` - `CALCULATED("CALCULATED")` - `OTHER("OTHER")` - `String symbol` Trading symbol - `TimeInForce timeInForce` Time in force instruction - `DAY("DAY")` - `GOOD_TILL_CANCEL("GOOD_TILL_CANCEL")` - `IMMEDIATE_OR_CANCEL("IMMEDIATE_OR_CANCEL")` - `FILL_OR_KILL("FILL_OR_KILL")` - `GOOD_TILL_DATE("GOOD_TILL_DATE")` - `AT_THE_OPENING("AT_THE_OPENING")` - `AT_THE_CLOSE("AT_THE_CLOSE")` - `GOOD_TILL_CROSSING("GOOD_TILL_CROSSING")` - `GOOD_THROUGH_CROSSING("GOOD_THROUGH_CROSSING")` - `AT_CROSSING("AT_CROSSING")` - `OTHER("OTHER")` - `LocalDateTime updatedAt` Timestamp of the most recent update (UTC) - `String venue` MIC code of the venue where the order is routed - `Optional averageFillPrice` Average fill price across all executions - `Optional> details` Contains execution, rejection or cancellation details, if any - `Optional expiresAt` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `Optional extendedHours` Whether the order is eligible for extended-hours trading. - `Optional limitOffset` Limit offset for trailing stop-limit orders (signed) - `Optional limitPrice` Limit price (for LIMIT and STOP_LIMIT orders) - `Optional queueState` Parent order queue state, present when the order is awaiting release or released. - `AWAITING_RELEASE("AWAITING_RELEASE")` - `RELEASED("RELEASED")` - `Optional releasesAt` Scheduled release time for orders awaiting release. - `Optional stopPrice` Stop price (for STOP and STOP_LIMIT orders) - `Optional trailingLimitPx` Current trailing limit price computed by the trailing strategy - `Optional trailingOffset` Trailing offset amount for trailing orders - `Optional trailingOffsetType` Trailing offset type for trailing orders - `PRICE("PRICE")` - `BPS("BPS")` - `Optional trailingStopPx` Current trailing stop price computed by the trailing strategy - `Optional trailingWatermarkPx` Trailing watermark price for trailing orders - `Optional trailingWatermarkTs` Trailing watermark timestamp for trailing orders - `Optional underlyingInstrumentId` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Example ```java package com.clear_street.api.example; import com.clear_street.api.client.ClearStreetClient; import com.clear_street.api.client.okhttp.ClearStreetOkHttpClient; import com.clear_street.api.models.v1.positions.PositionClosePositionParams; import com.clear_street.api.models.v1.positions.PositionClosePositionResponse; public final class Main { private Main() {} public static void main(String[] args) { ClearStreetClient client = ClearStreetOkHttpClient.builder() .fromEnv() .apiKey("My API Key") .build(); PositionClosePositionParams params = PositionClosePositionParams.builder() .accountId(0L) .instrumentId("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e") .build(); PositionClosePositionResponse response = client.v1().positions().closePosition(params); } } ``` #### Response ```json { "data": [ { "account_id": 19816, "average_fill_price": null, "created_at": "2025-10-03T14:01:15.000000000Z", "filled_quantity": "0", "id": "019c0b56-2119-7482-a80f-5a2a316524d9", "instrument_id": "c3c4c5c6-d3d4-e3e4-f3f4-f5f6f7f8f9fa", "instrument_type": "COMMON_STOCK", "leaves_quantity": "25", "limit_price": null, "order_type": "MARKET", "quantity": "25", "side": "SELL", "status": "PENDING_NEW", "stop_price": null, "symbol": "GOOG", "time_in_force": "DAY", "updated_at": "2025-10-03T14:01:15.000000000Z", "venue": "XNMS" } ], "error": null, "metadata": { "request_id": "3f4a5b6c-7d8e-9f0a-1b2c-3d4e5f6a7b8c" } } ``` ## List Position Instructions `PositionGetPositionInstructionsResponse v1().positions().getPositionInstructions(PositionGetPositionInstructionsParamsparams = PositionGetPositionInstructionsParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` **get** `/v1/accounts/{account_id}/positions/instructions` Returns the current lifecycle state of the account's position instructions. Optionally filter by a specific contract. ### Parameters - `PositionGetPositionInstructionsParams params` - `Optional accountId` - `Optional instrumentId` Limit results to a single contract. Accepts the instrument id or the OSI symbol. ### Returns - `class PositionGetPositionInstructionsResponse:` - `List data` - `String id` Server-assigned id. Used as the path parameter on cancel. - `long accountId` Account the instruction belongs to. - `String instructionId` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `PositionInstructionType instructionType` The action this instruction requests. - `EXERCISE("EXERCISE")` - `DO_NOT_EXERCISE("DO_NOT_EXERCISE")` - `CONTRARY_EXERCISE("CONTRARY_EXERCISE")` - `String instrumentId` Identifier of the options contract this instruction acts on. - `String quantity` Number of contracts included in the instruction. - `PositionInstructionStatus status` Current lifecycle status. - `SENT("SENT")` - `ACCEPTED("ACCEPTED")` - `REJECTED("REJECTED")` - `ENGINE_REJECTED("ENGINE_REJECTED")` - `CANCEL_REQUESTED("CANCEL_REQUESTED")` - `CANCELLED("CANCELLED")` - `CANCEL_FAILED("CANCEL_FAILED")` - `UNKNOWN("UNKNOWN")` - `String symbol` Options symbol (OSI) for display. - `Optional acceptedQuantity` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `Optional createdAt` When the instruction was first accepted by the service. - `Optional rejectionReason` Human-readable explanation populated on any non-success terminal status — `REJECTED`, `ENGINE_REJECTED`, or `CANCEL_FAILED`. On a `207 Multi-Status` batch submit the top-level `error` field summarizes the batch; per-row detail continues to live here. - `Optional updatedAt` When the instruction's lifecycle state last changed. ### Example ```java package com.clear_street.api.example; import com.clear_street.api.client.ClearStreetClient; import com.clear_street.api.client.okhttp.ClearStreetOkHttpClient; import com.clear_street.api.models.v1.positions.PositionGetPositionInstructionsParams; import com.clear_street.api.models.v1.positions.PositionGetPositionInstructionsResponse; public final class Main { private Main() {} public static void main(String[] args) { ClearStreetClient client = ClearStreetOkHttpClient.builder() .fromEnv() .apiKey("My API Key") .build(); PositionGetPositionInstructionsResponse response = client.v1().positions().getPositionInstructions(0L); } } ``` #### Response ```json { "metadata": { "request_id": "request_id", "next_page_token": "U3RhaW5sZXNzIHJvY2tz", "page_number": 0, "previous_page_token": "U3RhaW5sZXNzIHJvY2tz", "total_items": 0, "total_pages": 0 }, "error": { "code": 400, "message": "Order quantity must be greater than zero", "details": [ { "foo": "bar" } ] }, "data": [ { "id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02", "account_id": 122503, "instruction_id": "ui-20260424-001", "instruction_type": "EXERCISE", "instrument_id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02", "quantity": "1", "status": "SENT", "symbol": "AAPL 280121C00195000", "accepted_quantity": null, "created_at": "2026-04-24T14:30:00Z", "rejection_reason": null, "updated_at": "2026-04-24T14:30:00Z" } ] } ``` ## Submit Position Instructions `PositionSubmitPositionInstructionsResponse v1().positions().submitPositionInstructions(PositionSubmitPositionInstructionsParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` **post** `/v1/accounts/{account_id}/positions/instructions` Submit one or more position instructions (Exercise, Do-Not-Exercise, Contrary Exercise Advice) against the account. Batch semantics: - **All rows accepted** → `200 OK`. Every row is in `data` with `status = SENT`. - **Partial success** → `207 Multi-Status`. `data` contains every row; rejected rows carry `status = ENGINE_REJECTED` (or `REJECTED`) and `rejection_reason`. The top-level `error` summarizes the batch failure. - **All rows rejected** → `4xx`/`5xx` error response. The HTTP status reflects the underlying cause: `409` for duplicate `instruction_id`, `400` for validation failures such as DNE/CEA on a non-expiry day, `503` if the clearing service is unavailable. No `data` is returned. Pre-flight validation (unknown `instrument_id`, unencodable `quantity`) short-circuits the whole batch with a `4xx` before any row is submitted. ### Parameters - `PositionSubmitPositionInstructionsParams params` - `Optional accountId` - `List instructions` - `PositionInstructionType instructionType` The action to take. - `EXERCISE("EXERCISE")` - `DO_NOT_EXERCISE("DO_NOT_EXERCISE")` - `CONTRARY_EXERCISE("CONTRARY_EXERCISE")` - `String instrumentId` Identifier of the options contract to act on. Unknown ids return 404. - `String quantity` Number of contracts to include in the instruction. - `Optional instructionId` Caller-supplied idempotency key. Echoed on the response. The server generates a unique id when omitted. ### Returns - `class PositionSubmitPositionInstructionsResponse:` - `List data` - `String id` Server-assigned id. Used as the path parameter on cancel. - `long accountId` Account the instruction belongs to. - `String instructionId` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `PositionInstructionType instructionType` The action this instruction requests. - `EXERCISE("EXERCISE")` - `DO_NOT_EXERCISE("DO_NOT_EXERCISE")` - `CONTRARY_EXERCISE("CONTRARY_EXERCISE")` - `String instrumentId` Identifier of the options contract this instruction acts on. - `String quantity` Number of contracts included in the instruction. - `PositionInstructionStatus status` Current lifecycle status. - `SENT("SENT")` - `ACCEPTED("ACCEPTED")` - `REJECTED("REJECTED")` - `ENGINE_REJECTED("ENGINE_REJECTED")` - `CANCEL_REQUESTED("CANCEL_REQUESTED")` - `CANCELLED("CANCELLED")` - `CANCEL_FAILED("CANCEL_FAILED")` - `UNKNOWN("UNKNOWN")` - `String symbol` Options symbol (OSI) for display. - `Optional acceptedQuantity` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `Optional createdAt` When the instruction was first accepted by the service. - `Optional rejectionReason` Human-readable explanation populated on any non-success terminal status — `REJECTED`, `ENGINE_REJECTED`, or `CANCEL_FAILED`. On a `207 Multi-Status` batch submit the top-level `error` field summarizes the batch; per-row detail continues to live here. - `Optional updatedAt` When the instruction's lifecycle state last changed. ### Example ```java package com.clear_street.api.example; import com.clear_street.api.client.ClearStreetClient; import com.clear_street.api.client.okhttp.ClearStreetOkHttpClient; import com.clear_street.api.models.v1.positions.PositionInstructionType; import com.clear_street.api.models.v1.positions.PositionSubmitPositionInstructionsParams; import com.clear_street.api.models.v1.positions.PositionSubmitPositionInstructionsResponse; public final class Main { private Main() {} public static void main(String[] args) { ClearStreetClient client = ClearStreetOkHttpClient.builder() .fromEnv() .apiKey("My API Key") .build(); PositionSubmitPositionInstructionsParams params = PositionSubmitPositionInstructionsParams.builder() .accountId(0L) .addInstruction(PositionSubmitPositionInstructionsParams.Instruction.builder() .instructionType(PositionInstructionType.EXERCISE) .instrumentId("0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02") .quantity("1") .build()) .build(); PositionSubmitPositionInstructionsResponse response = client.v1().positions().submitPositionInstructions(params); } } ``` #### Response ```json { "data": [ { "account_id": 122503, "id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02", "instruction_id": "ui-20260424-001", "instruction_type": "EXERCISE", "instrument_id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e01", "quantity": "1", "status": "SENT", "symbol": "AAPL 280121C00195000" } ], "metadata": { "request_id": "0a5c9ebf-a9a7-4f2d-9c7e-f2b5f0b1bd01" } } ``` ## Cancel Position Instruction `PositionCancelPositionInstructionResponse v1().positions().cancelPositionInstruction(PositionCancelPositionInstructionParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` **delete** `/v1/accounts/{account_id}/positions/instructions/{instruction_id}` Cancel an outstanding position instruction by its server-assigned `id`. Returns the updated instruction with status `CANCEL_REQUESTED`. The terminal `CANCELLED` or `CANCEL_FAILED` state arrives asynchronously and is observable via subsequent GETs. ### Parameters - `PositionCancelPositionInstructionParams params` - `long accountId` - `Optional instructionId` ### Returns - `class PositionCancelPositionInstructionResponse:` - `PositionInstruction data` A position instruction and its current lifecycle state. - `String id` Server-assigned id. Used as the path parameter on cancel. - `long accountId` Account the instruction belongs to. - `String instructionId` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `PositionInstructionType instructionType` The action this instruction requests. - `EXERCISE("EXERCISE")` - `DO_NOT_EXERCISE("DO_NOT_EXERCISE")` - `CONTRARY_EXERCISE("CONTRARY_EXERCISE")` - `String instrumentId` Identifier of the options contract this instruction acts on. - `String quantity` Number of contracts included in the instruction. - `PositionInstructionStatus status` Current lifecycle status. - `SENT("SENT")` - `ACCEPTED("ACCEPTED")` - `REJECTED("REJECTED")` - `ENGINE_REJECTED("ENGINE_REJECTED")` - `CANCEL_REQUESTED("CANCEL_REQUESTED")` - `CANCELLED("CANCELLED")` - `CANCEL_FAILED("CANCEL_FAILED")` - `UNKNOWN("UNKNOWN")` - `String symbol` Options symbol (OSI) for display. - `Optional acceptedQuantity` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `Optional createdAt` When the instruction was first accepted by the service. - `Optional rejectionReason` Human-readable explanation populated on any non-success terminal status — `REJECTED`, `ENGINE_REJECTED`, or `CANCEL_FAILED`. On a `207 Multi-Status` batch submit the top-level `error` field summarizes the batch; per-row detail continues to live here. - `Optional updatedAt` When the instruction's lifecycle state last changed. ### Example ```java package com.clear_street.api.example; import com.clear_street.api.client.ClearStreetClient; import com.clear_street.api.client.okhttp.ClearStreetOkHttpClient; import com.clear_street.api.models.v1.positions.PositionCancelPositionInstructionParams; import com.clear_street.api.models.v1.positions.PositionCancelPositionInstructionResponse; public final class Main { private Main() {} public static void main(String[] args) { ClearStreetClient client = ClearStreetOkHttpClient.builder() .fromEnv() .apiKey("My API Key") .build(); PositionCancelPositionInstructionParams params = PositionCancelPositionInstructionParams.builder() .accountId(0L) .instructionId("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e") .build(); PositionCancelPositionInstructionResponse response = client.v1().positions().cancelPositionInstruction(params); } } ``` #### Response ```json { "metadata": { "request_id": "request_id", "next_page_token": "U3RhaW5sZXNzIHJvY2tz", "page_number": 0, "previous_page_token": "U3RhaW5sZXNzIHJvY2tz", "total_items": 0, "total_pages": 0 }, "error": { "code": 400, "message": "Order quantity must be greater than zero", "details": [ { "foo": "bar" } ] }, "data": { "id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02", "account_id": 122503, "instruction_id": "ui-20260424-001", "instruction_type": "EXERCISE", "instrument_id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02", "quantity": "1", "status": "SENT", "symbol": "AAPL 280121C00195000", "accepted_quantity": null, "created_at": "2026-04-24T14:30:00Z", "rejection_reason": null, "updated_at": "2026-04-24T14:30:00Z" } } ``` ## Domain Types ### Position - `class Position:` Represents a holding of a particular instrument in an account - `long accountId` The account this position belongs to - `String availableQuantity` The quantity of a position that is free to be operated on. - `String instrumentId` OEMS instrument UUID - `SecurityType instrumentType` Type of security - `COMMON_STOCK("COMMON_STOCK")` - `PREFERRED_STOCK("PREFERRED_STOCK")` - `OPTION("OPTION")` - `CASH("CASH")` - `OTHER("OTHER")` - `String marketValue` The current market value of the position - `PositionType positionType` The type of position - `LONG("LONG")` - `SHORT("SHORT")` - `LONG_CALL("LONG_CALL")` - `SHORT_CALL("SHORT_CALL")` - `LONG_PUT("LONG_PUT")` - `SHORT_PUT("SHORT_PUT")` - `String quantity` The number of shares or contracts. Can be positive (long) or negative (short) - `String symbol` The trading symbol for the instrument - `Optional avgPrice` The average price paid per share or contract for this position - `Optional closingPrice` The closing price used to value the position for the last trading day - `Optional closingPriceDate` The market date associated with `closing_price` - `Optional costBasis` The total cost basis for this position - `Optional dailyUnrealizedPnl` The unrealized profit or loss for this position relative to the previous close - `Optional dailyUnrealizedPnlPct` The unrealized profit/loss for the position for the current day, expressed as a percentage of the baseline value (range: 0-100). - `Optional instrumentPrice` The current market price of the instrument - `Optional underlyingInstrumentId` OEMS instrument identifier of the underlying instrument, if resolvable - `Optional unrealizedPnl` The total unrealized profit or loss for this position based on current market value - `Optional unrealizedPnlPct` The unrealized profit/loss for the position, expressed as a percentage of the position's cost basis (range: 0-100). ### Position Instruction - `class PositionInstruction:` A position instruction and its current lifecycle state. - `String id` Server-assigned id. Used as the path parameter on cancel. - `long accountId` Account the instruction belongs to. - `String instructionId` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `PositionInstructionType instructionType` The action this instruction requests. - `EXERCISE("EXERCISE")` - `DO_NOT_EXERCISE("DO_NOT_EXERCISE")` - `CONTRARY_EXERCISE("CONTRARY_EXERCISE")` - `String instrumentId` Identifier of the options contract this instruction acts on. - `String quantity` Number of contracts included in the instruction. - `PositionInstructionStatus status` Current lifecycle status. - `SENT("SENT")` - `ACCEPTED("ACCEPTED")` - `REJECTED("REJECTED")` - `ENGINE_REJECTED("ENGINE_REJECTED")` - `CANCEL_REQUESTED("CANCEL_REQUESTED")` - `CANCELLED("CANCELLED")` - `CANCEL_FAILED("CANCEL_FAILED")` - `UNKNOWN("UNKNOWN")` - `String symbol` Options symbol (OSI) for display. - `Optional acceptedQuantity` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `Optional createdAt` When the instruction was first accepted by the service. - `Optional rejectionReason` Human-readable explanation populated on any non-success terminal status — `REJECTED`, `ENGINE_REJECTED`, or `CANCEL_FAILED`. On a `207 Multi-Status` batch submit the top-level `error` field summarizes the batch; per-row detail continues to live here. - `Optional updatedAt` When the instruction's lifecycle state last changed. ### Position Instruction Status - `enum PositionInstructionStatus:` Lifecycle status of a position instruction. - `SENT("SENT")` - `ACCEPTED("ACCEPTED")` - `REJECTED("REJECTED")` - `ENGINE_REJECTED("ENGINE_REJECTED")` - `CANCEL_REQUESTED("CANCEL_REQUESTED")` - `CANCELLED("CANCELLED")` - `CANCEL_FAILED("CANCEL_FAILED")` - `UNKNOWN("UNKNOWN")` ### Position Instruction Type - `enum PositionInstructionType:` The action to take against an options position. - `EXERCISE("EXERCISE")` - `DO_NOT_EXERCISE("DO_NOT_EXERCISE")` - `CONTRARY_EXERCISE("CONTRARY_EXERCISE")` ### Position Type - `enum PositionType:` Position type classification - `LONG("LONG")` - `SHORT("SHORT")` - `LONG_CALL("LONG_CALL")` - `SHORT_CALL("SHORT_CALL")` - `LONG_PUT("LONG_PUT")` - `SHORT_PUT("SHORT_PUT")`