paper_ex_polymarket

# Changelog

## 0.3.2 - 2026-07-25

### Fixed

- **Live CLOB book timestamps in milliseconds.** `OrderBook.from_clob_book/2`
  treated a string `"timestamp"` as Unix **seconds**, but the live
  `/book` endpoint sends **milliseconds** as a string (e.g.
  `"1781577793787"`) — `DateTime.from_unix!/1` then raised
  `invalid Unix time` and crashed the consuming snapshotter (and, in
  the reference bot, the whole app on boot). The string path now
  applies the same ms-vs-seconds heuristic as the integer path, and a
  malformed timestamp falls back to `DateTime.utc_now/0` instead of
  raising. Surfaced by a real paper-trading run; 2 regression tests.

## 0.3.1 (unreleased)

### Added

- Integration test for `PaperEx.Engine.advance_pending/3` flowing
  through `PaperExPolymarket.Adapter`: a limit pending created by
  the adapter is resolved by a fresh snapshot end-to-end, and a
  non-crossing fresh snapshot leaves the pending in place with no
  ledger churn.
- No adapter code change — `advance_pending/3` is generic in the
  engine and consumes the adapter's existing `simulate_fill/3`.

## 0.3.0 (unreleased)

### Added

- `PaperExPolymarket.Snapshot` — convenience module closing the
  loop from a Polymarket CLOB `/book` response to a
  `PaperEx.MarketSnapshot`:
  - `from_clob_book/3` — normalize an already-fetched body for a
    token id, `{:token_id, …}` tuple, or pre-resolved
    `PaperEx.Instrument`.
  - `fetch_order_book_snapshot/3` — same, with an **injected**
    fetcher (1-arity function or `{module, function, args}` tuple).
    The package never owns network IO; fetchers are caller-supplied.
- 18 new tests covering: fixture-backed conversion, token-id /
  tuple / instrument refs, malformed inputs returning bounded
  reason codes (`:polymarket_invalid_market_payload`,
  `:polymarket_invalid_book`), function and MFA fetcher success
  paths, error pass-through, instrument_opts forwarding.

### Notes

- This module exists in `paper_ex_polymarket` rather than
  `polymarket` to preserve the dependency direction: `polymarket`
  stays upstream of paper packages. Any helper returning
  `PaperEx.MarketSnapshot` belongs here or in `polymarket_bot`.

## 0.2.0 (unreleased)

### Added

- Hand-authored CLOB/Data-API fixture set under
  `test/fixtures/` (`clob_market.json`, `clob_book.json`,
  `data_api_trade.json`) modeling realistic Polymarket payload
  shapes from the v1 bot's observed responses. See
  `test/fixtures/README.md` for the shape rationale.
- `PaperExPolymarket.Fixtures` — test-support helper for loading
  the fixture set (not compiled into the library).
- 28 new fixture-backed integration tests exercising
  `Market.from_clob_market/2`, `OrderBook.from_clob_book/2`,
  `Adapter.normalize_instrument/1`,
  `Adapter.normalize_snapshot/2`,
  `Adapter.normalize_fill/2`, and `Execution.simulate_fill/3`
  against the realistic payload shapes. Covers happy paths,
  malformed payloads (non-map instrument, missing book keys,
  partial-parse prices, partial-parse timestamps, zero-size
  levels) and the bounded-reason-code contract.
- 6 new pending-integration tests verifying that the
  `:pending_remainder` policy added to `PaperEx.Engine` flows
  cleanly through the Polymarket adapter, that market FAK partials
  never record `:pending`, and that
  `Engine.cancel_pending/3` and
  `LiveMirror.record_pending/3` coexist without colliding.

### Notes

- No code change to `PaperExPolymarket.Adapter` was required: the
  pending-remainder policy is implemented generically in
  `PaperEx.Engine` and the adapter's `simulate_fill/3` already
  returns the `{:ok, :partial, fills}` shape the engine consumes.

## 0.1.0 (unreleased)

Initial scaffold of the Polymarket adapter for `paper_ex`.

### Added

- `PaperExPolymarket` top-level module with `version/0` and moduledoc
  explaining the adapter package role and non-goals.
- `PaperExPolymarket.Market` — token id ↔ `PaperEx.Instrument`
  conversion, including outcome label/index lookup against CLOB
  `"tokens"` lists and tick-size parsing.
- `PaperExPolymarket.OrderBook` — CLOB `/book` body ↔
  `PaperEx.MarketSnapshot`. Parses string-encoded prices/sizes,
  filters zero-size levels, surfaces malformed payloads as
  `:invalid_book`.
- `PaperExPolymarket.ActivityMapper` — Data-API and RTDS trade event ↔
  `PaperEx.Fill`. Enforces instrument id match, parses second-/ms-
  precision timestamps, surfaces maker/taker liquidity hints.
- `PaperExPolymarket.Execution` — Polymarket-flavored fill simulator
  (`:market` orders modeled as FAK, `:limit` modeled as GTC).
  Walks the book, produces `:filled` / `:partial` /
  `:missed` outcomes with bounded reason codes
  (`:no_liquidity`, `:limit_not_crossed`).
- `PaperExPolymarket.Fees` — bps-based fee helper for take-fee
  modeling via `adapter_opts: [fee_bps: <bps>]`. Defaults to zero.
- `PaperExPolymarket.Adapter` — implements every `PaperEx.Adapter`
  callback. Returns bounded Polymarket-tagged reason atoms
  (`:polymarket_invalid_market_payload`, `:polymarket_invalid_book`,
  `:polymarket_invalid_trade_payload`,
  `:polymarket_instrument_mismatch`) on top of the generic engine
  codes from `PaperEx.ReasonCodes.engine_codes/0`.
- `PaperExPolymarket.LiveMirror` — live-mirror lifecycle helpers:
  - `simulate_intent/4` — engine apply with `:mode = :live_mirror`.
  - `mirror_actual_fill/4` — record an observed exchange trade as a
    `:filled` execution.
  - `record_pending/3` — record a resting `:pending` execution.
  - `resolve_pending/4` — move a pending into `:filled` or
    `:cancelled`, preserving both ledger entries.
- 71 tests covering: CLOB market normalization, CLOB book parsing
  (happy + malformed + zero-size), activity-event mapping (BUY /
  SELL / liquidity / ms timestamps / instrument mismatch / zero
  size / non-numeric), fill simulation across `:market` / `:limit`
  / `:buy` / `:sell` / partial / missed / limit-not-crossed paths,
  adapter behaviour conformance, end-to-end
  `PaperEx.Engine.apply_order/4` through the adapter, fee
  application via `adapter_opts`, full live-mirror pending →
  filled / cancelled lifecycle, and live-mirror ledger preservation
  for misses and skips that never produced a position.

### Deferred

- Auto-fetching CLOB market metadata via `polymarket_clob`. Callers
  pass metadata in.
- Polymarket FAK partial-remainder lifecycle (`:pending` execution
  for the unfilled remainder of a market order).
- A built-in price-history loader.