# Positions ## Get Positions `client.V1.Positions.GetPositions(ctx, accountID, query) (*V1PositionGetPositionsResponse, error)` **get** `/v1/accounts/{account_id}/positions` Retrieves all positions for the specified trading account. ### Parameters - `accountID int64` - `query V1PositionGetPositionsParams` - `InstrumentIDs param.Field[[]string]` Comma-separated OEMS instrument UUIDs - `PageSize param.Field[int64]` The number of items to return per page. Only used when page_token is not provided. - `PageToken param.Field[string]` Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored. - `SortBy param.Field[V1PositionGetPositionsParamsSortBy]` Field to sort by - `const V1PositionGetPositionsParamsSortBySymbol V1PositionGetPositionsParamsSortBy = "SYMBOL"` - `const V1PositionGetPositionsParamsSortByInstrumentType V1PositionGetPositionsParamsSortBy = "INSTRUMENT_TYPE"` - `const V1PositionGetPositionsParamsSortByQuantity V1PositionGetPositionsParamsSortBy = "QUANTITY"` - `const V1PositionGetPositionsParamsSortByMarketValue V1PositionGetPositionsParamsSortBy = "MARKET_VALUE"` - `const V1PositionGetPositionsParamsSortByPositionType V1PositionGetPositionsParamsSortBy = "POSITION_TYPE"` - `const V1PositionGetPositionsParamsSortByUnrealizedPnl V1PositionGetPositionsParamsSortBy = "UNREALIZED_PNL"` - `const V1PositionGetPositionsParamsSortByDailyUnrealizedPnl V1PositionGetPositionsParamsSortBy = "DAILY_UNREALIZED_PNL"` - `SortDirection param.Field[V1PositionGetPositionsParamsSortDirection]` Sort direction - `const V1PositionGetPositionsParamsSortDirectionAsc V1PositionGetPositionsParamsSortDirection = "ASC"` - `const V1PositionGetPositionsParamsSortDirectionDesc V1PositionGetPositionsParamsSortDirection = "DESC"` ### Returns - `type V1PositionGetPositionsResponse struct{…}` - `Data PositionList` - `AccountID int64` The account this position belongs to - `AvailableQuantity string` The quantity of a position that is free to be operated on. - `InstrumentID string` OEMS instrument UUID - `InstrumentType SecurityType` Type of security - `const SecurityTypeCommonStock SecurityType = "COMMON_STOCK"` - `const SecurityTypePreferredStock SecurityType = "PREFERRED_STOCK"` - `const SecurityTypeOption SecurityType = "OPTION"` - `const SecurityTypeCash SecurityType = "CASH"` - `const SecurityTypeOther SecurityType = "OTHER"` - `MarketValue string` The current market value of the position - `PositionType PositionType` The type of position - `const PositionTypeLong PositionType = "LONG"` - `const PositionTypeShort PositionType = "SHORT"` - `const PositionTypeLongCall PositionType = "LONG_CALL"` - `const PositionTypeShortCall PositionType = "SHORT_CALL"` - `const PositionTypeLongPut PositionType = "LONG_PUT"` - `const PositionTypeShortPut PositionType = "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 - `AvgPrice string` The average price paid per share or contract for this position - `ClosingPrice string` The closing price used to value the position for the last trading day - `ClosingPriceDate Time` The market date associated with `closing_price` - `CostBasis string` The total cost basis for this position - `DailyUnrealizedPnl string` The unrealized profit or loss for this position relative to the previous close - `DailyUnrealizedPnlPct string` The unrealized profit/loss for the position for the current day, expressed as a percentage of the baseline value (range: 0-100). - `InstrumentPrice string` The current market price of the instrument - `UnderlyingInstrumentID string` OEMS instrument identifier of the underlying instrument, if resolvable - `UnrealizedPnl string` The total unrealized profit or loss for this position based on current market value - `UnrealizedPnlPct string` The unrealized profit/loss for the position, expressed as a percentage of the position's cost basis (range: 0-100). ### Example ```go package main import ( "context" "fmt" "github.com/clear-street/clear-street-go" "github.com/clear-street/clear-street-go/option" ) func main() { client := clearstreet.NewClient( option.WithAPIKey("My API Key"), ) response, err := client.V1.Positions.GetPositions( context.TODO(), 0, clearstreet.V1PositionGetPositionsParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", 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(ctx, accountID, body) (*V1PositionClosePositionsResponse, error)` **delete** `/v1/accounts/{account_id}/positions` Delete all positions within an account. Closes all positions for the specified trading account. ### Parameters - `accountID int64` - `body V1PositionClosePositionsParams` - `CancelOrders param.Field[bool]` Whether to cancel existing open orders for the position before submitting closing orders. ### Returns - `type V1PositionClosePositionsResponse struct{…}` - `Data OrderList` - `ID string` Engine-assigned unique identifier for this order (UUID). - `AccountID int64` Account placing the order - `ClientOrderID string` Client-provided identifier echoed back (FIX tag 11). - `CreatedAt Time` Timestamp when order was created (UTC) - `FilledQuantity string` Cumulative filled quantity - `InstrumentID string` OEMS instrument UUID for the traded instrument. - `InstrumentType SecurityType` Type of security - `const SecurityTypeCommonStock SecurityType = "COMMON_STOCK"` - `const SecurityTypePreferredStock SecurityType = "PREFERRED_STOCK"` - `const SecurityTypeOption SecurityType = "OPTION"` - `const SecurityTypeCash SecurityType = "CASH"` - `const SecurityTypeOther SecurityType = "OTHER"` - `LeavesQuantity string` Remaining unfilled quantity - `OrderType OrderType` Type of order (MARKET, LIMIT, etc.) - `const OrderTypeMarket OrderType = "MARKET"` - `const OrderTypeLimit OrderType = "LIMIT"` - `const OrderTypeStop OrderType = "STOP"` - `const OrderTypeStopLimit OrderType = "STOP_LIMIT"` - `const OrderTypeTrailingStop OrderType = "TRAILING_STOP"` - `const OrderTypeTrailingStopLimit OrderType = "TRAILING_STOP_LIMIT"` - `const OrderTypeOther OrderType = "OTHER"` - `Quantity string` Total order quantity - `Side Side` Side of the order (BUY, SELL, SELL_SHORT) - `const SideBuy Side = "BUY"` - `const SideSell Side = "SELL"` - `const SideSellShort Side = "SELL_SHORT"` - `const SideOther Side = "OTHER"` - `Status OrderStatus` Current status of the order - `const OrderStatusPendingNew OrderStatus = "PENDING_NEW"` - `const OrderStatusNew OrderStatus = "NEW"` - `const OrderStatusPartiallyFilled OrderStatus = "PARTIALLY_FILLED"` - `const OrderStatusFilled OrderStatus = "FILLED"` - `const OrderStatusCanceled OrderStatus = "CANCELED"` - `const OrderStatusRejected OrderStatus = "REJECTED"` - `const OrderStatusExpired OrderStatus = "EXPIRED"` - `const OrderStatusPendingCancel OrderStatus = "PENDING_CANCEL"` - `const OrderStatusPendingReplace OrderStatus = "PENDING_REPLACE"` - `const OrderStatusReplaced OrderStatus = "REPLACED"` - `const OrderStatusDoneForDay OrderStatus = "DONE_FOR_DAY"` - `const OrderStatusStopped OrderStatus = "STOPPED"` - `const OrderStatusSuspended OrderStatus = "SUSPENDED"` - `const OrderStatusCalculated OrderStatus = "CALCULATED"` - `const OrderStatusOther OrderStatus = "OTHER"` - `Symbol string` Trading symbol - `TimeInForce TimeInForce` Time in force instruction - `const TimeInForceDay TimeInForce = "DAY"` - `const TimeInForceGoodTillCancel TimeInForce = "GOOD_TILL_CANCEL"` - `const TimeInForceImmediateOrCancel TimeInForce = "IMMEDIATE_OR_CANCEL"` - `const TimeInForceFillOrKill TimeInForce = "FILL_OR_KILL"` - `const TimeInForceGoodTillDate TimeInForce = "GOOD_TILL_DATE"` - `const TimeInForceAtTheOpening TimeInForce = "AT_THE_OPENING"` - `const TimeInForceAtTheClose TimeInForce = "AT_THE_CLOSE"` - `const TimeInForceGoodTillCrossing TimeInForce = "GOOD_TILL_CROSSING"` - `const TimeInForceGoodThroughCrossing TimeInForce = "GOOD_THROUGH_CROSSING"` - `const TimeInForceAtCrossing TimeInForce = "AT_CROSSING"` - `const TimeInForceOther TimeInForce = "OTHER"` - `UpdatedAt Time` Timestamp of the most recent update (UTC) - `Venue string` MIC code of the venue where the order is routed - `AverageFillPrice string` Average fill price across all executions - `Details []string` Contains execution, rejection or cancellation details, if any - `ExpiresAt Time` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `ExtendedHours bool` Whether the order is eligible for extended-hours trading. - `LimitOffset string` Limit offset for trailing stop-limit orders (signed) - `LimitPrice string` Limit price (for LIMIT and STOP_LIMIT orders) - `QueueState QueueState` Parent order queue state, present when the order is awaiting release or released. - `const QueueStateAwaitingRelease QueueState = "AWAITING_RELEASE"` - `const QueueStateReleased QueueState = "RELEASED"` - `ReleasesAt Time` Scheduled release time for orders awaiting release. - `StopPrice string` Stop price (for STOP and STOP_LIMIT orders) - `TrailingLimitPx string` Current trailing limit price computed by the trailing strategy - `TrailingOffset string` Trailing offset amount for trailing orders - `TrailingOffsetType TrailingOffsetType` Trailing offset type for trailing orders - `const TrailingOffsetTypePrice TrailingOffsetType = "PRICE"` - `const TrailingOffsetTypeBps TrailingOffsetType = "BPS"` - `TrailingStopPx string` Current trailing stop price computed by the trailing strategy - `TrailingWatermarkPx string` Trailing watermark price for trailing orders - `TrailingWatermarkTs Time` Trailing watermark timestamp for trailing orders - `UnderlyingInstrumentID 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 ```go package main import ( "context" "fmt" "github.com/clear-street/clear-street-go" "github.com/clear-street/clear-street-go/option" ) func main() { client := clearstreet.NewClient( option.WithAPIKey("My API Key"), ) response, err := client.V1.Positions.ClosePositions( context.TODO(), 0, clearstreet.V1PositionClosePositionsParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", 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(ctx, instrumentID, params) (*V1PositionClosePositionResponse, error)` **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 - `InstrumentID InstrumentIDOrSymbol` OEMS instrument UUID - `params V1PositionClosePositionParams` - `AccountID param.Field[int64]` Path param: Account identifier - `CancelOrders param.Field[bool]` Body param: Whether to cancel existing open orders for the position before submitting closing orders. ### Returns - `type V1PositionClosePositionResponse struct{…}` - `Data OrderList` - `ID string` Engine-assigned unique identifier for this order (UUID). - `AccountID int64` Account placing the order - `ClientOrderID string` Client-provided identifier echoed back (FIX tag 11). - `CreatedAt Time` Timestamp when order was created (UTC) - `FilledQuantity string` Cumulative filled quantity - `InstrumentID string` OEMS instrument UUID for the traded instrument. - `InstrumentType SecurityType` Type of security - `const SecurityTypeCommonStock SecurityType = "COMMON_STOCK"` - `const SecurityTypePreferredStock SecurityType = "PREFERRED_STOCK"` - `const SecurityTypeOption SecurityType = "OPTION"` - `const SecurityTypeCash SecurityType = "CASH"` - `const SecurityTypeOther SecurityType = "OTHER"` - `LeavesQuantity string` Remaining unfilled quantity - `OrderType OrderType` Type of order (MARKET, LIMIT, etc.) - `const OrderTypeMarket OrderType = "MARKET"` - `const OrderTypeLimit OrderType = "LIMIT"` - `const OrderTypeStop OrderType = "STOP"` - `const OrderTypeStopLimit OrderType = "STOP_LIMIT"` - `const OrderTypeTrailingStop OrderType = "TRAILING_STOP"` - `const OrderTypeTrailingStopLimit OrderType = "TRAILING_STOP_LIMIT"` - `const OrderTypeOther OrderType = "OTHER"` - `Quantity string` Total order quantity - `Side Side` Side of the order (BUY, SELL, SELL_SHORT) - `const SideBuy Side = "BUY"` - `const SideSell Side = "SELL"` - `const SideSellShort Side = "SELL_SHORT"` - `const SideOther Side = "OTHER"` - `Status OrderStatus` Current status of the order - `const OrderStatusPendingNew OrderStatus = "PENDING_NEW"` - `const OrderStatusNew OrderStatus = "NEW"` - `const OrderStatusPartiallyFilled OrderStatus = "PARTIALLY_FILLED"` - `const OrderStatusFilled OrderStatus = "FILLED"` - `const OrderStatusCanceled OrderStatus = "CANCELED"` - `const OrderStatusRejected OrderStatus = "REJECTED"` - `const OrderStatusExpired OrderStatus = "EXPIRED"` - `const OrderStatusPendingCancel OrderStatus = "PENDING_CANCEL"` - `const OrderStatusPendingReplace OrderStatus = "PENDING_REPLACE"` - `const OrderStatusReplaced OrderStatus = "REPLACED"` - `const OrderStatusDoneForDay OrderStatus = "DONE_FOR_DAY"` - `const OrderStatusStopped OrderStatus = "STOPPED"` - `const OrderStatusSuspended OrderStatus = "SUSPENDED"` - `const OrderStatusCalculated OrderStatus = "CALCULATED"` - `const OrderStatusOther OrderStatus = "OTHER"` - `Symbol string` Trading symbol - `TimeInForce TimeInForce` Time in force instruction - `const TimeInForceDay TimeInForce = "DAY"` - `const TimeInForceGoodTillCancel TimeInForce = "GOOD_TILL_CANCEL"` - `const TimeInForceImmediateOrCancel TimeInForce = "IMMEDIATE_OR_CANCEL"` - `const TimeInForceFillOrKill TimeInForce = "FILL_OR_KILL"` - `const TimeInForceGoodTillDate TimeInForce = "GOOD_TILL_DATE"` - `const TimeInForceAtTheOpening TimeInForce = "AT_THE_OPENING"` - `const TimeInForceAtTheClose TimeInForce = "AT_THE_CLOSE"` - `const TimeInForceGoodTillCrossing TimeInForce = "GOOD_TILL_CROSSING"` - `const TimeInForceGoodThroughCrossing TimeInForce = "GOOD_THROUGH_CROSSING"` - `const TimeInForceAtCrossing TimeInForce = "AT_CROSSING"` - `const TimeInForceOther TimeInForce = "OTHER"` - `UpdatedAt Time` Timestamp of the most recent update (UTC) - `Venue string` MIC code of the venue where the order is routed - `AverageFillPrice string` Average fill price across all executions - `Details []string` Contains execution, rejection or cancellation details, if any - `ExpiresAt Time` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `ExtendedHours bool` Whether the order is eligible for extended-hours trading. - `LimitOffset string` Limit offset for trailing stop-limit orders (signed) - `LimitPrice string` Limit price (for LIMIT and STOP_LIMIT orders) - `QueueState QueueState` Parent order queue state, present when the order is awaiting release or released. - `const QueueStateAwaitingRelease QueueState = "AWAITING_RELEASE"` - `const QueueStateReleased QueueState = "RELEASED"` - `ReleasesAt Time` Scheduled release time for orders awaiting release. - `StopPrice string` Stop price (for STOP and STOP_LIMIT orders) - `TrailingLimitPx string` Current trailing limit price computed by the trailing strategy - `TrailingOffset string` Trailing offset amount for trailing orders - `TrailingOffsetType TrailingOffsetType` Trailing offset type for trailing orders - `const TrailingOffsetTypePrice TrailingOffsetType = "PRICE"` - `const TrailingOffsetTypeBps TrailingOffsetType = "BPS"` - `TrailingStopPx string` Current trailing stop price computed by the trailing strategy - `TrailingWatermarkPx string` Trailing watermark price for trailing orders - `TrailingWatermarkTs Time` Trailing watermark timestamp for trailing orders - `UnderlyingInstrumentID 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 ```go package main import ( "context" "fmt" "github.com/clear-street/clear-street-go" "github.com/clear-street/clear-street-go/option" ) func main() { client := clearstreet.NewClient( option.WithAPIKey("My API Key"), ) response, err := client.V1.Positions.ClosePosition( context.TODO(), "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", clearstreet.V1PositionClosePositionParams{ AccountID: 0, }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", 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(ctx, accountID, query) (*V1PositionGetPositionInstructionsResponse, error)` **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 int64` - `query V1PositionGetPositionInstructionsParams` - `InstrumentID param.Field[InstrumentIDOrSymbol]` Limit results to a single contract. Accepts the instrument id or the OSI symbol. ### Returns - `type V1PositionGetPositionInstructionsResponse struct{…}` - `Data PositionInstructionList` - `ID string` Server-assigned id. Used as the path parameter on cancel. - `AccountID int64` Account the instruction belongs to. - `InstructionID string` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `InstructionType PositionInstructionType` The action this instruction requests. - `const PositionInstructionTypeExercise PositionInstructionType = "EXERCISE"` - `const PositionInstructionTypeDoNotExercise PositionInstructionType = "DO_NOT_EXERCISE"` - `const PositionInstructionTypeContraryExercise PositionInstructionType = "CONTRARY_EXERCISE"` - `InstrumentID string` Identifier of the options contract this instruction acts on. - `Quantity string` Number of contracts included in the instruction. - `Status PositionInstructionStatus` Current lifecycle status. - `const PositionInstructionStatusSent PositionInstructionStatus = "SENT"` - `const PositionInstructionStatusAccepted PositionInstructionStatus = "ACCEPTED"` - `const PositionInstructionStatusRejected PositionInstructionStatus = "REJECTED"` - `const PositionInstructionStatusEngineRejected PositionInstructionStatus = "ENGINE_REJECTED"` - `const PositionInstructionStatusCancelRequested PositionInstructionStatus = "CANCEL_REQUESTED"` - `const PositionInstructionStatusCancelled PositionInstructionStatus = "CANCELLED"` - `const PositionInstructionStatusCancelFailed PositionInstructionStatus = "CANCEL_FAILED"` - `const PositionInstructionStatusUnknown PositionInstructionStatus = "UNKNOWN"` - `Symbol string` Options symbol (OSI) for display. - `AcceptedQuantity string` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `CreatedAt Time` When the instruction was first accepted by the service. - `RejectionReason 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. - `UpdatedAt Time` When the instruction's lifecycle state last changed. ### Example ```go package main import ( "context" "fmt" "github.com/clear-street/clear-street-go" "github.com/clear-street/clear-street-go/option" ) func main() { client := clearstreet.NewClient( option.WithAPIKey("My API Key"), ) response, err := client.V1.Positions.GetPositionInstructions( context.TODO(), 0, clearstreet.V1PositionGetPositionInstructionsParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", 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(ctx, accountID, body) (*V1PositionSubmitPositionInstructionsResponse, error)` **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 int64` - `body V1PositionSubmitPositionInstructionsParams` - `Instructions param.Field[[]V1PositionSubmitPositionInstructionsParamsInstruction]` - `InstructionType PositionInstructionType` The action to take. - `const PositionInstructionTypeExercise PositionInstructionType = "EXERCISE"` - `const PositionInstructionTypeDoNotExercise PositionInstructionType = "DO_NOT_EXERCISE"` - `const PositionInstructionTypeContraryExercise PositionInstructionType = "CONTRARY_EXERCISE"` - `InstrumentID string` Identifier of the options contract to act on. Unknown ids return 404. - `Quantity string` Number of contracts to include in the instruction. - `InstructionID string` Caller-supplied idempotency key. Echoed on the response. The server generates a unique id when omitted. ### Returns - `type V1PositionSubmitPositionInstructionsResponse struct{…}` - `Data PositionInstructionList` - `ID string` Server-assigned id. Used as the path parameter on cancel. - `AccountID int64` Account the instruction belongs to. - `InstructionID string` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `InstructionType PositionInstructionType` The action this instruction requests. - `const PositionInstructionTypeExercise PositionInstructionType = "EXERCISE"` - `const PositionInstructionTypeDoNotExercise PositionInstructionType = "DO_NOT_EXERCISE"` - `const PositionInstructionTypeContraryExercise PositionInstructionType = "CONTRARY_EXERCISE"` - `InstrumentID string` Identifier of the options contract this instruction acts on. - `Quantity string` Number of contracts included in the instruction. - `Status PositionInstructionStatus` Current lifecycle status. - `const PositionInstructionStatusSent PositionInstructionStatus = "SENT"` - `const PositionInstructionStatusAccepted PositionInstructionStatus = "ACCEPTED"` - `const PositionInstructionStatusRejected PositionInstructionStatus = "REJECTED"` - `const PositionInstructionStatusEngineRejected PositionInstructionStatus = "ENGINE_REJECTED"` - `const PositionInstructionStatusCancelRequested PositionInstructionStatus = "CANCEL_REQUESTED"` - `const PositionInstructionStatusCancelled PositionInstructionStatus = "CANCELLED"` - `const PositionInstructionStatusCancelFailed PositionInstructionStatus = "CANCEL_FAILED"` - `const PositionInstructionStatusUnknown PositionInstructionStatus = "UNKNOWN"` - `Symbol string` Options symbol (OSI) for display. - `AcceptedQuantity string` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `CreatedAt Time` When the instruction was first accepted by the service. - `RejectionReason 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. - `UpdatedAt Time` When the instruction's lifecycle state last changed. ### Example ```go package main import ( "context" "fmt" "github.com/clear-street/clear-street-go" "github.com/clear-street/clear-street-go/option" ) func main() { client := clearstreet.NewClient( option.WithAPIKey("My API Key"), ) response, err := client.V1.Positions.SubmitPositionInstructions( context.TODO(), 0, clearstreet.V1PositionSubmitPositionInstructionsParams{ Instructions: []clearstreet.V1PositionSubmitPositionInstructionsParamsInstruction{clearstreet.V1PositionSubmitPositionInstructionsParamsInstruction{ InstructionType: clearstreet.PositionInstructionTypeExercise, InstrumentID: "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02", Quantity: "1", }}, }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", 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(ctx, instructionID, body) (*V1PositionCancelPositionInstructionResponse, error)` **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` - `body V1PositionCancelPositionInstructionParams` - `AccountID param.Field[int64]` Account identifier ### Returns - `type V1PositionCancelPositionInstructionResponse struct{…}` - `Data PositionInstruction` A position instruction and its current lifecycle state. - `ID string` Server-assigned id. Used as the path parameter on cancel. - `AccountID int64` Account the instruction belongs to. - `InstructionID string` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `InstructionType PositionInstructionType` The action this instruction requests. - `const PositionInstructionTypeExercise PositionInstructionType = "EXERCISE"` - `const PositionInstructionTypeDoNotExercise PositionInstructionType = "DO_NOT_EXERCISE"` - `const PositionInstructionTypeContraryExercise PositionInstructionType = "CONTRARY_EXERCISE"` - `InstrumentID string` Identifier of the options contract this instruction acts on. - `Quantity string` Number of contracts included in the instruction. - `Status PositionInstructionStatus` Current lifecycle status. - `const PositionInstructionStatusSent PositionInstructionStatus = "SENT"` - `const PositionInstructionStatusAccepted PositionInstructionStatus = "ACCEPTED"` - `const PositionInstructionStatusRejected PositionInstructionStatus = "REJECTED"` - `const PositionInstructionStatusEngineRejected PositionInstructionStatus = "ENGINE_REJECTED"` - `const PositionInstructionStatusCancelRequested PositionInstructionStatus = "CANCEL_REQUESTED"` - `const PositionInstructionStatusCancelled PositionInstructionStatus = "CANCELLED"` - `const PositionInstructionStatusCancelFailed PositionInstructionStatus = "CANCEL_FAILED"` - `const PositionInstructionStatusUnknown PositionInstructionStatus = "UNKNOWN"` - `Symbol string` Options symbol (OSI) for display. - `AcceptedQuantity string` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `CreatedAt Time` When the instruction was first accepted by the service. - `RejectionReason 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. - `UpdatedAt Time` When the instruction's lifecycle state last changed. ### Example ```go package main import ( "context" "fmt" "github.com/clear-street/clear-street-go" "github.com/clear-street/clear-street-go/option" ) func main() { client := clearstreet.NewClient( option.WithAPIKey("My API Key"), ) response, err := client.V1.Positions.CancelPositionInstruction( context.TODO(), "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", clearstreet.V1PositionCancelPositionInstructionParams{ AccountID: 0, }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", 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 - `type Position struct{…}` Represents a holding of a particular instrument in an account - `AccountID int64` The account this position belongs to - `AvailableQuantity string` The quantity of a position that is free to be operated on. - `InstrumentID string` OEMS instrument UUID - `InstrumentType SecurityType` Type of security - `const SecurityTypeCommonStock SecurityType = "COMMON_STOCK"` - `const SecurityTypePreferredStock SecurityType = "PREFERRED_STOCK"` - `const SecurityTypeOption SecurityType = "OPTION"` - `const SecurityTypeCash SecurityType = "CASH"` - `const SecurityTypeOther SecurityType = "OTHER"` - `MarketValue string` The current market value of the position - `PositionType PositionType` The type of position - `const PositionTypeLong PositionType = "LONG"` - `const PositionTypeShort PositionType = "SHORT"` - `const PositionTypeLongCall PositionType = "LONG_CALL"` - `const PositionTypeShortCall PositionType = "SHORT_CALL"` - `const PositionTypeLongPut PositionType = "LONG_PUT"` - `const PositionTypeShortPut PositionType = "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 - `AvgPrice string` The average price paid per share or contract for this position - `ClosingPrice string` The closing price used to value the position for the last trading day - `ClosingPriceDate Time` The market date associated with `closing_price` - `CostBasis string` The total cost basis for this position - `DailyUnrealizedPnl string` The unrealized profit or loss for this position relative to the previous close - `DailyUnrealizedPnlPct string` The unrealized profit/loss for the position for the current day, expressed as a percentage of the baseline value (range: 0-100). - `InstrumentPrice string` The current market price of the instrument - `UnderlyingInstrumentID string` OEMS instrument identifier of the underlying instrument, if resolvable - `UnrealizedPnl string` The total unrealized profit or loss for this position based on current market value - `UnrealizedPnlPct string` The unrealized profit/loss for the position, expressed as a percentage of the position's cost basis (range: 0-100). ### Position Instruction - `type PositionInstruction struct{…}` A position instruction and its current lifecycle state. - `ID string` Server-assigned id. Used as the path parameter on cancel. - `AccountID int64` Account the instruction belongs to. - `InstructionID string` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `InstructionType PositionInstructionType` The action this instruction requests. - `const PositionInstructionTypeExercise PositionInstructionType = "EXERCISE"` - `const PositionInstructionTypeDoNotExercise PositionInstructionType = "DO_NOT_EXERCISE"` - `const PositionInstructionTypeContraryExercise PositionInstructionType = "CONTRARY_EXERCISE"` - `InstrumentID string` Identifier of the options contract this instruction acts on. - `Quantity string` Number of contracts included in the instruction. - `Status PositionInstructionStatus` Current lifecycle status. - `const PositionInstructionStatusSent PositionInstructionStatus = "SENT"` - `const PositionInstructionStatusAccepted PositionInstructionStatus = "ACCEPTED"` - `const PositionInstructionStatusRejected PositionInstructionStatus = "REJECTED"` - `const PositionInstructionStatusEngineRejected PositionInstructionStatus = "ENGINE_REJECTED"` - `const PositionInstructionStatusCancelRequested PositionInstructionStatus = "CANCEL_REQUESTED"` - `const PositionInstructionStatusCancelled PositionInstructionStatus = "CANCELLED"` - `const PositionInstructionStatusCancelFailed PositionInstructionStatus = "CANCEL_FAILED"` - `const PositionInstructionStatusUnknown PositionInstructionStatus = "UNKNOWN"` - `Symbol string` Options symbol (OSI) for display. - `AcceptedQuantity string` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `CreatedAt Time` When the instruction was first accepted by the service. - `RejectionReason 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. - `UpdatedAt Time` When the instruction's lifecycle state last changed. ### Position Instruction List - `type PositionInstructionList []PositionInstruction` - `ID string` Server-assigned id. Used as the path parameter on cancel. - `AccountID int64` Account the instruction belongs to. - `InstructionID string` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `InstructionType PositionInstructionType` The action this instruction requests. - `const PositionInstructionTypeExercise PositionInstructionType = "EXERCISE"` - `const PositionInstructionTypeDoNotExercise PositionInstructionType = "DO_NOT_EXERCISE"` - `const PositionInstructionTypeContraryExercise PositionInstructionType = "CONTRARY_EXERCISE"` - `InstrumentID string` Identifier of the options contract this instruction acts on. - `Quantity string` Number of contracts included in the instruction. - `Status PositionInstructionStatus` Current lifecycle status. - `const PositionInstructionStatusSent PositionInstructionStatus = "SENT"` - `const PositionInstructionStatusAccepted PositionInstructionStatus = "ACCEPTED"` - `const PositionInstructionStatusRejected PositionInstructionStatus = "REJECTED"` - `const PositionInstructionStatusEngineRejected PositionInstructionStatus = "ENGINE_REJECTED"` - `const PositionInstructionStatusCancelRequested PositionInstructionStatus = "CANCEL_REQUESTED"` - `const PositionInstructionStatusCancelled PositionInstructionStatus = "CANCELLED"` - `const PositionInstructionStatusCancelFailed PositionInstructionStatus = "CANCEL_FAILED"` - `const PositionInstructionStatusUnknown PositionInstructionStatus = "UNKNOWN"` - `Symbol string` Options symbol (OSI) for display. - `AcceptedQuantity string` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `CreatedAt Time` When the instruction was first accepted by the service. - `RejectionReason 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. - `UpdatedAt Time` When the instruction's lifecycle state last changed. ### Position Instruction Status - `type PositionInstructionStatus string` Lifecycle status of a position instruction. - `const PositionInstructionStatusSent PositionInstructionStatus = "SENT"` - `const PositionInstructionStatusAccepted PositionInstructionStatus = "ACCEPTED"` - `const PositionInstructionStatusRejected PositionInstructionStatus = "REJECTED"` - `const PositionInstructionStatusEngineRejected PositionInstructionStatus = "ENGINE_REJECTED"` - `const PositionInstructionStatusCancelRequested PositionInstructionStatus = "CANCEL_REQUESTED"` - `const PositionInstructionStatusCancelled PositionInstructionStatus = "CANCELLED"` - `const PositionInstructionStatusCancelFailed PositionInstructionStatus = "CANCEL_FAILED"` - `const PositionInstructionStatusUnknown PositionInstructionStatus = "UNKNOWN"` ### Position Instruction Type - `type PositionInstructionType string` The action to take against an options position. - `const PositionInstructionTypeExercise PositionInstructionType = "EXERCISE"` - `const PositionInstructionTypeDoNotExercise PositionInstructionType = "DO_NOT_EXERCISE"` - `const PositionInstructionTypeContraryExercise PositionInstructionType = "CONTRARY_EXERCISE"` ### Position List - `type PositionList []Position` - `AccountID int64` The account this position belongs to - `AvailableQuantity string` The quantity of a position that is free to be operated on. - `InstrumentID string` OEMS instrument UUID - `InstrumentType SecurityType` Type of security - `const SecurityTypeCommonStock SecurityType = "COMMON_STOCK"` - `const SecurityTypePreferredStock SecurityType = "PREFERRED_STOCK"` - `const SecurityTypeOption SecurityType = "OPTION"` - `const SecurityTypeCash SecurityType = "CASH"` - `const SecurityTypeOther SecurityType = "OTHER"` - `MarketValue string` The current market value of the position - `PositionType PositionType` The type of position - `const PositionTypeLong PositionType = "LONG"` - `const PositionTypeShort PositionType = "SHORT"` - `const PositionTypeLongCall PositionType = "LONG_CALL"` - `const PositionTypeShortCall PositionType = "SHORT_CALL"` - `const PositionTypeLongPut PositionType = "LONG_PUT"` - `const PositionTypeShortPut PositionType = "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 - `AvgPrice string` The average price paid per share or contract for this position - `ClosingPrice string` The closing price used to value the position for the last trading day - `ClosingPriceDate Time` The market date associated with `closing_price` - `CostBasis string` The total cost basis for this position - `DailyUnrealizedPnl string` The unrealized profit or loss for this position relative to the previous close - `DailyUnrealizedPnlPct string` The unrealized profit/loss for the position for the current day, expressed as a percentage of the baseline value (range: 0-100). - `InstrumentPrice string` The current market price of the instrument - `UnderlyingInstrumentID string` OEMS instrument identifier of the underlying instrument, if resolvable - `UnrealizedPnl string` The total unrealized profit or loss for this position based on current market value - `UnrealizedPnlPct string` The unrealized profit/loss for the position, expressed as a percentage of the position's cost basis (range: 0-100). ### Position Type - `type PositionType string` Position type classification - `const PositionTypeLong PositionType = "LONG"` - `const PositionTypeShort PositionType = "SHORT"` - `const PositionTypeLongCall PositionType = "LONG_CALL"` - `const PositionTypeShortCall PositionType = "SHORT_CALL"` - `const PositionTypeLongPut PositionType = "LONG_PUT"` - `const PositionTypeShortPut PositionType = "SHORT_PUT"`