# Positions ## Get Positions `client.v1.positions.getPositions(numberaccountID, PositionGetPositionsParamsquery?, RequestOptionsoptions?): PositionGetPositionsResponse` **get** `/v1/accounts/{account_id}/positions` Retrieves all positions for the specified trading account. ### Parameters - `accountID: number` - `query: PositionGetPositionsParams` - `instrument_ids?: Array` Comma-separated OEMS instrument UUIDs - `page_size?: number` The number of items to return per page. Only used when page_token is not provided. - `page_token?: string` Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored. - `sort_by?: "SYMBOL" | "INSTRUMENT_TYPE" | "QUANTITY" | 4 more` Field to sort by - `"SYMBOL"` - `"INSTRUMENT_TYPE"` - `"QUANTITY"` - `"MARKET_VALUE"` - `"POSITION_TYPE"` - `"UNREALIZED_PNL"` - `"DAILY_UNREALIZED_PNL"` - `sort_direction?: "ASC" | "DESC"` Sort direction - `"ASC"` - `"DESC"` ### Returns - `PositionGetPositionsResponse extends BaseResponse` - `data: PositionList` - `account_id: number` The account this position belongs to - `available_quantity: string` The quantity of a position that is free to be operated on. - `instrument_id: string` OEMS instrument UUID - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `market_value: string` The current market value of the position - `position_type: PositionType` The type of position - `"LONG"` - `"SHORT"` - `"LONG_CALL"` - `"SHORT_CALL"` - `"LONG_PUT"` - `"SHORT_PUT"` - `quantity: string` The number of shares or contracts. Can be positive (long) or negative (short) - `symbol: string` The trading symbol for the instrument - `avg_price?: string | null` The average price paid per share or contract for this position - `closing_price?: string | null` The closing price used to value the position for the last trading day - `closing_price_date?: string | null` The market date associated with `closing_price` - `cost_basis?: string | null` The total cost basis for this position - `daily_unrealized_pnl?: string | null` The unrealized profit or loss for this position relative to the previous close - `daily_unrealized_pnl_pct?: string | null` The unrealized profit/loss for the position for the current day, expressed as a percentage of the baseline value (range: 0-100). - `instrument_price?: string | null` The current market price of the instrument - `underlying_instrument_id?: string | null` OEMS instrument identifier of the underlying instrument, if resolvable - `unrealized_pnl?: string | null` The total unrealized profit or loss for this position based on current market value - `unrealized_pnl_pct?: string | null` The unrealized profit/loss for the position, expressed as a percentage of the position's cost basis (range: 0-100). ### Example ```typescript import ClearStreet from '@clear-street-internal/sdk'; const client = new ClearStreet({ apiKey: 'My API Key', }); const response = await client.v1.positions.getPositions(0); console.log(response); ``` #### 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 `client.v1.positions.closePositions(numberaccountID, PositionClosePositionsParamsbody?, RequestOptionsoptions?): PositionClosePositionsResponse` **delete** `/v1/accounts/{account_id}/positions` Delete all positions within an account. Closes all positions for the specified trading account. ### Parameters - `accountID: number` - `body: PositionClosePositionsParams` - `cancel_orders?: boolean | null` Whether to cancel existing open orders for the position before submitting closing orders. ### Returns - `PositionClosePositionsResponse extends BaseResponse` - `data: OrderList` - `id: string` Engine-assigned unique identifier for this order (UUID). - `account_id: number` Account placing the order - `client_order_id: string` Client-provided identifier echoed back (FIX tag 11). - `created_at: string` Timestamp when order was created (UTC) - `filled_quantity: string` Cumulative filled quantity - `instrument_id: string` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: string` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: string` Timestamp of the most recent update (UTC) - `venue: string` MIC code of the venue where the order is routed - `average_fill_price?: string | null` Average fill price across all executions - `details?: Array` Contains execution, rejection or cancellation details, if any - `expires_at?: string | null` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours?: boolean | null` Whether the order is eligible for extended-hours trading. - `limit_offset?: string | null` Limit offset for trailing stop-limit orders (signed) - `limit_price?: string | null` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state?: QueueState | null` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at?: string | null` Scheduled release time for orders awaiting release. - `stop_price?: string | null` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px?: string | null` Current trailing limit price computed by the trailing strategy - `trailing_offset?: string | null` Trailing offset amount for trailing orders - `trailing_offset_type?: TrailingOffsetType | null` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px?: string | null` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px?: string | null` Trailing watermark price for trailing orders - `trailing_watermark_ts?: string | null` Trailing watermark timestamp for trailing orders - `underlying_instrument_id?: string | null` 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 ```typescript import ClearStreet from '@clear-street-internal/sdk'; const client = new ClearStreet({ apiKey: 'My API Key', }); const response = await client.v1.positions.closePositions(0); console.log(response); ``` #### 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 `client.v1.positions.closePosition(InstrumentIDOrSymbolinstrumentID, PositionClosePositionParamsparams, RequestOptionsoptions?): PositionClosePositionResponse` **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 - `instrument_id: InstrumentIDOrSymbol` OEMS instrument UUID - `params: PositionClosePositionParams` - `account_id: number` Path param: Account identifier - `cancel_orders?: boolean | null` Body param: Whether to cancel existing open orders for the position before submitting closing orders. ### Returns - `PositionClosePositionResponse extends BaseResponse` - `data: OrderList` - `id: string` Engine-assigned unique identifier for this order (UUID). - `account_id: number` Account placing the order - `client_order_id: string` Client-provided identifier echoed back (FIX tag 11). - `created_at: string` Timestamp when order was created (UTC) - `filled_quantity: string` Cumulative filled quantity - `instrument_id: string` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: string` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: string` Timestamp of the most recent update (UTC) - `venue: string` MIC code of the venue where the order is routed - `average_fill_price?: string | null` Average fill price across all executions - `details?: Array` Contains execution, rejection or cancellation details, if any - `expires_at?: string | null` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours?: boolean | null` Whether the order is eligible for extended-hours trading. - `limit_offset?: string | null` Limit offset for trailing stop-limit orders (signed) - `limit_price?: string | null` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state?: QueueState | null` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at?: string | null` Scheduled release time for orders awaiting release. - `stop_price?: string | null` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px?: string | null` Current trailing limit price computed by the trailing strategy - `trailing_offset?: string | null` Trailing offset amount for trailing orders - `trailing_offset_type?: TrailingOffsetType | null` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px?: string | null` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px?: string | null` Trailing watermark price for trailing orders - `trailing_watermark_ts?: string | null` Trailing watermark timestamp for trailing orders - `underlying_instrument_id?: string | null` 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 ```typescript import ClearStreet from '@clear-street-internal/sdk'; const client = new ClearStreet({ apiKey: 'My API Key', }); const response = await client.v1.positions.closePosition('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { account_id: 0, }); console.log(response); ``` #### 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 `client.v1.positions.getPositionInstructions(numberaccountID, PositionGetPositionInstructionsParamsquery?, RequestOptionsoptions?): PositionGetPositionInstructionsResponse` **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 - `accountID: number` - `query: PositionGetPositionInstructionsParams` - `instrument_id?: InstrumentIDOrSymbol` Limit results to a single contract. Accepts the instrument id or the OSI symbol. ### Returns - `PositionGetPositionInstructionsResponse extends BaseResponse` - `data: PositionInstructionList` - `id: string` Server-assigned id. Used as the path parameter on cancel. - `account_id: number` Account the instruction belongs to. - `instruction_id: string` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `instruction_type: PositionInstructionType` The action this instruction requests. - `"EXERCISE"` - `"DO_NOT_EXERCISE"` - `"CONTRARY_EXERCISE"` - `instrument_id: string` Identifier of the options contract this instruction acts on. - `quantity: string` Number of contracts included in the instruction. - `status: PositionInstructionStatus` Current lifecycle status. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` - `symbol: string` Options symbol (OSI) for display. - `accepted_quantity?: string | null` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `created_at?: string | null` When the instruction was first accepted by the service. - `rejection_reason?: string | null` 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. - `updated_at?: string | null` When the instruction's lifecycle state last changed. ### Example ```typescript import ClearStreet from '@clear-street-internal/sdk'; const client = new ClearStreet({ apiKey: 'My API Key', }); const response = await client.v1.positions.getPositionInstructions(0); console.log(response); ``` #### 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 `client.v1.positions.submitPositionInstructions(numberaccountID, PositionSubmitPositionInstructionsParamsparams, RequestOptionsoptions?): PositionSubmitPositionInstructionsResponse` **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 - `accountID: number` - `params: PositionSubmitPositionInstructionsParams` - `instructions: Array` - `instruction_type: PositionInstructionType` The action to take. - `"EXERCISE"` - `"DO_NOT_EXERCISE"` - `"CONTRARY_EXERCISE"` - `instrument_id: string` Identifier of the options contract to act on. Unknown ids return 404. - `quantity: string` Number of contracts to include in the instruction. - `instruction_id?: string | null` Caller-supplied idempotency key. Echoed on the response. The server generates a unique id when omitted. ### Returns - `PositionSubmitPositionInstructionsResponse extends BaseResponse` - `data: PositionInstructionList` - `id: string` Server-assigned id. Used as the path parameter on cancel. - `account_id: number` Account the instruction belongs to. - `instruction_id: string` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `instruction_type: PositionInstructionType` The action this instruction requests. - `"EXERCISE"` - `"DO_NOT_EXERCISE"` - `"CONTRARY_EXERCISE"` - `instrument_id: string` Identifier of the options contract this instruction acts on. - `quantity: string` Number of contracts included in the instruction. - `status: PositionInstructionStatus` Current lifecycle status. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` - `symbol: string` Options symbol (OSI) for display. - `accepted_quantity?: string | null` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `created_at?: string | null` When the instruction was first accepted by the service. - `rejection_reason?: string | null` 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. - `updated_at?: string | null` When the instruction's lifecycle state last changed. ### Example ```typescript import ClearStreet from '@clear-street-internal/sdk'; const client = new ClearStreet({ apiKey: 'My API Key', }); const response = await client.v1.positions.submitPositionInstructions(0, { instructions: [ { instruction_type: 'EXERCISE', instrument_id: '0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02', quantity: '1', }, ], }); console.log(response); ``` #### 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 `client.v1.positions.cancelPositionInstruction(stringinstructionID, PositionCancelPositionInstructionParamsparams, RequestOptionsoptions?): PositionCancelPositionInstructionResponse` **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 - `instructionID: string` - `params: PositionCancelPositionInstructionParams` - `account_id: number` Account identifier ### Returns - `PositionCancelPositionInstructionResponse extends BaseResponse` - `data: PositionInstruction` A position instruction and its current lifecycle state. - `id: string` Server-assigned id. Used as the path parameter on cancel. - `account_id: number` Account the instruction belongs to. - `instruction_id: string` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `instruction_type: PositionInstructionType` The action this instruction requests. - `"EXERCISE"` - `"DO_NOT_EXERCISE"` - `"CONTRARY_EXERCISE"` - `instrument_id: string` Identifier of the options contract this instruction acts on. - `quantity: string` Number of contracts included in the instruction. - `status: PositionInstructionStatus` Current lifecycle status. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` - `symbol: string` Options symbol (OSI) for display. - `accepted_quantity?: string | null` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `created_at?: string | null` When the instruction was first accepted by the service. - `rejection_reason?: string | null` 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. - `updated_at?: string | null` When the instruction's lifecycle state last changed. ### Example ```typescript import ClearStreet from '@clear-street-internal/sdk'; const client = new ClearStreet({ apiKey: 'My API Key', }); const response = await client.v1.positions.cancelPositionInstruction( '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { account_id: 0 }, ); console.log(response); ``` #### 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 - `Position` Represents a holding of a particular instrument in an account - `account_id: number` The account this position belongs to - `available_quantity: string` The quantity of a position that is free to be operated on. - `instrument_id: string` OEMS instrument UUID - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `market_value: string` The current market value of the position - `position_type: PositionType` The type of position - `"LONG"` - `"SHORT"` - `"LONG_CALL"` - `"SHORT_CALL"` - `"LONG_PUT"` - `"SHORT_PUT"` - `quantity: string` The number of shares or contracts. Can be positive (long) or negative (short) - `symbol: string` The trading symbol for the instrument - `avg_price?: string | null` The average price paid per share or contract for this position - `closing_price?: string | null` The closing price used to value the position for the last trading day - `closing_price_date?: string | null` The market date associated with `closing_price` - `cost_basis?: string | null` The total cost basis for this position - `daily_unrealized_pnl?: string | null` The unrealized profit or loss for this position relative to the previous close - `daily_unrealized_pnl_pct?: string | null` The unrealized profit/loss for the position for the current day, expressed as a percentage of the baseline value (range: 0-100). - `instrument_price?: string | null` The current market price of the instrument - `underlying_instrument_id?: string | null` OEMS instrument identifier of the underlying instrument, if resolvable - `unrealized_pnl?: string | null` The total unrealized profit or loss for this position based on current market value - `unrealized_pnl_pct?: string | null` The unrealized profit/loss for the position, expressed as a percentage of the position's cost basis (range: 0-100). ### Position Instruction - `PositionInstruction` A position instruction and its current lifecycle state. - `id: string` Server-assigned id. Used as the path parameter on cancel. - `account_id: number` Account the instruction belongs to. - `instruction_id: string` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `instruction_type: PositionInstructionType` The action this instruction requests. - `"EXERCISE"` - `"DO_NOT_EXERCISE"` - `"CONTRARY_EXERCISE"` - `instrument_id: string` Identifier of the options contract this instruction acts on. - `quantity: string` Number of contracts included in the instruction. - `status: PositionInstructionStatus` Current lifecycle status. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` - `symbol: string` Options symbol (OSI) for display. - `accepted_quantity?: string | null` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `created_at?: string | null` When the instruction was first accepted by the service. - `rejection_reason?: string | null` 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. - `updated_at?: string | null` When the instruction's lifecycle state last changed. ### Position Instruction List - `PositionInstructionList = Array` - `id: string` Server-assigned id. Used as the path parameter on cancel. - `account_id: number` Account the instruction belongs to. - `instruction_id: string` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `instruction_type: PositionInstructionType` The action this instruction requests. - `"EXERCISE"` - `"DO_NOT_EXERCISE"` - `"CONTRARY_EXERCISE"` - `instrument_id: string` Identifier of the options contract this instruction acts on. - `quantity: string` Number of contracts included in the instruction. - `status: PositionInstructionStatus` Current lifecycle status. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` - `symbol: string` Options symbol (OSI) for display. - `accepted_quantity?: string | null` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `created_at?: string | null` When the instruction was first accepted by the service. - `rejection_reason?: string | null` 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. - `updated_at?: string | null` When the instruction's lifecycle state last changed. ### Position Instruction Status - `PositionInstructionStatus = "SENT" | "ACCEPTED" | "REJECTED" | 5 more` Lifecycle status of a position instruction. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` ### Position Instruction Type - `PositionInstructionType = "EXERCISE" | "DO_NOT_EXERCISE" | "CONTRARY_EXERCISE"` The action to take against an options position. - `"EXERCISE"` - `"DO_NOT_EXERCISE"` - `"CONTRARY_EXERCISE"` ### Position List - `PositionList = Array` - `account_id: number` The account this position belongs to - `available_quantity: string` The quantity of a position that is free to be operated on. - `instrument_id: string` OEMS instrument UUID - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `market_value: string` The current market value of the position - `position_type: PositionType` The type of position - `"LONG"` - `"SHORT"` - `"LONG_CALL"` - `"SHORT_CALL"` - `"LONG_PUT"` - `"SHORT_PUT"` - `quantity: string` The number of shares or contracts. Can be positive (long) or negative (short) - `symbol: string` The trading symbol for the instrument - `avg_price?: string | null` The average price paid per share or contract for this position - `closing_price?: string | null` The closing price used to value the position for the last trading day - `closing_price_date?: string | null` The market date associated with `closing_price` - `cost_basis?: string | null` The total cost basis for this position - `daily_unrealized_pnl?: string | null` The unrealized profit or loss for this position relative to the previous close - `daily_unrealized_pnl_pct?: string | null` The unrealized profit/loss for the position for the current day, expressed as a percentage of the baseline value (range: 0-100). - `instrument_price?: string | null` The current market price of the instrument - `underlying_instrument_id?: string | null` OEMS instrument identifier of the underlying instrument, if resolvable - `unrealized_pnl?: string | null` The total unrealized profit or loss for this position based on current market value - `unrealized_pnl_pct?: string | null` The unrealized profit/loss for the position, expressed as a percentage of the position's cost basis (range: 0-100). ### Position Type - `PositionType = "LONG" | "SHORT" | "LONG_CALL" | 3 more` Position type classification - `"LONG"` - `"SHORT"` - `"LONG_CALL"` - `"SHORT_CALL"` - `"LONG_PUT"` - `"SHORT_PUT"` ### Position Get Positions Response - `PositionGetPositionsResponse extends BaseResponse` - `data: PositionList` - `account_id: number` The account this position belongs to - `available_quantity: string` The quantity of a position that is free to be operated on. - `instrument_id: string` OEMS instrument UUID - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `market_value: string` The current market value of the position - `position_type: PositionType` The type of position - `"LONG"` - `"SHORT"` - `"LONG_CALL"` - `"SHORT_CALL"` - `"LONG_PUT"` - `"SHORT_PUT"` - `quantity: string` The number of shares or contracts. Can be positive (long) or negative (short) - `symbol: string` The trading symbol for the instrument - `avg_price?: string | null` The average price paid per share or contract for this position - `closing_price?: string | null` The closing price used to value the position for the last trading day - `closing_price_date?: string | null` The market date associated with `closing_price` - `cost_basis?: string | null` The total cost basis for this position - `daily_unrealized_pnl?: string | null` The unrealized profit or loss for this position relative to the previous close - `daily_unrealized_pnl_pct?: string | null` The unrealized profit/loss for the position for the current day, expressed as a percentage of the baseline value (range: 0-100). - `instrument_price?: string | null` The current market price of the instrument - `underlying_instrument_id?: string | null` OEMS instrument identifier of the underlying instrument, if resolvable - `unrealized_pnl?: string | null` The total unrealized profit or loss for this position based on current market value - `unrealized_pnl_pct?: string | null` The unrealized profit/loss for the position, expressed as a percentage of the position's cost basis (range: 0-100). ### Position Close Positions Response - `PositionClosePositionsResponse extends BaseResponse` - `data: OrderList` - `id: string` Engine-assigned unique identifier for this order (UUID). - `account_id: number` Account placing the order - `client_order_id: string` Client-provided identifier echoed back (FIX tag 11). - `created_at: string` Timestamp when order was created (UTC) - `filled_quantity: string` Cumulative filled quantity - `instrument_id: string` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: string` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: string` Timestamp of the most recent update (UTC) - `venue: string` MIC code of the venue where the order is routed - `average_fill_price?: string | null` Average fill price across all executions - `details?: Array` Contains execution, rejection or cancellation details, if any - `expires_at?: string | null` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours?: boolean | null` Whether the order is eligible for extended-hours trading. - `limit_offset?: string | null` Limit offset for trailing stop-limit orders (signed) - `limit_price?: string | null` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state?: QueueState | null` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at?: string | null` Scheduled release time for orders awaiting release. - `stop_price?: string | null` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px?: string | null` Current trailing limit price computed by the trailing strategy - `trailing_offset?: string | null` Trailing offset amount for trailing orders - `trailing_offset_type?: TrailingOffsetType | null` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px?: string | null` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px?: string | null` Trailing watermark price for trailing orders - `trailing_watermark_ts?: string | null` Trailing watermark timestamp for trailing orders - `underlying_instrument_id?: string | null` 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. ### Position Close Position Response - `PositionClosePositionResponse extends BaseResponse` - `data: OrderList` - `id: string` Engine-assigned unique identifier for this order (UUID). - `account_id: number` Account placing the order - `client_order_id: string` Client-provided identifier echoed back (FIX tag 11). - `created_at: string` Timestamp when order was created (UTC) - `filled_quantity: string` Cumulative filled quantity - `instrument_id: string` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: string` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: string` Timestamp of the most recent update (UTC) - `venue: string` MIC code of the venue where the order is routed - `average_fill_price?: string | null` Average fill price across all executions - `details?: Array` Contains execution, rejection or cancellation details, if any - `expires_at?: string | null` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours?: boolean | null` Whether the order is eligible for extended-hours trading. - `limit_offset?: string | null` Limit offset for trailing stop-limit orders (signed) - `limit_price?: string | null` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state?: QueueState | null` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at?: string | null` Scheduled release time for orders awaiting release. - `stop_price?: string | null` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px?: string | null` Current trailing limit price computed by the trailing strategy - `trailing_offset?: string | null` Trailing offset amount for trailing orders - `trailing_offset_type?: TrailingOffsetType | null` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px?: string | null` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px?: string | null` Trailing watermark price for trailing orders - `trailing_watermark_ts?: string | null` Trailing watermark timestamp for trailing orders - `underlying_instrument_id?: string | null` 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. ### Position Get Position Instructions Response - `PositionGetPositionInstructionsResponse extends BaseResponse` - `data: PositionInstructionList` - `id: string` Server-assigned id. Used as the path parameter on cancel. - `account_id: number` Account the instruction belongs to. - `instruction_id: string` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `instruction_type: PositionInstructionType` The action this instruction requests. - `"EXERCISE"` - `"DO_NOT_EXERCISE"` - `"CONTRARY_EXERCISE"` - `instrument_id: string` Identifier of the options contract this instruction acts on. - `quantity: string` Number of contracts included in the instruction. - `status: PositionInstructionStatus` Current lifecycle status. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` - `symbol: string` Options symbol (OSI) for display. - `accepted_quantity?: string | null` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `created_at?: string | null` When the instruction was first accepted by the service. - `rejection_reason?: string | null` 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. - `updated_at?: string | null` When the instruction's lifecycle state last changed. ### Position Submit Position Instructions Response - `PositionSubmitPositionInstructionsResponse extends BaseResponse` - `data: PositionInstructionList` - `id: string` Server-assigned id. Used as the path parameter on cancel. - `account_id: number` Account the instruction belongs to. - `instruction_id: string` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `instruction_type: PositionInstructionType` The action this instruction requests. - `"EXERCISE"` - `"DO_NOT_EXERCISE"` - `"CONTRARY_EXERCISE"` - `instrument_id: string` Identifier of the options contract this instruction acts on. - `quantity: string` Number of contracts included in the instruction. - `status: PositionInstructionStatus` Current lifecycle status. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` - `symbol: string` Options symbol (OSI) for display. - `accepted_quantity?: string | null` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `created_at?: string | null` When the instruction was first accepted by the service. - `rejection_reason?: string | null` 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. - `updated_at?: string | null` When the instruction's lifecycle state last changed. ### Position Cancel Position Instruction Response - `PositionCancelPositionInstructionResponse extends BaseResponse` - `data: PositionInstruction` A position instruction and its current lifecycle state. - `id: string` Server-assigned id. Used as the path parameter on cancel. - `account_id: number` Account the instruction belongs to. - `instruction_id: string` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `instruction_type: PositionInstructionType` The action this instruction requests. - `"EXERCISE"` - `"DO_NOT_EXERCISE"` - `"CONTRARY_EXERCISE"` - `instrument_id: string` Identifier of the options contract this instruction acts on. - `quantity: string` Number of contracts included in the instruction. - `status: PositionInstructionStatus` Current lifecycle status. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` - `symbol: string` Options symbol (OSI) for display. - `accepted_quantity?: string | null` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `created_at?: string | null` When the instruction was first accepted by the service. - `rejection_reason?: string | null` 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. - `updated_at?: string | null` When the instruction's lifecycle state last changed.