Skip to content
Clear Street Clear Street
Start Trading
API Reference
V1

Positions

View positions and manage position instructions.

Get Positions
PositionGetPositionsResponse v1().positions().getPositions(PositionGetPositionsParamsparams = PositionGetPositionsParams.none(), RequestOptionsrequestOptions = RequestOptions.none())
GET/v1/accounts/{account_id}/positions
Close Positions
PositionClosePositionsResponse v1().positions().closePositions(PositionClosePositionsParamsparams = PositionClosePositionsParams.none(), RequestOptionsrequestOptions = RequestOptions.none())
DELETE/v1/accounts/{account_id}/positions
Close Position
PositionClosePositionResponse v1().positions().closePosition(PositionClosePositionParamsparams, RequestOptionsrequestOptions = RequestOptions.none())
DELETE/v1/accounts/{account_id}/positions/{instrument_id}
Get Position Instructions
PositionGetPositionInstructionsResponse v1().positions().getPositionInstructions(PositionGetPositionInstructionsParamsparams = PositionGetPositionInstructionsParams.none(), RequestOptionsrequestOptions = RequestOptions.none())
GET/v1/accounts/{account_id}/positions/instructions
Submit Position Instructions
PositionSubmitPositionInstructionsResponse v1().positions().submitPositionInstructions(PositionSubmitPositionInstructionsParamsparams, RequestOptionsrequestOptions = RequestOptions.none())
POST/v1/accounts/{account_id}/positions/instructions
Cancel Position Instruction
PositionCancelPositionInstructionResponse v1().positions().cancelPositionInstruction(PositionCancelPositionInstructionParamsparams, RequestOptionsrequestOptions = RequestOptions.none())
DELETE/v1/accounts/{account_id}/positions/instructions/{instruction_id}
ModelsExpand Collapse
class Position:

Represents a holding of a particular instrument in an account

long accountId

The account this position belongs to

formatint64
String availableQuantity

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

String instrumentId

Unique instrument identifier

formatuuid
SecurityType instrumentType

Type of security

One of the following:
COMMON_STOCK("COMMON_STOCK")
OPTION("OPTION")
CASH("CASH")
String marketValue

The current market value of the position

PositionType positionType

The type of position

One of the following:
LONG("LONG")
SHORT("SHORT")
LONG_CALL("LONG_CALL")
SHORT_CALL("SHORT_CALL")
LONG_PUT("LONG_PUT")
SHORT_PUT("SHORT_PUT")
String quantity

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

String symbol

The trading symbol for the instrument

Optional<String> avgPrice

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.

Optional<String> closingPrice

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.

Optional<LocalDate> closingPriceDate

The market date associated with closing_price When a null/undefined value is observed, it indicates that there is no available data.

formatdate
Optional<String> costBasis

The total cost basis for this position When a null/undefined value is observed, it indicates that there is no available data.

Optional<String> dailyRealizedPnl

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.

Optional<String> dailyUnrealizedPnl

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.

Optional<String> dailyUnrealizedPnlPct

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.

Optional<String> instrumentPrice

The current market price of the instrument When a null/undefined value is observed, it indicates that there is no available data.

Optional<String> underlyingInstrumentId

Identifier of the underlying instrument, when available When a null/undefined value is observed, it indicates it does not apply.

formatuuid
Optional<String> unrealizedPnl

The total unrealized profit or loss for this position based on current market value When a null/undefined value is observed, it indicates that there is no available data.

Optional<String> unrealizedPnlPct

The unrealized profit/loss for the position, expressed as a percentage of the position’s cost basis (range: 0-100). When a null/undefined value is observed, it indicates that there is no available data.

class PositionInstruction:

A position instruction and its current lifecycle state.

String id

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

formatuuid
long accountId

Account the instruction belongs to.

formatint64
String instructionId

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

PositionInstructionType instructionType

The action this instruction requests.

One of the following:
EXERCISE("EXERCISE")
DO_NOT_EXERCISE("DO_NOT_EXERCISE")
CONTRARY_EXERCISE("CONTRARY_EXERCISE")
String instrumentId

Identifier of the options contract this instruction acts on.

formatuuid
String quantity

Number of contracts included in the instruction.

Current lifecycle status.

One of the following:
SENT("SENT")
ACCEPTED("ACCEPTED")
REJECTED("REJECTED")
CANCEL_REQUESTED("CANCEL_REQUESTED")
CANCELLED("CANCELLED")
CANCEL_FAILED("CANCEL_FAILED")
UNKNOWN("UNKNOWN")
String symbol

Options symbol (OSI) for display.

Optional<String> acceptedQuantity

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.

Optional<LocalDateTime> createdAt

When the instruction was first accepted by the service. When a null/undefined value is observed, it indicates that there is no available data.

formatdate-time
Optional<String> rejectionReason

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.

Optional<LocalDateTime> updatedAt

When the instruction’s lifecycle state last changed. When a null/undefined value is observed, it indicates that there is no available data.

formatdate-time
enum PositionInstructionStatus:

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_reason carries the detail. Covers both venue-reported rejections and rejections raised before the instruction reached the clearing venue (e.g. duplicate instruction_id, DO_NOT_EXERCISE / CONTRARY_EXERCISE submitted 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_reason carries the detail.
  • UNKNOWN: status could not be determined.
SENT("SENT")
ACCEPTED("ACCEPTED")
REJECTED("REJECTED")
CANCEL_REQUESTED("CANCEL_REQUESTED")
CANCELLED("CANCELLED")
CANCEL_FAILED("CANCEL_FAILED")
UNKNOWN("UNKNOWN")
enum PositionInstructionType:

The action to take against an options position.

EXERCISE("EXERCISE")
DO_NOT_EXERCISE("DO_NOT_EXERCISE")
CONTRARY_EXERCISE("CONTRARY_EXERCISE")
enum PositionType:

Position type classification

LONG("LONG")
SHORT("SHORT")
LONG_CALL("LONG_CALL")
SHORT_CALL("SHORT_CALL")
LONG_PUT("LONG_PUT")
SHORT_PUT("SHORT_PUT")