Positions

View positions and manage position instructions.

Get Positions

client.V1.Positions.GetPositions(ctx, accountID, query) (*V1PositionGetPositionsResponse, error)

GET/v1/accounts/{account_id}/positions

Close Positions

client.V1.Positions.ClosePositions(ctx, accountID, body) (*V1PositionClosePositionsResponse, error)

DELETE/v1/accounts/{account_id}/positions

Close Position

client.V1.Positions.ClosePosition(ctx, instrumentID, params) (*V1PositionClosePositionResponse, error)

DELETE/v1/accounts/{account_id}/positions/{instrument_id}

Get Position Instructions

client.V1.Positions.GetPositionInstructions(ctx, accountID, query) (*V1PositionGetPositionInstructionsResponse, error)

GET/v1/accounts/{account_id}/positions/instructions

Submit Position Instructions

client.V1.Positions.SubmitPositionInstructions(ctx, accountID, body) (*V1PositionSubmitPositionInstructionsResponse, error)

POST/v1/accounts/{account_id}/positions/instructions

Cancel Position Instruction

client.V1.Positions.CancelPositionInstruction(ctx, instructionID, body) (*V1PositionCancelPositionInstructionResponse, error)

DELETE/v1/accounts/{account_id}/positions/instructions/{instruction_id}

ModelsExpand Collapse

type Position struct{…}

Represents a holding of a particular instrument in an account

AccountID int64

The account this position belongs to

formatint64

AvailableQuantity string

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

InstrumentID string

Unique instrument identifier

formatuuid

InstrumentType SecurityType

Type of security

One of the following:

const SecurityTypeCommonStock SecurityType = "COMMON_STOCK"

const SecurityTypeIndex SecurityType = "INDEX"

const SecurityTypeOption SecurityType = "OPTION"

const SecurityTypeCash SecurityType = "CASH"

MarketValue string

The current market value of the position

PositionType PositionType

The type of position

One of the following:

const PositionTypeLong PositionType = "LONG"

const PositionTypeShort PositionType = "SHORT"

Quantity string

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

Symbol string

The trading symbol for the instrument

AvgPrice stringOptional

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.

ClosingPrice stringOptional

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.

ClosingPriceDate TimeOptional

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

formatdate

CostBasis stringOptional

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

DailyRealizedPnl stringOptional

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.

DailyUnrealizedPnl stringOptional

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.

DailyUnrealizedPnlPct stringOptional

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.

InstrumentPrice stringOptional

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

UnderlyingInstrumentID stringOptional

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

formatuuid

UnderlyingInstrumentType SecurityTypeOptional

Type of the underlying instrument, alongside underlying_instrument_id When a null/undefined value is observed, it indicates it does not apply.

One of the following:

const SecurityTypeCommonStock SecurityType = "COMMON_STOCK"

const SecurityTypeIndex SecurityType = "INDEX"

const SecurityTypeOption SecurityType = "OPTION"

const SecurityTypeCash SecurityType = "CASH"

UnrealizedPnl stringOptional

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.

UnrealizedPnlPct stringOptional

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.

type PositionInstruction struct{…}

A position instruction and its current lifecycle state.

ID string

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

formatuuid

AccountID int64

Account the instruction belongs to.

formatint64

ClientInstructionID 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.

One of the following:

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.

formatuuid

Quantity string

Number of contracts included in the instruction.

Status PositionInstructionStatus

Current lifecycle status.

One of the following:

const PositionInstructionStatusSent PositionInstructionStatus = "SENT"

const PositionInstructionStatusAccepted PositionInstructionStatus = "ACCEPTED"

const PositionInstructionStatusRejected PositionInstructionStatus = "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 stringOptional

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.

CreatedAt TimeOptional

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

Rejection PositionInstructionRejectionOptional

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 string

Human-readable explanation of the rejection. Duplicates the top-level rejection_reason; prefer this field.

Domain string

Namespacing domain of the reason code — com.clearstreet.oems.exercise for reasons OEMS validates, com.clearstreet.oems.clearing for clearing-owned reasons.

Metadata map[string, string]

Reason-specific parameters as a string→string map. Which keys are present depends on reason:

INSUFFICIENT_POSITION → available, requested
DNE_NOT_ON_EXPIRY / CEA_NOT_ON_EXPIRY → expiry, business_date
EXERCISE_PAST_CUTOFF → cutoff_time
DUPLICATE_INSTRUCTION → existing_id

Empty for reasons that carry no parameters. New keys may be added over time, so treat unknown keys leniently.

Reason string

Stable, machine-readable reason code, e.g. DNE_NOT_ON_EXPIRY, INSUFFICIENT_POSITION, OPTIONS_LEVEL_EXCEEDED, EXERCISE_PAST_CUTOFF.

RejectionReason stringOptional

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.

UnderlyingInstrumentID stringOptional

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

formatuuid

UpdatedAt TimeOptional

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

type PositionInstructionList []PositionInstruction

ID string

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

formatuuid

AccountID int64

Account the instruction belongs to.

formatint64

ClientInstructionID 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.

One of the following:

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.

formatuuid

Quantity string

Number of contracts included in the instruction.

Status PositionInstructionStatus

Current lifecycle status.

One of the following:

const PositionInstructionStatusSent PositionInstructionStatus = "SENT"

const PositionInstructionStatusAccepted PositionInstructionStatus = "ACCEPTED"

const PositionInstructionStatusRejected PositionInstructionStatus = "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 stringOptional

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.

CreatedAt TimeOptional

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

Rejection PositionInstructionRejectionOptional

Description string

Human-readable explanation of the rejection. Duplicates the top-level rejection_reason; prefer this field.

Domain string

Namespacing domain of the reason code — com.clearstreet.oems.exercise for reasons OEMS validates, com.clearstreet.oems.clearing for clearing-owned reasons.

Metadata map[string, string]

Reason-specific parameters as a string→string map. Which keys are present depends on reason:

INSUFFICIENT_POSITION → available, requested
DNE_NOT_ON_EXPIRY / CEA_NOT_ON_EXPIRY → expiry, business_date
EXERCISE_PAST_CUTOFF → cutoff_time
DUPLICATE_INSTRUCTION → existing_id

Empty for reasons that carry no parameters. New keys may be added over time, so treat unknown keys leniently.

Reason string

Stable, machine-readable reason code, e.g. DNE_NOT_ON_EXPIRY, INSUFFICIENT_POSITION, OPTIONS_LEVEL_EXCEEDED, EXERCISE_PAST_CUTOFF.

RejectionReason stringOptional

UnderlyingInstrumentID stringOptional

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

formatuuid

UpdatedAt TimeOptional

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

type PositionInstructionRejection struct{…}

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 string

Human-readable explanation of the rejection. Duplicates the top-level rejection_reason; prefer this field.

Domain string

Namespacing domain of the reason code — com.clearstreet.oems.exercise for reasons OEMS validates, com.clearstreet.oems.clearing for clearing-owned reasons.

Metadata map[string, string]

Reason-specific parameters as a string→string map. Which keys are present depends on reason:

INSUFFICIENT_POSITION → available, requested
DNE_NOT_ON_EXPIRY / CEA_NOT_ON_EXPIRY → expiry, business_date
EXERCISE_PAST_CUTOFF → cutoff_time
DUPLICATE_INSTRUCTION → existing_id

Empty for reasons that carry no parameters. New keys may be added over time, so treat unknown keys leniently.

Reason string

Stable, machine-readable reason code, e.g. DNE_NOT_ON_EXPIRY, INSUFFICIENT_POSITION, OPTIONS_LEVEL_EXCEEDED, EXERCISE_PAST_CUTOFF.

type PositionInstructionStatus string

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 client_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.

One of the following:

const PositionInstructionStatusSent PositionInstructionStatus = "SENT"

const PositionInstructionStatusAccepted PositionInstructionStatus = "ACCEPTED"

const PositionInstructionStatusRejected PositionInstructionStatus = "REJECTED"

const PositionInstructionStatusCancelRequested PositionInstructionStatus = "CANCEL_REQUESTED"

const PositionInstructionStatusCancelled PositionInstructionStatus = "CANCELLED"

const PositionInstructionStatusCancelFailed PositionInstructionStatus = "CANCEL_FAILED"

const PositionInstructionStatusUnknown PositionInstructionStatus = "UNKNOWN"

type PositionInstructionType string

The action to take against an options position.

One of the following:

const PositionInstructionTypeExercise PositionInstructionType = "EXERCISE"

const PositionInstructionTypeDoNotExercise PositionInstructionType = "DO_NOT_EXERCISE"

const PositionInstructionTypeContraryExercise PositionInstructionType = "CONTRARY_EXERCISE"

type PositionList []Position

AccountID int64

The account this position belongs to

formatint64

AvailableQuantity string

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

InstrumentID string

Unique instrument identifier

formatuuid

InstrumentType SecurityType

Type of security

One of the following:

const SecurityTypeCommonStock SecurityType = "COMMON_STOCK"

const SecurityTypeIndex SecurityType = "INDEX"

const SecurityTypeOption SecurityType = "OPTION"

const SecurityTypeCash SecurityType = "CASH"

MarketValue string

The current market value of the position

PositionType PositionType

The type of position

One of the following:

const PositionTypeLong PositionType = "LONG"

const PositionTypeShort PositionType = "SHORT"

Quantity string

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

Symbol string

The trading symbol for the instrument

AvgPrice stringOptional

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.

ClosingPrice stringOptional

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.

ClosingPriceDate TimeOptional

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

formatdate

CostBasis stringOptional

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

DailyRealizedPnl stringOptional

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.

DailyUnrealizedPnl stringOptional

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.

DailyUnrealizedPnlPct stringOptional

InstrumentPrice stringOptional

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

UnderlyingInstrumentID stringOptional

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

formatuuid

UnderlyingInstrumentType SecurityTypeOptional

Type of the underlying instrument, alongside underlying_instrument_id When a null/undefined value is observed, it indicates it does not apply.

One of the following:

const SecurityTypeCommonStock SecurityType = "COMMON_STOCK"

const SecurityTypeIndex SecurityType = "INDEX"

const SecurityTypeOption SecurityType = "OPTION"

const SecurityTypeCash SecurityType = "CASH"

UnrealizedPnl stringOptional

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.

UnrealizedPnlPct stringOptional

type PositionType string

Position type classification

One of the following:

const PositionTypeLong PositionType = "LONG"

const PositionTypeShort PositionType = "SHORT"