# Positions ## Get Positions `$ clear-street v1:positions get-positions` **get** `/v1/accounts/{account_id}/positions` Retrieves all positions for the specified trading account. ### Parameters - `--account-id: number` Account identifier - `--instrument-id: optional array of string` Comma-separated OEMS instrument UUIDs - `--page-size: optional number` The number of items to return per page. Only used when page_token is not provided. - `--page-token: optional string` Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored. - `--sort-by: optional "SYMBOL" or "INSTRUMENT_TYPE" or "QUANTITY" or 4 more` Field to sort by - `--sort-direction: optional "ASC" or "DESC"` Sort direction ### Returns - `V1PositionGetPositionsResponse: BaseResponse` - `data: array of Position` - `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: "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `market_value: string` The current market value of the position - `position_type: "LONG" or "SHORT" or "LONG_CALL" or 3 more` 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: optional string` The average price paid per share or contract for this position - `closing_price: optional string` The closing price used to value the position for the last trading day - `closing_price_date: optional string` The market date associated with `closing_price` - `cost_basis: optional string` The total cost basis for this position - `daily_unrealized_pnl: optional string` The unrealized profit or loss for this position relative to the previous close - `daily_unrealized_pnl_pct: optional string` The unrealized profit/loss for the position for the current day, expressed as a percentage of the baseline value (range: 0-100). - `instrument_price: optional string` The current market price of the instrument - `underlying_instrument_id: optional string` OEMS instrument identifier of the underlying instrument, if resolvable - `unrealized_pnl: optional string` The total unrealized profit or loss for this position based on current market value - `unrealized_pnl_pct: optional string` The unrealized profit/loss for the position, expressed as a percentage of the position's cost basis (range: 0-100). ### Example ```cli clear-street v1:positions get-positions \ --api-key 'My API Key' \ --account-id 0 ``` #### 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 `$ clear-street v1:positions close-positions` **delete** `/v1/accounts/{account_id}/positions` Delete all positions within an account. Closes all positions for the specified trading account. ### Parameters - `--account-id: number` Account identifier - `--cancel-orders: optional boolean` Whether to cancel existing open orders for the position before submitting closing orders. ### Returns - `V1PositionClosePositionsResponse: BaseResponse` - `data: array of Order` - `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: "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: "MARKET" or "LIMIT" or "STOP" or 4 more` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: "BUY" or "SELL" or "SELL_SHORT" or "OTHER"` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: "PENDING_NEW" or "NEW" or "PARTIALLY_FILLED" or 12 more` 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: "DAY" or "GOOD_TILL_CANCEL" or "IMMEDIATE_OR_CANCEL" or 8 more` 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: optional string` Average fill price across all executions - `details: optional array of string` Contains execution, rejection or cancellation details, if any - `expires_at: optional string` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: optional boolean` Whether the order is eligible for extended-hours trading. - `limit_offset: optional string` Limit offset for trailing stop-limit orders (signed) - `limit_price: optional string` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: optional "AWAITING_RELEASE" or "RELEASED"` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: optional string` Scheduled release time for orders awaiting release. - `stop_price: optional string` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: optional string` Current trailing limit price computed by the trailing strategy - `trailing_offset: optional string` Trailing offset amount for trailing orders - `trailing_offset_type: optional "PRICE" or "BPS"` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: optional string` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: optional string` Trailing watermark price for trailing orders - `trailing_watermark_ts: optional string` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: optional string` 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 ```cli clear-street v1:positions close-positions \ --api-key 'My API Key' \ --account-id 0 ``` #### 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 `$ clear-street v1:positions close-position` **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 - `--account-id: number` Path param: Account identifier - `--instrument-id: string` Path param: OEMS instrument UUID - `--cancel-orders: optional boolean` Body param: Whether to cancel existing open orders for the position before submitting closing orders. ### Returns - `V1PositionClosePositionResponse: BaseResponse` - `data: array of Order` - `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: "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: "MARKET" or "LIMIT" or "STOP" or 4 more` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: "BUY" or "SELL" or "SELL_SHORT" or "OTHER"` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: "PENDING_NEW" or "NEW" or "PARTIALLY_FILLED" or 12 more` 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: "DAY" or "GOOD_TILL_CANCEL" or "IMMEDIATE_OR_CANCEL" or 8 more` 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: optional string` Average fill price across all executions - `details: optional array of string` Contains execution, rejection or cancellation details, if any - `expires_at: optional string` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: optional boolean` Whether the order is eligible for extended-hours trading. - `limit_offset: optional string` Limit offset for trailing stop-limit orders (signed) - `limit_price: optional string` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: optional "AWAITING_RELEASE" or "RELEASED"` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: optional string` Scheduled release time for orders awaiting release. - `stop_price: optional string` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: optional string` Current trailing limit price computed by the trailing strategy - `trailing_offset: optional string` Trailing offset amount for trailing orders - `trailing_offset_type: optional "PRICE" or "BPS"` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: optional string` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: optional string` Trailing watermark price for trailing orders - `trailing_watermark_ts: optional string` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: optional string` 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 ```cli clear-street v1:positions close-position \ --api-key 'My API Key' \ --account-id 0 \ --instrument-id 182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e ``` #### 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 `$ clear-street v1:positions get-position-instructions` **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 - `--account-id: number` Account identifier - `--instrument-id: optional string` Limit results to a single contract. Accepts the instrument id or the OSI symbol. ### Returns - `V1PositionGetPositionInstructionsResponse: BaseResponse` - `data: array of PositionInstruction` - `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: "EXERCISE" or "DO_NOT_EXERCISE" or "CONTRARY_EXERCISE"` 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: "SENT" or "ACCEPTED" or "REJECTED" or 5 more` Current lifecycle status. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` - `symbol: string` Options symbol (OSI) for display. - `accepted_quantity: optional string` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `created_at: optional string` When the instruction was first accepted by the service. - `rejection_reason: optional string` 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: optional string` When the instruction's lifecycle state last changed. ### Example ```cli clear-street v1:positions get-position-instructions \ --api-key 'My API Key' \ --account-id 0 ``` #### 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 `$ clear-street v1:positions submit-position-instructions` **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 - `--account-id: number` Account identifier - `--instruction: array of object { instruction_type, instrument_id, quantity, instruction_id }` ### Returns - `V1PositionSubmitPositionInstructionsResponse: BaseResponse` - `data: array of PositionInstruction` - `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: "EXERCISE" or "DO_NOT_EXERCISE" or "CONTRARY_EXERCISE"` 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: "SENT" or "ACCEPTED" or "REJECTED" or 5 more` Current lifecycle status. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` - `symbol: string` Options symbol (OSI) for display. - `accepted_quantity: optional string` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `created_at: optional string` When the instruction was first accepted by the service. - `rejection_reason: optional string` 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: optional string` When the instruction's lifecycle state last changed. ### Example ```cli clear-street v1:positions submit-position-instructions \ --api-key 'My API Key' \ --account-id 0 \ --instruction "{instruction_type: EXERCISE, instrument_id: 0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02, quantity: '1'}" ``` #### 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 `$ clear-street v1:positions cancel-position-instruction` **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 - `--account-id: number` Account identifier - `--instruction-id: string` Server-assigned instruction id ### Returns - `V1PositionCancelPositionInstructionResponse: BaseResponse` - `data: object { id, account_id, instruction_id, 9 more }` 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: "EXERCISE" or "DO_NOT_EXERCISE" or "CONTRARY_EXERCISE"` 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: "SENT" or "ACCEPTED" or "REJECTED" or 5 more` Current lifecycle status. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` - `symbol: string` Options symbol (OSI) for display. - `accepted_quantity: optional string` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `created_at: optional string` When the instruction was first accepted by the service. - `rejection_reason: optional string` 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: optional string` When the instruction's lifecycle state last changed. ### Example ```cli clear-street v1:positions cancel-position-instruction \ --api-key 'My API Key' \ --account-id 0 \ --instruction-id 182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e ``` #### 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: object { account_id, available_quantity, instrument_id, 15 more }` 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: "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `market_value: string` The current market value of the position - `position_type: "LONG" or "SHORT" or "LONG_CALL" or 3 more` 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: optional string` The average price paid per share or contract for this position - `closing_price: optional string` The closing price used to value the position for the last trading day - `closing_price_date: optional string` The market date associated with `closing_price` - `cost_basis: optional string` The total cost basis for this position - `daily_unrealized_pnl: optional string` The unrealized profit or loss for this position relative to the previous close - `daily_unrealized_pnl_pct: optional string` The unrealized profit/loss for the position for the current day, expressed as a percentage of the baseline value (range: 0-100). - `instrument_price: optional string` The current market price of the instrument - `underlying_instrument_id: optional string` OEMS instrument identifier of the underlying instrument, if resolvable - `unrealized_pnl: optional string` The total unrealized profit or loss for this position based on current market value - `unrealized_pnl_pct: optional string` The unrealized profit/loss for the position, expressed as a percentage of the position's cost basis (range: 0-100). ### Position Instruction - `position_instruction: object { id, account_id, instruction_id, 9 more }` 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: "EXERCISE" or "DO_NOT_EXERCISE" or "CONTRARY_EXERCISE"` 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: "SENT" or "ACCEPTED" or "REJECTED" or 5 more` Current lifecycle status. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` - `symbol: string` Options symbol (OSI) for display. - `accepted_quantity: optional string` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `created_at: optional string` When the instruction was first accepted by the service. - `rejection_reason: optional string` 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: optional string` When the instruction's lifecycle state last changed. ### Position Instruction List - `position_instruction_list: array of PositionInstruction` - `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: "EXERCISE" or "DO_NOT_EXERCISE" or "CONTRARY_EXERCISE"` 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: "SENT" or "ACCEPTED" or "REJECTED" or 5 more` Current lifecycle status. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` - `symbol: string` Options symbol (OSI) for display. - `accepted_quantity: optional string` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `created_at: optional string` When the instruction was first accepted by the service. - `rejection_reason: optional string` 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: optional string` When the instruction's lifecycle state last changed. ### Position Instruction Status - `position_instruction_status: "SENT" or "ACCEPTED" or "REJECTED" or 5 more` Lifecycle status of a position instruction. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` ### Position Instruction Type - `position_instruction_type: "EXERCISE" or "DO_NOT_EXERCISE" or "CONTRARY_EXERCISE"` The action to take against an options position. - `"EXERCISE"` - `"DO_NOT_EXERCISE"` - `"CONTRARY_EXERCISE"` ### Position List - `position_list: array of Position` - `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: "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `market_value: string` The current market value of the position - `position_type: "LONG" or "SHORT" or "LONG_CALL" or 3 more` 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: optional string` The average price paid per share or contract for this position - `closing_price: optional string` The closing price used to value the position for the last trading day - `closing_price_date: optional string` The market date associated with `closing_price` - `cost_basis: optional string` The total cost basis for this position - `daily_unrealized_pnl: optional string` The unrealized profit or loss for this position relative to the previous close - `daily_unrealized_pnl_pct: optional string` The unrealized profit/loss for the position for the current day, expressed as a percentage of the baseline value (range: 0-100). - `instrument_price: optional string` The current market price of the instrument - `underlying_instrument_id: optional string` OEMS instrument identifier of the underlying instrument, if resolvable - `unrealized_pnl: optional string` The total unrealized profit or loss for this position based on current market value - `unrealized_pnl_pct: optional string` The unrealized profit/loss for the position, expressed as a percentage of the position's cost basis (range: 0-100). ### Position Type - `position_type: "LONG" or "SHORT" or "LONG_CALL" or 3 more` Position type classification - `"LONG"` - `"SHORT"` - `"LONG_CALL"` - `"SHORT_CALL"` - `"LONG_PUT"` - `"SHORT_PUT"`