Skip to content
Clear Street Clear Street
Get started
API Reference
V1

Positions

View positions and manage position instructions.

Get Positions
client.v1.positions.getPositions(numberaccountID, PositionGetPositionsParams { instrument_ids, page_size, page_token, 2 more } query?, RequestOptionsoptions?): PositionGetPositionsResponse { data }
GET/v1/accounts/{account_id}/positions
Close Positions
client.v1.positions.closePositions(numberaccountID, PositionClosePositionsParams { cancel_orders } body?, RequestOptionsoptions?): PositionClosePositionsResponse { data }
DELETE/v1/accounts/{account_id}/positions
Close Position
client.v1.positions.closePosition(InstrumentIDOrSymbolinstrumentID, PositionClosePositionParams { account_id, cancel_orders } params, RequestOptionsoptions?): PositionClosePositionResponse { data }
DELETE/v1/accounts/{account_id}/positions/{instrument_id}
List Position Instructions
client.v1.positions.getPositionInstructions(numberaccountID, PositionGetPositionInstructionsParams { instrument_id } query?, RequestOptionsoptions?): PositionGetPositionInstructionsResponse { data }
GET/v1/accounts/{account_id}/positions/instructions
Submit Position Instructions
client.v1.positions.submitPositionInstructions(numberaccountID, PositionSubmitPositionInstructionsParams { instructions } params, RequestOptionsoptions?): PositionSubmitPositionInstructionsResponse { data }
POST/v1/accounts/{account_id}/positions/instructions
Cancel Position Instruction
client.v1.positions.cancelPositionInstruction(stringinstructionID, PositionCancelPositionInstructionParams { account_id } params, RequestOptionsoptions?): PositionCancelPositionInstructionResponse { data }
DELETE/v1/accounts/{account_id}/positions/instructions/{instruction_id}
ModelsExpand Collapse
Position { 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

formatint64
available_quantity: string

The quantity of a position that is free to be operated on.

instrument_id: string

OEMS instrument UUID

formatuuid
instrument_type: SecurityType

Type of security

One of the following:
"COMMON_STOCK"
"PREFERRED_STOCK"
"OPTION"
"CASH"
"OTHER"
market_value: string

The current market value of the position

position_type: PositionType

The type of position

One of the following:
"LONG"
"SHORT"
"LONG_CALL"
"SHORT_CALL"
"LONG_PUT"
"SHORT_PUT"
quantity: string

The number of shares or contracts. Can be positive (long) or negative (short)

symbol: string

The trading symbol for the instrument

avg_price?: string | null

The average price paid per share or contract for this position

closing_price?: string | null

The closing price used to value the position for the last trading day

closing_price_date?: string | null

The market date associated with closing_price

formatdate
cost_basis?: string | null

The total cost basis for this position

daily_unrealized_pnl?: string | null

The unrealized profit or loss for this position relative to the previous close

daily_unrealized_pnl_pct?: string | null

The unrealized profit/loss for the position for the current day, expressed as a percentage of the baseline value (range: 0-100).

instrument_price?: string | null

The current market price of the instrument

underlying_instrument_id?: string | null

OEMS instrument identifier of the underlying instrument, if resolvable

formatuuid
unrealized_pnl?: string | null

The total unrealized profit or loss for this position based on current market value

unrealized_pnl_pct?: string | null

The unrealized profit/loss for the position, expressed as a percentage of the position’s cost basis (range: 0-100).

PositionInstruction { 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.

formatuuid
account_id: number

Account the instruction belongs to.

formatint64
instruction_id: string

Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied.

instruction_type: PositionInstructionType

The action this instruction requests.

One of the following:
"EXERCISE"
"DO_NOT_EXERCISE"
"CONTRARY_EXERCISE"
instrument_id: string

Identifier of the options contract this instruction acts on.

formatuuid
quantity: string

Number of contracts included in the instruction.

Current lifecycle status.

One of the following:
"SENT"
"ACCEPTED"
"REJECTED"
"ENGINE_REJECTED"
"CANCEL_REQUESTED"
"CANCELLED"
"CANCEL_FAILED"
"UNKNOWN"
symbol: string

Options symbol (OSI) for display.

accepted_quantity?: string | null

Number of contracts accepted by the clearing venue. Populated once the instruction reaches ACCEPTED.

created_at?: string | null

When the instruction was first accepted by the service.

formatdate-time
rejection_reason?: string | null

Human-readable explanation populated on any non-success terminal status — REJECTED, ENGINE_REJECTED, or CANCEL_FAILED. On a 207 Multi-Status batch submit the top-level error field summarizes the batch; per-row detail continues to live here.

updated_at?: string | null

When the instruction’s lifecycle state last changed.

formatdate-time
PositionInstructionList = Array<PositionInstruction { id, account_id, instruction_id, 9 more } >
id: string

Server-assigned id. Used as the path parameter on cancel.

formatuuid
account_id: number

Account the instruction belongs to.

formatint64
instruction_id: string

Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied.

instruction_type: PositionInstructionType

The action this instruction requests.

One of the following:
"EXERCISE"
"DO_NOT_EXERCISE"
"CONTRARY_EXERCISE"
instrument_id: string

Identifier of the options contract this instruction acts on.

formatuuid
quantity: string

Number of contracts included in the instruction.

Current lifecycle status.

One of the following:
"SENT"
"ACCEPTED"
"REJECTED"
"ENGINE_REJECTED"
"CANCEL_REQUESTED"
"CANCELLED"
"CANCEL_FAILED"
"UNKNOWN"
symbol: string

Options symbol (OSI) for display.

accepted_quantity?: string | null

Number of contracts accepted by the clearing venue. Populated once the instruction reaches ACCEPTED.

created_at?: string | null

When the instruction was first accepted by the service.

formatdate-time
rejection_reason?: string | null

Human-readable explanation populated on any non-success terminal status — REJECTED, ENGINE_REJECTED, or CANCEL_FAILED. On a 207 Multi-Status batch submit the top-level error field summarizes the batch; per-row detail continues to live here.

updated_at?: string | null

When the instruction’s lifecycle state last changed.

formatdate-time
PositionInstructionStatus = "SENT" | "ACCEPTED" | "REJECTED" | 5 more

Lifecycle status of a position instruction.

One of the following:
"SENT"
"ACCEPTED"
"REJECTED"
"ENGINE_REJECTED"
"CANCEL_REQUESTED"
"CANCELLED"
"CANCEL_FAILED"
"UNKNOWN"
PositionInstructionType = "EXERCISE" | "DO_NOT_EXERCISE" | "CONTRARY_EXERCISE"

The action to take against an options position.

One of the following:
"EXERCISE"
"DO_NOT_EXERCISE"
"CONTRARY_EXERCISE"
PositionList = Array<Position { account_id, available_quantity, instrument_id, 15 more } >
account_id: number

The account this position belongs to

formatint64
available_quantity: string

The quantity of a position that is free to be operated on.

instrument_id: string

OEMS instrument UUID

formatuuid
instrument_type: SecurityType

Type of security

One of the following:
"COMMON_STOCK"
"PREFERRED_STOCK"
"OPTION"
"CASH"
"OTHER"
market_value: string

The current market value of the position

position_type: PositionType

The type of position

One of the following:
"LONG"
"SHORT"
"LONG_CALL"
"SHORT_CALL"
"LONG_PUT"
"SHORT_PUT"
quantity: string

The number of shares or contracts. Can be positive (long) or negative (short)

symbol: string

The trading symbol for the instrument

avg_price?: string | null

The average price paid per share or contract for this position

closing_price?: string | null

The closing price used to value the position for the last trading day

closing_price_date?: string | null

The market date associated with closing_price

formatdate
cost_basis?: string | null

The total cost basis for this position

daily_unrealized_pnl?: string | null

The unrealized profit or loss for this position relative to the previous close

daily_unrealized_pnl_pct?: string | null

The unrealized profit/loss for the position for the current day, expressed as a percentage of the baseline value (range: 0-100).

instrument_price?: string | null

The current market price of the instrument

underlying_instrument_id?: string | null

OEMS instrument identifier of the underlying instrument, if resolvable

formatuuid
unrealized_pnl?: string | null

The total unrealized profit or loss for this position based on current market value

unrealized_pnl_pct?: string | null

The unrealized profit/loss for the position, expressed as a percentage of the position’s cost basis (range: 0-100).

PositionType = "LONG" | "SHORT" | "LONG_CALL" | 3 more

Position type classification

One of the following:
"LONG"
"SHORT"
"LONG_CALL"
"SHORT_CALL"
"LONG_PUT"
"SHORT_PUT"
PositionGetPositionsResponse extends BaseResponse { metadata, error } { data }
data: PositionList { account_id, available_quantity, instrument_id, 15 more }
account_id: number

The account this position belongs to

formatint64
available_quantity: string

The quantity of a position that is free to be operated on.

instrument_id: string

OEMS instrument UUID

formatuuid
instrument_type: SecurityType

Type of security

One of the following:
"COMMON_STOCK"
"PREFERRED_STOCK"
"OPTION"
"CASH"
"OTHER"
market_value: string

The current market value of the position

position_type: PositionType

The type of position

One of the following:
"LONG"
"SHORT"
"LONG_CALL"
"SHORT_CALL"
"LONG_PUT"
"SHORT_PUT"
quantity: string

The number of shares or contracts. Can be positive (long) or negative (short)

symbol: string

The trading symbol for the instrument

avg_price?: string | null

The average price paid per share or contract for this position

closing_price?: string | null

The closing price used to value the position for the last trading day

closing_price_date?: string | null

The market date associated with closing_price

formatdate
cost_basis?: string | null

The total cost basis for this position

daily_unrealized_pnl?: string | null

The unrealized profit or loss for this position relative to the previous close

daily_unrealized_pnl_pct?: string | null

The unrealized profit/loss for the position for the current day, expressed as a percentage of the baseline value (range: 0-100).

instrument_price?: string | null

The current market price of the instrument

underlying_instrument_id?: string | null

OEMS instrument identifier of the underlying instrument, if resolvable

formatuuid
unrealized_pnl?: string | null

The total unrealized profit or loss for this position based on current market value

unrealized_pnl_pct?: string | null

The unrealized profit/loss for the position, expressed as a percentage of the position’s cost basis (range: 0-100).

PositionClosePositionsResponse extends BaseResponse { metadata, error } { data }
data: OrderList { id, account_id, client_order_id, 29 more }
id: string

Engine-assigned unique identifier for this order (UUID).

account_id: number

Account placing the order

formatint64
client_order_id: string

Client-provided identifier echoed back (FIX tag 11).

created_at: string

Timestamp when order was created (UTC)

formatdate-time
filled_quantity: string

Cumulative filled quantity

instrument_id: string

OEMS instrument UUID for the traded instrument.

formatuuid
instrument_type: SecurityType

Type of security

One of the following:
"COMMON_STOCK"
"PREFERRED_STOCK"
"OPTION"
"CASH"
"OTHER"
leaves_quantity: string

Remaining unfilled quantity

order_type: OrderType

Type of order (MARKET, LIMIT, etc.)

One of the following:
"MARKET"
"LIMIT"
"STOP"
"STOP_LIMIT"
"TRAILING_STOP"
"TRAILING_STOP_LIMIT"
"OTHER"
quantity: string

Total order quantity

side: Side

Side of the order (BUY, SELL, SELL_SHORT)

One of the following:
"BUY"
"SELL"
"SELL_SHORT"
"OTHER"
status: OrderStatus

Current status of the order

One of the following:
"PENDING_NEW"
"NEW"
"PARTIALLY_FILLED"
"FILLED"
"CANCELED"
"REJECTED"
"EXPIRED"
"PENDING_CANCEL"
"PENDING_REPLACE"
"REPLACED"
"DONE_FOR_DAY"
"STOPPED"
"SUSPENDED"
"CALCULATED"
"OTHER"
symbol: string

Trading symbol

time_in_force: TimeInForce

Time in force instruction

One of the following:
"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)

formatdate-time
venue: string

MIC code of the venue where the order is routed

average_fill_price?: string | null

Average fill price across all executions

details?: Array<string>

Contains execution, rejection or cancellation details, if any

expires_at?: string | null

Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE.

formatdate-time
extended_hours?: boolean | null

Whether the order is eligible for extended-hours trading.

limit_offset?: string | null

Limit offset for trailing stop-limit orders (signed)

limit_price?: string | null

Limit price (for LIMIT and STOP_LIMIT orders)

queue_state?: QueueState | null

Parent order queue state, present when the order is awaiting release or released.

One of the following:
"AWAITING_RELEASE"
"RELEASED"
releases_at?: string | null

Scheduled release time for orders awaiting release.

formatdate-time
stop_price?: string | null

Stop price (for STOP and STOP_LIMIT orders)

trailing_limit_px?: string | null

Current trailing limit price computed by the trailing strategy

trailing_offset?: string | null

Trailing offset amount for trailing orders

trailing_offset_type?: TrailingOffsetType | null

Trailing offset type for trailing orders

One of the following:
"PRICE"
"BPS"
trailing_stop_px?: string | null

Current trailing stop price computed by the trailing strategy

trailing_watermark_px?: string | null

Trailing watermark price for trailing orders

trailing_watermark_ts?: string | null

Trailing watermark timestamp for trailing orders

formatdate-time
underlying_instrument_id?: string | null

OEMS instrument ID of the option’s underlying instrument. Populated only for OPTIONS orders; null for non-options and for options whose underlier cannot be resolved from the instrument cache.

formatuuid
PositionClosePositionResponse extends BaseResponse { metadata, error } { data }
data: OrderList { id, account_id, client_order_id, 29 more }
id: string

Engine-assigned unique identifier for this order (UUID).

account_id: number

Account placing the order

formatint64
client_order_id: string

Client-provided identifier echoed back (FIX tag 11).

created_at: string

Timestamp when order was created (UTC)

formatdate-time
filled_quantity: string

Cumulative filled quantity

instrument_id: string

OEMS instrument UUID for the traded instrument.

formatuuid
instrument_type: SecurityType

Type of security

One of the following:
"COMMON_STOCK"
"PREFERRED_STOCK"
"OPTION"
"CASH"
"OTHER"
leaves_quantity: string

Remaining unfilled quantity

order_type: OrderType

Type of order (MARKET, LIMIT, etc.)

One of the following:
"MARKET"
"LIMIT"
"STOP"
"STOP_LIMIT"
"TRAILING_STOP"
"TRAILING_STOP_LIMIT"
"OTHER"
quantity: string

Total order quantity

side: Side

Side of the order (BUY, SELL, SELL_SHORT)

One of the following:
"BUY"
"SELL"
"SELL_SHORT"
"OTHER"
status: OrderStatus

Current status of the order

One of the following:
"PENDING_NEW"
"NEW"
"PARTIALLY_FILLED"
"FILLED"
"CANCELED"
"REJECTED"
"EXPIRED"
"PENDING_CANCEL"
"PENDING_REPLACE"
"REPLACED"
"DONE_FOR_DAY"
"STOPPED"
"SUSPENDED"
"CALCULATED"
"OTHER"
symbol: string

Trading symbol

time_in_force: TimeInForce

Time in force instruction

One of the following:
"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)

formatdate-time
venue: string

MIC code of the venue where the order is routed

average_fill_price?: string | null

Average fill price across all executions

details?: Array<string>

Contains execution, rejection or cancellation details, if any

expires_at?: string | null

Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE.

formatdate-time
extended_hours?: boolean | null

Whether the order is eligible for extended-hours trading.

limit_offset?: string | null

Limit offset for trailing stop-limit orders (signed)

limit_price?: string | null

Limit price (for LIMIT and STOP_LIMIT orders)

queue_state?: QueueState | null

Parent order queue state, present when the order is awaiting release or released.

One of the following:
"AWAITING_RELEASE"
"RELEASED"
releases_at?: string | null

Scheduled release time for orders awaiting release.

formatdate-time
stop_price?: string | null

Stop price (for STOP and STOP_LIMIT orders)

trailing_limit_px?: string | null

Current trailing limit price computed by the trailing strategy

trailing_offset?: string | null

Trailing offset amount for trailing orders

trailing_offset_type?: TrailingOffsetType | null

Trailing offset type for trailing orders

One of the following:
"PRICE"
"BPS"
trailing_stop_px?: string | null

Current trailing stop price computed by the trailing strategy

trailing_watermark_px?: string | null

Trailing watermark price for trailing orders

trailing_watermark_ts?: string | null

Trailing watermark timestamp for trailing orders

formatdate-time
underlying_instrument_id?: string | null

OEMS instrument ID of the option’s underlying instrument. Populated only for OPTIONS orders; null for non-options and for options whose underlier cannot be resolved from the instrument cache.

formatuuid
PositionGetPositionInstructionsResponse extends BaseResponse { metadata, error } { data }
data: PositionInstructionList { id, account_id, instruction_id, 9 more }
id: string

Server-assigned id. Used as the path parameter on cancel.

formatuuid
account_id: number

Account the instruction belongs to.

formatint64
instruction_id: string

Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied.

instruction_type: PositionInstructionType

The action this instruction requests.

One of the following:
"EXERCISE"
"DO_NOT_EXERCISE"
"CONTRARY_EXERCISE"
instrument_id: string

Identifier of the options contract this instruction acts on.

formatuuid
quantity: string

Number of contracts included in the instruction.

Current lifecycle status.

One of the following:
"SENT"
"ACCEPTED"
"REJECTED"
"ENGINE_REJECTED"
"CANCEL_REQUESTED"
"CANCELLED"
"CANCEL_FAILED"
"UNKNOWN"
symbol: string

Options symbol (OSI) for display.

accepted_quantity?: string | null

Number of contracts accepted by the clearing venue. Populated once the instruction reaches ACCEPTED.

created_at?: string | null

When the instruction was first accepted by the service.

formatdate-time
rejection_reason?: string | null

Human-readable explanation populated on any non-success terminal status — REJECTED, ENGINE_REJECTED, or CANCEL_FAILED. On a 207 Multi-Status batch submit the top-level error field summarizes the batch; per-row detail continues to live here.

updated_at?: string | null

When the instruction’s lifecycle state last changed.

formatdate-time
PositionSubmitPositionInstructionsResponse extends BaseResponse { metadata, error } { data }
data: PositionInstructionList { id, account_id, instruction_id, 9 more }
id: string

Server-assigned id. Used as the path parameter on cancel.

formatuuid
account_id: number

Account the instruction belongs to.

formatint64
instruction_id: string

Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied.

instruction_type: PositionInstructionType

The action this instruction requests.

One of the following:
"EXERCISE"
"DO_NOT_EXERCISE"
"CONTRARY_EXERCISE"
instrument_id: string

Identifier of the options contract this instruction acts on.

formatuuid
quantity: string

Number of contracts included in the instruction.

Current lifecycle status.

One of the following:
"SENT"
"ACCEPTED"
"REJECTED"
"ENGINE_REJECTED"
"CANCEL_REQUESTED"
"CANCELLED"
"CANCEL_FAILED"
"UNKNOWN"
symbol: string

Options symbol (OSI) for display.

accepted_quantity?: string | null

Number of contracts accepted by the clearing venue. Populated once the instruction reaches ACCEPTED.

created_at?: string | null

When the instruction was first accepted by the service.

formatdate-time
rejection_reason?: string | null

Human-readable explanation populated on any non-success terminal status — REJECTED, ENGINE_REJECTED, or CANCEL_FAILED. On a 207 Multi-Status batch submit the top-level error field summarizes the batch; per-row detail continues to live here.

updated_at?: string | null

When the instruction’s lifecycle state last changed.

formatdate-time
PositionCancelPositionInstructionResponse extends BaseResponse { metadata, error } { data }
data: PositionInstruction { 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.

formatuuid
account_id: number

Account the instruction belongs to.

formatint64
instruction_id: string

Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied.

instruction_type: PositionInstructionType

The action this instruction requests.

One of the following:
"EXERCISE"
"DO_NOT_EXERCISE"
"CONTRARY_EXERCISE"
instrument_id: string

Identifier of the options contract this instruction acts on.

formatuuid
quantity: string

Number of contracts included in the instruction.

Current lifecycle status.

One of the following:
"SENT"
"ACCEPTED"
"REJECTED"
"ENGINE_REJECTED"
"CANCEL_REQUESTED"
"CANCELLED"
"CANCEL_FAILED"
"UNKNOWN"
symbol: string

Options symbol (OSI) for display.

accepted_quantity?: string | null

Number of contracts accepted by the clearing venue. Populated once the instruction reaches ACCEPTED.

created_at?: string | null

When the instruction was first accepted by the service.

formatdate-time
rejection_reason?: string | null

Human-readable explanation populated on any non-success terminal status — REJECTED, ENGINE_REJECTED, or CANCEL_FAILED. On a 207 Multi-Status batch submit the top-level error field summarizes the batch; per-row detail continues to live here.

updated_at?: string | null

When the instruction’s lifecycle state last changed.

formatdate-time