A request to buy or sell on a market — input to the engine.

An Order is a request, not a result. PaperEx.Engine.apply_order/4 consumes an Order and produces a PaperEx.Execution and possibly a PaperEx.Position. This module is the request struct plus shape validation; the engine that acts on it lives in PaperEx.Engine.

Fields

• :id — caller-assignable identifier (any term). Useful for cross-referencing the order from an Execution or a Position. nil is allowed; the engine round-trips whatever you set (and uses it to tag pending remainders).
• :market_id (required) — exchange-specific market identifier. The package keeps this opaque (any term); the exchange adapter translates it.
• :side (required) — :buy or :sell.
• :order_type (required) — :limit or :market.
• :size — number of units (shares). For :limit orders this is the offered quantity; for :market orders the engine usually derives it from :amount after fill.
• :amount — currency spend budget for a market BUY only: the "spend at most $N" cap the engine converts to shares as it walks the book. A market SELL should use :size (the number of shares to sell) — its :amount is not a dollar budget and the engine ignores it. For :limit orders :amount is informational.
• :price — limit price per unit. Required for :limit; ignored for :market.
• :strategy — optional binary tag for grouping orders by strategy / signal source.
• :metadata — free-form map for caller-provided context. The engine never inspects this; it only round-trips it onto downstream Execution and Position records.
• :placed_at — DateTime.t() when the order was submitted to the engine. Defaults to DateTime.utc_now/0 if omitted.

Required-field semantics

new/1 requires :market_id, :side, and :order_type. For :limit orders it additionally requires :price and :size. For :market orders it additionally requires either :size or :amount. Validation is shape-only — economic policy (price-range checks, size limits, etc.) is the engine's job and lives in PaperEx.Engine.