PaperEx.Position (PaperEx v0.8.0)

Copy Markdown View Source

An open or closed paper position.

A Position is created when a PaperEx.Order produces a :filled PaperEx.Execution. It carries the entry data plus, when closed, the exit data and realized P&L. The struct is plain data; the engine that opens, closes, and resolves positions lives in PaperEx.Engine.

Lifecycle

  • :open — the position holds shares; :exit_price, :pnl, and :closed_at are all nil.
  • :closed — the position has been fully exited; :exit_price, :pnl, and :closed_at are populated.

Partial closes are modeled with a parent/child split. When PaperEx.Engine partially sells (or short-covers) an open position, it books a :closed child Position for the closed shares — carrying that slice's realized :pnl, :exit_price, and :closed_at — onto the portfolio's :history, while the parent stays :open with reduced :shares at its original :entry_price basis. A full close simply transitions the position itself to :closed.

Fields

  • :id — caller-assignable identifier.
  • :order_id — the PaperEx.Order that opened this position.
  • :execution_id — the :filled PaperEx.Execution record that created this position.
  • :market_id (required) — opaque exchange-specific market id.
  • :side (required) — :buy or :sell.
  • :entry_price (required) — execution price per share.
  • :shares (required) — number of units held.
  • :strategy — optional binary tag, copied from the Order.
  • :metadata — free-form map, copied from the Order and possibly augmented by the engine.
  • :status (required) — :open or :closed.
  • :exit_price — populated on close.
  • :pnl — realized profit or loss on close. Sign convention is P&L-positive-is-profit; the engine computes it in PaperEx.Engine.
  • :opened_at — DateTime.t() (defaults to DateTime.utc_now/0).
  • :closed_at — DateTime.t(), populated on close.

Summary

Types

id()
market_id()
side()
status()
t()

Functions

new(attrs)

Builds a Position from a map or keyword list.

statuses()

Returns the list of valid :status atoms.

Types

id()

@type id() :: term() | nil

market_id()

@type market_id() :: term()

side()

@type side() :: :buy | :sell

status()

@type status() :: :open | :closed

t()

@type t() :: %PaperEx.Position{
  closed_at: DateTime.t() | nil,
  entry_price: number(),
  execution_id: term() | nil,
  exit_price: number() | nil,
  id: id(),
  market_id: market_id(),
  metadata: map(),
  opened_at: DateTime.t(),
  order_id: term() | nil,
  pnl: number() | nil,
  shares: number(),
  side: side(),
  status: status(),
  strategy: String.t() | nil
}

Functions

new(attrs)

@spec new(keyword() | map()) :: t()

Builds a Position from a map or keyword list.

Required: :market_id, :side, :entry_price, :shares. :status defaults to :open. When :status is :closed, :exit_price, :pnl, and :closed_at must all be set.

statuses()

@spec statuses() :: [status()]

Returns the list of valid :status atoms.