PaperExPolymarket.ActivityMapper (PaperExPolymarket v0.3.2)

Copy Markdown View Source

Translation between Polymarket Data-API activity / trade events and PaperEx.Fill.

Used for live-mirror reconciliation: when a real Polymarket trade is observed (via the RTDS stream or the Data API /activity endpoint), the mirror layer turns it into a Fill so the paper engine can compare what did happen against what its simulation said would happen.

Input shapes

Two well-known shapes are supported:

  • Data API /activity events with "type" => "TRADE", fields "asset", "side", "size", "price", "timestamp", "transactionHash", optional "outcome", "outcomeIndex", "pseudonym", "proxyWallet".
  • RTDS trade payloads from the global feed, structurally identical to the above. Any map carrying an asset token id ("asset", or the fallbacks "asset_id" / "token_id") plus "side", "size", and "price" parses.

Side mapping

Polymarket strings "BUY" / "SELL" map to :buy / :sell. Any other side string yields {:error, :invalid_side}.

Errors

from_trade/2 is total — it returns {:error, atom()} (never raises) for any bad input:

  • :instrument_mismatch — the event's asset token id is missing, nil, non-binary, or does not equal the instrument id.
  • :invalid_side — "side" is not "BUY" / "SELL".
  • :zero_size — "size" is zero (PaperEx.Fill requires size > 0).
  • :invalid_number — "size" / "price" is non-numeric, a partial-parse string, or negative. Price zero is accepted (PaperEx.Fill allows price >= 0).
  • :invalid_timestamp — an integer "timestamp" outside the Unix second/millisecond ranges, or a non-integer/non-string timestamp (float, map, …). A garbage numeric-string timestamp instead falls back to the current time.

Summary

Functions

from_trade(payload, inst)

Maps a Polymarket trade payload onto a PaperEx.Fill for the given instrument.

Functions

from_trade(payload, inst)

@spec from_trade(map(), PaperEx.Instrument.t()) ::
  {:ok, PaperEx.Fill.t()} | {:error, atom()}

Maps a Polymarket trade payload onto a PaperEx.Fill for the given instrument.

The event's asset token id ("asset", falling back to "asset_id" / "token_id") MUST equal the instrument's :id; a missing, nil, non-binary, or differing asset yields {:error, :instrument_mismatch}. See the module Errors section for the full {:error, atom()} set.