Positions
View positions and manage position instructions.
Get Positions
Close Positions
Close Position
Get Position Instructions
Submit Position Instructions
Cancel Position Instruction
ModelsExpand Collapse
class Position: …
Represents a holding of a particular instrument in an account
avg_price: Optional[str]
The average price paid per share or contract for this position When a null/undefined value is observed, it indicates that there is no available data.
closing_price: Optional[str]
The closing price used to value the position for the last trading day When a null/undefined value is observed, it indicates that there is no available data.
closing_price_date: Optional[date]
The market date associated with closing_price
When a null/undefined value is observed, it indicates that there is no available data.
cost_basis: Optional[str]
The total cost basis for this position When a null/undefined value is observed, it indicates that there is no available data.
daily_realized_pnl: Optional[str]
The realized profit or loss for this position for the current day When a null/undefined value is observed, it indicates that there is no available data.
daily_unrealized_pnl: Optional[str]
The unrealized profit or loss for this position relative to the previous close When a null/undefined value is observed, it indicates that there is no available data.
daily_unrealized_pnl_pct: Optional[str]
The unrealized profit/loss for the position for the current day, expressed as a percentage of the baseline value (range: 0-100). When a null/undefined value is observed, it indicates that there is no available data.
instrument_price: Optional[str]
The current market price of the instrument When a null/undefined value is observed, it indicates that there is no available data.
underlying_instrument_id: Optional[str]
Identifier of the underlying instrument, when available When a null/undefined value is observed, it indicates it does not apply.
class PositionInstruction: …
A position instruction and its current lifecycle state.
client_instruction_id: str
Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied.
accepted_quantity: Optional[str]
Number of contracts accepted by the clearing venue. Populated once
the instruction reaches ACCEPTED.
When a null/undefined value is observed, it indicates that there is no available data.
created_at: Optional[datetime]
When the instruction was first accepted by the service. When a null/undefined value is observed, it indicates that there is no available data.
rejection: Optional[PositionInstructionRejection]
Machine-readable counterpart to rejection_reason: a stable reason code,
human-readable description, and params, present on every rejected row —
on submit, cancel, get, and list alike. Branch on rejection.reason and
read rejection.description instead of the top-level rejection_reason.
When a null/undefined value is observed, it indicates it does not apply.
description: str
Human-readable explanation of the rejection. Duplicates the top-level
rejection_reason; prefer this field.
domain: str
Namespacing domain of the reason code — com.clearstreet.oems.exercise
for reasons OEMS validates, com.clearstreet.oems.clearing for
clearing-owned reasons.
metadata: Dict[str, str]
Reason-specific parameters as a string→string map. Which keys are present
depends on reason:
INSUFFICIENT_POSITION→available,requestedDNE_NOT_ON_EXPIRY/CEA_NOT_ON_EXPIRY→expiry,business_dateEXERCISE_PAST_CUTOFF→cutoff_timeDUPLICATE_INSTRUCTION→existing_id
Empty for reasons that carry no parameters. New keys may be added over time, so treat unknown keys leniently.
rejection_reason: Optional[str]
Human-readable explanation populated on any non-success terminal
status — 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.
When a null/undefined value is observed, it indicates it does not apply.
List[PositionInstruction]
client_instruction_id: str
Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied.
accepted_quantity: Optional[str]
Number of contracts accepted by the clearing venue. Populated once
the instruction reaches ACCEPTED.
When a null/undefined value is observed, it indicates that there is no available data.
created_at: Optional[datetime]
When the instruction was first accepted by the service. When a null/undefined value is observed, it indicates that there is no available data.
rejection: Optional[PositionInstructionRejection]
Machine-readable counterpart to rejection_reason: a stable reason code,
human-readable description, and params, present on every rejected row —
on submit, cancel, get, and list alike. Branch on rejection.reason and
read rejection.description instead of the top-level rejection_reason.
When a null/undefined value is observed, it indicates it does not apply.
description: str
Human-readable explanation of the rejection. Duplicates the top-level
rejection_reason; prefer this field.
domain: str
Namespacing domain of the reason code — com.clearstreet.oems.exercise
for reasons OEMS validates, com.clearstreet.oems.clearing for
clearing-owned reasons.
metadata: Dict[str, str]
Reason-specific parameters as a string→string map. Which keys are present
depends on reason:
INSUFFICIENT_POSITION→available,requestedDNE_NOT_ON_EXPIRY/CEA_NOT_ON_EXPIRY→expiry,business_dateEXERCISE_PAST_CUTOFF→cutoff_timeDUPLICATE_INSTRUCTION→existing_id
Empty for reasons that carry no parameters. New keys may be added over time, so treat unknown keys leniently.
rejection_reason: Optional[str]
Human-readable explanation populated on any non-success terminal
status — 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.
When a null/undefined value is observed, it indicates it does not apply.
class PositionInstructionRejection: …
Machine-readable detail for a rejected position instruction.
Present on every rejected row, across the full lifecycle — submit, cancel,
get, and list. Branch on reason for programmatic handling and template your
own copy from metadata, or show description directly.
description: str
Human-readable explanation of the rejection. Duplicates the top-level
rejection_reason; prefer this field.
domain: str
Namespacing domain of the reason code — com.clearstreet.oems.exercise
for reasons OEMS validates, com.clearstreet.oems.clearing for
clearing-owned reasons.
metadata: Dict[str, str]
Reason-specific parameters as a string→string map. Which keys are present
depends on reason:
INSUFFICIENT_POSITION→available,requestedDNE_NOT_ON_EXPIRY/CEA_NOT_ON_EXPIRY→expiry,business_dateEXERCISE_PAST_CUTOFF→cutoff_timeDUPLICATE_INSTRUCTION→existing_id
Empty for reasons that carry no parameters. New keys may be added over time, so treat unknown keys leniently.
Literal["SENT", "ACCEPTED", "REJECTED", 4 more]
Lifecycle status of a position instruction.
SENT: accepted and submitted to the clearing venue.ACCEPTED: terminal — accepted by the clearing venue.REJECTED: terminal rejection;rejection_reasoncarries the detail. Covers both venue-reported rejections and rejections raised before the instruction reached the clearing venue (e.g. duplicateclient_instruction_id,DO_NOT_EXERCISE/CONTRARY_EXERCISEsubmitted on a non-expiry day, insufficient position, or an instrument that does not resolve).CANCEL_REQUESTED: cancel accepted; final cancel state pending.CANCELLED: terminal — cancel completed.CANCEL_FAILED: cancel could not be completed; operator attention required.rejection_reasoncarries the detail.UNKNOWN: status could not be determined.
List[Position]
avg_price: Optional[str]
The average price paid per share or contract for this position When a null/undefined value is observed, it indicates that there is no available data.
closing_price: Optional[str]
The closing price used to value the position for the last trading day When a null/undefined value is observed, it indicates that there is no available data.
closing_price_date: Optional[date]
The market date associated with closing_price
When a null/undefined value is observed, it indicates that there is no available data.
cost_basis: Optional[str]
The total cost basis for this position When a null/undefined value is observed, it indicates that there is no available data.
daily_realized_pnl: Optional[str]
The realized profit or loss for this position for the current day When a null/undefined value is observed, it indicates that there is no available data.
daily_unrealized_pnl: Optional[str]
The unrealized profit or loss for this position relative to the previous close When a null/undefined value is observed, it indicates that there is no available data.
daily_unrealized_pnl_pct: Optional[str]
The unrealized profit/loss for the position for the current day, expressed as a percentage of the baseline value (range: 0-100). When a null/undefined value is observed, it indicates that there is no available data.
instrument_price: Optional[str]
The current market price of the instrument When a null/undefined value is observed, it indicates that there is no available data.
underlying_instrument_id: Optional[str]
Identifier of the underlying instrument, when available When a null/undefined value is observed, it indicates it does not apply.
class PositionGetPositionsResponse: …
avg_price: Optional[str]
The average price paid per share or contract for this position When a null/undefined value is observed, it indicates that there is no available data.
closing_price: Optional[str]
The closing price used to value the position for the last trading day When a null/undefined value is observed, it indicates that there is no available data.
closing_price_date: Optional[date]
The market date associated with closing_price
When a null/undefined value is observed, it indicates that there is no available data.
cost_basis: Optional[str]
The total cost basis for this position When a null/undefined value is observed, it indicates that there is no available data.
daily_realized_pnl: Optional[str]
The realized profit or loss for this position for the current day When a null/undefined value is observed, it indicates that there is no available data.
daily_unrealized_pnl: Optional[str]
The unrealized profit or loss for this position relative to the previous close When a null/undefined value is observed, it indicates that there is no available data.
daily_unrealized_pnl_pct: Optional[str]
The unrealized profit/loss for the position for the current day, expressed as a percentage of the baseline value (range: 0-100). When a null/undefined value is observed, it indicates that there is no available data.
instrument_price: Optional[str]
The current market price of the instrument When a null/undefined value is observed, it indicates that there is no available data.
underlying_instrument_id: Optional[str]
Identifier of the underlying instrument, when available When a null/undefined value is observed, it indicates it does not apply.
class PositionClosePositionsResponse: …
average_fill_price: Optional[str]
Average fill price across all executions. For multileg orders this is the venue’s strategy-level average when reported, else the signed net package price derived from the leg averages: net debit positive, net credit negative, zero possible. When a null/undefined value is observed, it indicates that there is no available data.
expires_at: Optional[datetime]
Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. When a null/undefined value is observed, it indicates it does not apply.
instrument_id: Optional[str]
Instrument identifier for the traded instrument. null when the order has
no single resolvable instrument.
When a null/undefined value is observed, it indicates it does not apply.
limit_offset: Optional[str]
Limit offset for trailing stop-limit orders (signed) When a null/undefined value is observed, it indicates it does not apply.
limit_price: Optional[str]
Limit price (for LIMIT and STOP_LIMIT orders) When a null/undefined value is observed, it indicates it does not apply.
releases_at: Optional[datetime]
Scheduled release time for orders awaiting release. When a null/undefined value is observed, it indicates it does not apply.
stop_price: Optional[str]
Stop price (for STOP and STOP_LIMIT orders) When a null/undefined value is observed, it indicates it does not apply.
symbol: Optional[str]
Trading symbol. null when the order has no single resolvable instrument.
When a null/undefined value is observed, it indicates it does not apply.
trailing_limit_px: Optional[str]
Current trailing limit price computed by the trailing strategy When a null/undefined value is observed, it indicates it does not apply.
trailing_offset: Optional[str]
Trailing offset amount for trailing orders When a null/undefined value is observed, it indicates it does not apply.
trailing_stop_px: Optional[str]
Current trailing stop price computed by the trailing strategy When a null/undefined value is observed, it indicates it does not apply.
trailing_watermark_px: Optional[str]
Trailing watermark price for trailing orders. Strategy-computed, so it is absent on the order-submission acknowledgement and only appears once fetched via the order fetch or list endpoints. When a null/undefined value is observed, it indicates it does not apply.
trailing_watermark_ts: Optional[datetime]
Trailing watermark timestamp for trailing orders. Strategy-computed, so it is absent on the order-submission acknowledgement and only appears once fetched via the order fetch or list endpoints. When a null/undefined value is observed, it indicates it does not apply.
underlying_instrument_id: Optional[str]
Instrument ID of the option’s underlying instrument. Populated only for
options orders. A null means one of two things: the order is not an
option, so the field does not apply; or the order is an option whose
underlier has not yet been resolved.
When a null/undefined value is observed, it indicates it does not apply.
class PositionClosePositionResponse: …
average_fill_price: Optional[str]
Average fill price across all executions. For multileg orders this is the venue’s strategy-level average when reported, else the signed net package price derived from the leg averages: net debit positive, net credit negative, zero possible. When a null/undefined value is observed, it indicates that there is no available data.
expires_at: Optional[datetime]
Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. When a null/undefined value is observed, it indicates it does not apply.
instrument_id: Optional[str]
Instrument identifier for the traded instrument. null when the order has
no single resolvable instrument.
When a null/undefined value is observed, it indicates it does not apply.
limit_offset: Optional[str]
Limit offset for trailing stop-limit orders (signed) When a null/undefined value is observed, it indicates it does not apply.
limit_price: Optional[str]
Limit price (for LIMIT and STOP_LIMIT orders) When a null/undefined value is observed, it indicates it does not apply.
releases_at: Optional[datetime]
Scheduled release time for orders awaiting release. When a null/undefined value is observed, it indicates it does not apply.
stop_price: Optional[str]
Stop price (for STOP and STOP_LIMIT orders) When a null/undefined value is observed, it indicates it does not apply.
symbol: Optional[str]
Trading symbol. null when the order has no single resolvable instrument.
When a null/undefined value is observed, it indicates it does not apply.
trailing_limit_px: Optional[str]
Current trailing limit price computed by the trailing strategy When a null/undefined value is observed, it indicates it does not apply.
trailing_offset: Optional[str]
Trailing offset amount for trailing orders When a null/undefined value is observed, it indicates it does not apply.
trailing_stop_px: Optional[str]
Current trailing stop price computed by the trailing strategy When a null/undefined value is observed, it indicates it does not apply.
trailing_watermark_px: Optional[str]
Trailing watermark price for trailing orders. Strategy-computed, so it is absent on the order-submission acknowledgement and only appears once fetched via the order fetch or list endpoints. When a null/undefined value is observed, it indicates it does not apply.
trailing_watermark_ts: Optional[datetime]
Trailing watermark timestamp for trailing orders. Strategy-computed, so it is absent on the order-submission acknowledgement and only appears once fetched via the order fetch or list endpoints. When a null/undefined value is observed, it indicates it does not apply.
underlying_instrument_id: Optional[str]
Instrument ID of the option’s underlying instrument. Populated only for
options orders. A null means one of two things: the order is not an
option, so the field does not apply; or the order is an option whose
underlier has not yet been resolved.
When a null/undefined value is observed, it indicates it does not apply.
class PositionGetPositionInstructionsResponse: …
client_instruction_id: str
Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied.
accepted_quantity: Optional[str]
Number of contracts accepted by the clearing venue. Populated once
the instruction reaches ACCEPTED.
When a null/undefined value is observed, it indicates that there is no available data.
created_at: Optional[datetime]
When the instruction was first accepted by the service. When a null/undefined value is observed, it indicates that there is no available data.
rejection: Optional[PositionInstructionRejection]
Machine-readable counterpart to rejection_reason: a stable reason code,
human-readable description, and params, present on every rejected row —
on submit, cancel, get, and list alike. Branch on rejection.reason and
read rejection.description instead of the top-level rejection_reason.
When a null/undefined value is observed, it indicates it does not apply.
description: str
Human-readable explanation of the rejection. Duplicates the top-level
rejection_reason; prefer this field.
domain: str
Namespacing domain of the reason code — com.clearstreet.oems.exercise
for reasons OEMS validates, com.clearstreet.oems.clearing for
clearing-owned reasons.
metadata: Dict[str, str]
Reason-specific parameters as a string→string map. Which keys are present
depends on reason:
INSUFFICIENT_POSITION→available,requestedDNE_NOT_ON_EXPIRY/CEA_NOT_ON_EXPIRY→expiry,business_dateEXERCISE_PAST_CUTOFF→cutoff_timeDUPLICATE_INSTRUCTION→existing_id
Empty for reasons that carry no parameters. New keys may be added over time, so treat unknown keys leniently.
rejection_reason: Optional[str]
Human-readable explanation populated on any non-success terminal
status — 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.
When a null/undefined value is observed, it indicates it does not apply.
class PositionSubmitPositionInstructionsResponse: …
client_instruction_id: str
Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied.
accepted_quantity: Optional[str]
Number of contracts accepted by the clearing venue. Populated once
the instruction reaches ACCEPTED.
When a null/undefined value is observed, it indicates that there is no available data.
created_at: Optional[datetime]
When the instruction was first accepted by the service. When a null/undefined value is observed, it indicates that there is no available data.
rejection: Optional[PositionInstructionRejection]
Machine-readable counterpart to rejection_reason: a stable reason code,
human-readable description, and params, present on every rejected row —
on submit, cancel, get, and list alike. Branch on rejection.reason and
read rejection.description instead of the top-level rejection_reason.
When a null/undefined value is observed, it indicates it does not apply.
description: str
Human-readable explanation of the rejection. Duplicates the top-level
rejection_reason; prefer this field.
domain: str
Namespacing domain of the reason code — com.clearstreet.oems.exercise
for reasons OEMS validates, com.clearstreet.oems.clearing for
clearing-owned reasons.
metadata: Dict[str, str]
Reason-specific parameters as a string→string map. Which keys are present
depends on reason:
INSUFFICIENT_POSITION→available,requestedDNE_NOT_ON_EXPIRY/CEA_NOT_ON_EXPIRY→expiry,business_dateEXERCISE_PAST_CUTOFF→cutoff_timeDUPLICATE_INSTRUCTION→existing_id
Empty for reasons that carry no parameters. New keys may be added over time, so treat unknown keys leniently.
rejection_reason: Optional[str]
Human-readable explanation populated on any non-success terminal
status — 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.
When a null/undefined value is observed, it indicates it does not apply.
class PositionCancelPositionInstructionResponse: …
A position instruction and its current lifecycle state.
client_instruction_id: str
Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied.
accepted_quantity: Optional[str]
Number of contracts accepted by the clearing venue. Populated once
the instruction reaches ACCEPTED.
When a null/undefined value is observed, it indicates that there is no available data.
created_at: Optional[datetime]
When the instruction was first accepted by the service. When a null/undefined value is observed, it indicates that there is no available data.
rejection: Optional[PositionInstructionRejection]
Machine-readable counterpart to rejection_reason: a stable reason code,
human-readable description, and params, present on every rejected row —
on submit, cancel, get, and list alike. Branch on rejection.reason and
read rejection.description instead of the top-level rejection_reason.
When a null/undefined value is observed, it indicates it does not apply.
description: str
Human-readable explanation of the rejection. Duplicates the top-level
rejection_reason; prefer this field.
domain: str
Namespacing domain of the reason code — com.clearstreet.oems.exercise
for reasons OEMS validates, com.clearstreet.oems.clearing for
clearing-owned reasons.
metadata: Dict[str, str]
Reason-specific parameters as a string→string map. Which keys are present
depends on reason:
INSUFFICIENT_POSITION→available,requestedDNE_NOT_ON_EXPIRY/CEA_NOT_ON_EXPIRY→expiry,business_dateEXERCISE_PAST_CUTOFF→cutoff_timeDUPLICATE_INSTRUCTION→existing_id
Empty for reasons that carry no parameters. New keys may be added over time, so treat unknown keys leniently.
rejection_reason: Optional[str]
Human-readable explanation populated on any non-success terminal
status — 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.
When a null/undefined value is observed, it indicates it does not apply.