mostlyright.markets.polymarket_trades

Polymarket trade-history public surface — Phase 9 (TRADES-04..05).

Two read-only entry points over the public Polymarket Gamma API:

history() — price + volume timeseries for a single market.
snapshot() — current state for an event (one row per outcome).

Both return pandas.DataFrame with source="polymarket.gamma" per row so downstream pd.concat / merge keep source-identity intact.

The trades surface intentionally lives at the flat module name mostlyright.markets.polymarket_trades (rather than under a hypothetical mostlyright.markets.polymarket.trades subpackage) because converting the existing polymarket.py module into a package would break the dozen-plus call sites (including test_polymarket_real.py and test_cross_issuer_station_identity.py) that import private names like _derive_city. Flat module + namespaced sibling is the minimum-invasive shape for Phase 9; Phase 10 can revisit if the namespace becomes load-bearing.

Functions

`history`(token_id, *, from_, to[, …])	Market price/volume timeseries from Polymarket CLOB `/prices-history`.
`snapshot`(event_id, *[, client, sleep_between])	Current state for `event_id` from Gamma `/events/{id}`.

mostlyright.markets.polymarket_trades.history(token_id, , from_, to, fidelity_minutes=60, client=None, sleep_between=None)

Market price/volume timeseries from Polymarket CLOB /prices-history.

Architect iter-1 CRITICAL fix: /prices-history lives on the CLOB host (clob.polymarket.com), NOT Gamma. The market query parameter is the CLOB token id (ERC-1155 asset id, one per YES/NO outcome), retrievable from Gamma’s /markets/slug/{slug} response as clobTokenIds. It is NOT a Gamma market/condition/event id.

Polymarket reports time-bucketed last-price + volume; there is no separate H/L/C per bucket (the order book is too thin in many markets for OHLC to be meaningful at sub-day granularity).

Parameters:
- token_id (str) – Polymarket CLOB token id (asset id for a single outcome — YES or NO; pick the side you want). NOT a Gamma market/condition/event id.
- from – tz-aware UTC datetimes bounding the window.
- to (datetime) – tz-aware UTC datetimes bounding the window.
- fidelity_minutes (int) – Bucket size in minutes (default 60 = hourly). Polymarket documents minimum 1.
- client (Client | None) – Optional shared httpx.Client.
- sleep_between (float | None) – Per-request polite-sleep override.
- from_ (datetime)
Returns:
- ts (datetime UTC | None): bucket end timestamp.
- price (float | None): last-traded price in [0, 1] for the requested outcome token.
- volume (float | None): volume in the bucket.
- source (str): always "polymarket.clob".
df.attrs["token_id"] echoes the input for downstream attribution.
Return type: DataFrame with columns
Raises:
- TypeError – from_/to not tz-aware datetimes.
- ValueError – from_ >= to or fidelity_minutes < 1.
- ValueError – token_id not a non-empty str.

mostlyright.markets.polymarket_trades.snapshot(event_id, , client=None, sleep_between=None)

Current state for event_id from Gamma /events/{id}.

Parameters:
- event_id (str) – Polymarket event id.
- client (Client | None) – Optional shared httpx.Client.
- sleep_between (float | None) – Per-request polite-sleep override. Default applies get_json’s 0.2s floor (the Gamma rate-limit-floor documented in .planning/research/MARKETS-RATE-LIMITS.md). Iter-4 codex HIGH: the previous implementation routed through fetch_event_by_id which has no sleep path — snapshot in a loop bypassed the polite floor entirely. Now routes through get_json so the default sleep applies.
Returns:
- market_id (str | None)
- outcome (str): e.g. "Yes" / "No" / candidate name.
- last_price (float | None): in [0, 1].
- volume (float | None): per-market lifetime volume.
- liquidity (float | None): order-book liquidity proxy.
- source (str): always "polymarket.gamma".
snapshot_at lives in df.attrs.
Return type: DataFrame, one row per outcome (across all markets in the event)
Raises: ValueError – event_id not a non-empty str OR upstream payload is not a dict.