Behaviour for paper-trading strategies: pure decision functions over market + portfolio state.

A strategy receives a context per instrument per tick and returns the orders it wants placed. It expresses intent only — the host application's runner owns execution policy (guardrail caps, kill switches, pacing, notification). Strategies must not perform side effects in decide/2: no network calls, no process state, no clock reads. Everything a decision needs is in the context; everything it learns lives in the returned state.

This behaviour was promoted from the polymarket_bot reference app once multiple strategy families (resting-bid, copy-trade, scanner) proved the abstraction — per the workspace watch-list rule of not extracting frameworks early.

Callbacks

• init/1 — turn keyword opts into strategy state once at runner startup. Validate hard here; a misconfigured strategy should refuse to start, not trade garbage.

• decide/2 — given a context and state, return a decision. Two forms, distinguished by tuple arity:

  • {orders, new_state} — place orders (the common case). Return {[], state} to do nothing.
  • {orders, cancels, new_state} — first cancel the resting pending remainders named in cancels, then place orders. A cancel reference is the :order_id of a resting pending — read it from PaperEx.Engine.open_pending_remainders/1 (each returned Execution carries the :order_id to cancel by). This is what lets a strategy move a resting quote — cancel the stale one, place a fresh one — rather than only ever adding orders. A market maker re-quoting around a moving midpoint is the motivating case.

  Orders are PaperEx.Order structs; set your own ids, sizes and prices — runners may prefix or suffix ids for uniqueness but stamp no other defaults, so a cancelling strategy must cancel by the :order_id it reads back from open_pending_remainders/1, not one it reconstructs. A runner that does not support the 3-tuple form may treat it as {orders, new_state} and ignore the cancels, so strategies that need cancels must be paired with a runner that honors them — and should declare cancels?/0 so hosts can gate incompatible execution paths (e.g. live mirroring).

• cancels?/0 (optional) — return true to declare that this strategy uses the 3-tuple cancel form. Hosts use it to refuse unsafe pairings up front (a runner that mirrors orders to a live venue but cannot yet cancel them there must not run a re-quoting strategy). Defaults to false when not exported.

Context shape

%{
  instrument_id: term(),
  snapshot: PaperEx.MarketSnapshot.t(),
  portfolio: PaperEx.Portfolio.t()
}

Runners may include additional keys (the Polymarket reference app, for example, also passes :token_id — the same value as :instrument_id — and copy-trade runners pass observed activity). Strategies should pattern-match only on the keys they need and tolerate extras.

The portfolio is the current state including open positions and pending remainders — use PaperEx.Engine.open_pending_remainders/1 to avoid stacking duplicate resting orders.