polysimulator 0.4.1__tar.gz → 0.4.2__tar.gz

{polysimulator-0.4.1 → polysimulator-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: polysimulator
-Version: 0.4.1
+Version: 0.4.2
 Summary: Python SDK for the PolySimulator paper-trading API, with py-clob-client v1 drop-in parity (not py-clob-client-v2) and a polysim_polymarket paper-mode mirror of Polymarket's unified py-sdk (polymarket-client 0.1.0b8).
 Project-URL: Homepage, https://polysimulator.com
 Project-URL: Documentation, https://docs.polysimulator.com
@@ -21,6 +21,7 @@ Classifier: Topic :: Office/Business :: Financial
 Requires-Python: >=3.10
 Requires-Dist: httpx<1,>=0.27
 Requires-Dist: pydantic<3,>=2
+Requires-Dist: typing-extensions>=4
 Requires-Dist: websockets<17,>=12
 Provides-Extra: dev
 Requires-Dist: build>=1.0; extra == 'dev'
@@ -334,7 +335,7 @@ The port is the same mechanical swap as v1 — change the import **prefix**, the
 - from polymarket import SecureClient
 + from polysim_polymarket import SecureClient
 
-- client = SecureClient(private_key="0x…")       # real Polymarket wallet + EIP-712 signing
+- client = SecureClient.create(private_key="0x…")  # real Polymarket wallet + EIP-712 signing
 + client = SecureClient(host="https://api.polysimulator.com", api_key="ps_live_…")
 
   # unchanged from here on — same method names, same keyword-only call shapes,
@@ -397,8 +398,13 @@ they're getting before they rely on a surface area:
   happens entirely in PolySimulator's paper matching engine.
 - **Collateral / balances are PAPER.** Your balance is PolySimulator's paper
   balance (the `balance` from `me()` on the native client), not an on-chain USDC
-  balance. `get_balance_allowance` reports the paper account's collateral; there
-  is no real USDC, no allowance/approval transaction, no funder wallet.
+  balance. `get_balance_allowance(asset_type="COLLATERAL")` reports the paper
+  account's cash collateral; `get_balance_allowance(asset_type="CONDITIONAL",
+  token_id=…)` reports the **conditional-token** balance — the open position's
+  share count for that token, in base units (matching real py-sdk, where a
+  CONDITIONAL read returns the held conditional token, not collateral; a flat
+  position is `0`). There is no real USDC, no allowance/approval transaction, no
+  funder wallet — so `allowances` is always empty.
 - **A settled trade carries the per-fill fee RATE, not a fee amount.**
   PolySimulator's matching engine charges and records a real (paper) fee on each
   fill. What it surfaces over the typed read surface is the fee *rate*: a settled

{polysimulator-0.4.1 → polysimulator-0.4.2}/README.md

@@ -299,7 +299,7 @@ The port is the same mechanical swap as v1 — change the import **prefix**, the
 - from polymarket import SecureClient
 + from polysim_polymarket import SecureClient
 
-- client = SecureClient(private_key="0x…")       # real Polymarket wallet + EIP-712 signing
+- client = SecureClient.create(private_key="0x…")  # real Polymarket wallet + EIP-712 signing
 + client = SecureClient(host="https://api.polysimulator.com", api_key="ps_live_…")
 
   # unchanged from here on — same method names, same keyword-only call shapes,
@@ -362,8 +362,13 @@ they're getting before they rely on a surface area:
   happens entirely in PolySimulator's paper matching engine.
 - **Collateral / balances are PAPER.** Your balance is PolySimulator's paper
   balance (the `balance` from `me()` on the native client), not an on-chain USDC
-  balance. `get_balance_allowance` reports the paper account's collateral; there
-  is no real USDC, no allowance/approval transaction, no funder wallet.
+  balance. `get_balance_allowance(asset_type="COLLATERAL")` reports the paper
+  account's cash collateral; `get_balance_allowance(asset_type="CONDITIONAL",
+  token_id=…)` reports the **conditional-token** balance — the open position's
+  share count for that token, in base units (matching real py-sdk, where a
+  CONDITIONAL read returns the held conditional token, not collateral; a flat
+  position is `0`). There is no real USDC, no allowance/approval transaction, no
+  funder wallet — so `allowances` is always empty.
 - **A settled trade carries the per-fill fee RATE, not a fee amount.**
   PolySimulator's matching engine charges and records a real (paper) fee on each
   fill. What it surfaces over the typed read surface is the fee *rate*: a settled

{polysimulator-0.4.1 → polysimulator-0.4.2}/polysim_clob_client/__init__.py

@@ -30,9 +30,11 @@ from polysim_clob_client.constants import (
     ZERO_ADDRESS,
 )
 from polysim_clob_client.exceptions import PolyApiException, PolyException
+from polysim_sdk import __version__
 
 __all__ = [
     "ClobClient",
+    "__version__",
     "ApiCreds",
     "AssetType",
     "BalanceAllowanceParams",

{polysimulator-0.4.1 → polysimulator-0.4.2}/polysim_clob_client/client.py

@@ -664,7 +664,8 @@ class ClobClient:
         order_type: OrderType | str | None,
         post_only: bool = False,
     ) -> dict[str, Any]:
-        tif = order.get("time_in_force", "GTC")
+        embedded_tif = str(order.get("time_in_force", "GTC"))
+        tif = embedded_tif
         if order_type is not None:
             tif = order_type.value if hasattr(order_type, "value") else str(order_type)
         # An embedded expiration means GTD was intended (e.g. a `create_order`
@@ -674,6 +675,17 @@ class ClobClient:
         # Never downgrade an expiring order to GTC.
         if order.get("expiration") and tif.upper() == "GTC":
             tif = "GTD"
+        # A MARKET order is a marketable-limit FOK/FAK; `create_market_order`
+        # embeds that tif. `post_order` defaults `orderType` to GTC, which would
+        # otherwise ship the contradictory `order_type=market, time_in_force=GTC`
+        # shape. When the caller left `orderType` at the GTC default, preserve the
+        # embedded FOK/FAK; an EXPLICIT FOK/FAK/GTD (anything but GTC) still wins.
+        if (
+            order.get("order_type") == "market"
+            and tif.upper() == "GTC"
+            and embedded_tif.upper() in ("FOK", "FAK")
+        ):
+            tif = embedded_tif
         return self._client.place_order(
             market_id=order["market_id"],
             side=order["side"],
@@ -713,7 +725,24 @@ class ClobClient:
         bodies: list[dict[str, Any]] = []
         for a in args:
             order = dict(a.order)
+            embedded_tif = str(order.get("time_in_force", "GTC"))
             tif = a.orderType.value if hasattr(a.orderType, "value") else str(a.orderType)
+            # Mirror _submit's GTD guard: an embedded expiration means GTD was
+            # intended (a `create_order(expiration=...)` order). `PostOrdersArgs`
+            # defaults `orderType` to GTC, which would otherwise downgrade the
+            # order to a contradictory GTC+expiration shape. Never downgrade an
+            # expiring order to GTC (an explicit non-GTC orderType still wins —
+            # exactly as `_submit` orders the two guards).
+            if order.get("expiration") and tif.upper() == "GTC":
+                tif = "GTD"
+            # Mirror _submit: a market order's embedded FOK/FAK must survive the
+            # GTC default of PostOrdersArgs.orderType (an explicit non-GTC wins).
+            if (
+                order.get("order_type") == "market"
+                and tif.upper() == "GTC"
+                and embedded_tif.upper() in ("FOK", "FAK")
+            ):
+                tif = embedded_tif
             order["time_in_force"] = tif
             if getattr(a, "postOnly", False):
                 order["post_only"] = True
@@ -751,12 +780,21 @@ class ClobClient:
         return self._client.cancel_all()
 
     def cancel_market_orders(self, market: str = "", asset_id: str = "") -> dict[str, Any]:
-        """adapt — cancel all orders in a market (``DELETE /v1/cancel-market-orders``)."""
+        """adapt — cancel all orders in a market (``DELETE /v1/cancel-market-orders``).
+
+        When only ``asset_id`` is given it is resolved to its market id via
+        :meth:`_resolve_token` (NOT the local-only ``_split_token``): a real
+        Polymarket CLOB outcome-token id (a long all-digit string) is
+        reverse-resolved through ``GET /v1/markets-by-token`` so the cancel scopes
+        the right condition id — a local split would treat the whole digit string
+        as the market and cancel the wrong (or no) market. The colon form and
+        short/non-numeric ids still resolve locally with no network call.
+        """
         market_id = market or asset_id
         if not market_id:
             raise PolyApiException(400, "cancel_market_orders requires market or asset_id.")
         if asset_id and not market:
-            market_id, _ = self._split_token(asset_id)
+            market_id, _ = self._resolve_token(asset_id)
         return self._client.cancel_market_orders(market_id)
 
     # ── order / trade reads ────────────────────────────────────────────────

{polysimulator-0.4.1 → polysimulator-0.4.2}/polysim_polymarket/__init__.py

@@ -112,6 +112,7 @@ from polysim_polymarket.rfq import (
     RfqSession,
     RfqSide,
 )
+from polysim_sdk import __version__
 
 # py-sdk exports ``SyncTransactionHandle`` (a ``TypeAlias`` for the
 # gasless|EOA sync-handle union) off its root; a ported bot type-hints
@@ -151,6 +152,7 @@ from polysim_polymarket.rfq import (
 # Each is verified present on py-sdk's root by the re-export subset test.
 __all__ = [
     "PRODUCTION",
+    "__version__",
     "AcceptedOrder",
     "ApiKeyCreds",
     "AssetType",

{polysimulator-0.4.1 → polysimulator-0.4.2}/polysim_polymarket/clients/_account.py

@@ -17,6 +17,7 @@ authenticated-surface logic the public client has no analog for.
 from __future__ import annotations
 
 from collections.abc import Sequence
+from decimal import Decimal, InvalidOperation
 from typing import Any
 
 from polysim_polymarket.errors import UnexpectedResponseError, UserInputError
@@ -69,8 +70,13 @@ def validate_asset_type(asset_type: object) -> None:
     Mirrors py-sdk's ``account._validate_asset_type`` (case-SENSITIVE — there is
     no ``.upper()``): anything else raises ``UserInputError`` with py-sdk's exact
     message, before any read.
+
+    The ``isinstance(asset_type, str)`` guard runs FIRST so an unhashable arg (a
+    ``list`` / ``dict`` a bot might pass by mistake) raises ``UserInputError``
+    rather than letting a ``TypeError`` escape the ``in`` membership test against
+    the frozenset.
     """
-    if asset_type not in VALID_ASSET_TYPES:
+    if not isinstance(asset_type, str) or asset_type not in VALID_ASSET_TYPES:
         raise UserInputError(
             f"asset_type must be 'COLLATERAL' or 'CONDITIONAL', got {asset_type!r}."
         )
@@ -118,6 +124,11 @@ def adapt_balance_allowance(payload: Any) -> BalanceAllowance:
     nearest base unit. Paper trading has no on-chain allowance, so ``allowances``
     is empty.
 
+    The scaling goes through :class:`~decimal.Decimal` (``Decimal(str(raw))``),
+    not ``float``, so a monetary value with binary-float drift (e.g. a value
+    whose ``float * 1e6`` would round to the wrong base-unit count) converts
+    exactly — money never rides a binary float through this adapter.
+
     A malformed payload (not a dict, or no numeric balance field) raises
     ``UnexpectedResponseError`` rather than silently reporting zero — a porting
     author should see the shape mismatch, not a wrong $0 balance.
@@ -132,12 +143,51 @@ def adapt_balance_allowance(payload: Any) -> BalanceAllowance:
     if raw is None:
         raise UnexpectedResponseError("balance response did not match expected shape")
     try:
-        usd = float(raw)
-    except (TypeError, ValueError) as error:
+        # ``Decimal(str(raw))`` keeps full decimal precision (str() avoids the
+        # binary-float artefacts of Decimal(<float>)); round half-even to the
+        # nearest integer base unit.
+        usd = Decimal(str(raw))
+    except (TypeError, ValueError, InvalidOperation) as error:
         raise UnexpectedResponseError(
             f"balance response 'balance' was not numeric: {raw!r}"
         ) from error
-    base_units = round(usd * USDC_BASE_UNITS_PER_USD)
+    base_units = int(round(usd * USDC_BASE_UNITS_PER_USD))
+    return BalanceAllowance(balance=base_units, allowances={})
+
+
+def adapt_conditional_balance(
+    positions: Any, market_id: str, outcome: str
+) -> BalanceAllowance:
+    """Adapt the open-positions list onto a CONDITIONAL ``BalanceAllowance``.
+
+    Resolution of the CodeRabbit/Codex disagreement: the real py-sdk's
+    ``get_balance_allowance`` for ``asset_type='CONDITIONAL'`` returns the
+    **conditional TOKEN** balance the server holds for that ``token_id`` (the
+    position's share count), NOT collateral cash. PolySimulator is paper trading
+    with no on-chain CTF balance, so the faithful analog is the open position's
+    share count for the resolved ``(market_id, outcome)`` — the conditional token
+    Polymarket would settle. Both the conditional token and USDC carry 6 decimals,
+    so the share count scales by :data:`USDC_BASE_UNITS_PER_USD`; a flat / absent
+    position is a genuine 0 conditional balance (not an error). Outcome matching
+    is case-insensitive (positions store ``"Yes"`` / ``"No"``; the token resolver
+    returns ``"YES"`` / ``"NO"`` / ``"UP"`` / ``"DOWN"``). Paper trading has no
+    on-chain allowance, so ``allowances`` is empty.
+    """
+    rows = positions if isinstance(positions, list) else []
+    target_outcome = outcome.upper()
+    shares = Decimal("0")
+    for row in rows:
+        if not isinstance(row, dict):
+            continue
+        if str(row.get("market_id")) != str(market_id):
+            continue
+        if str(row.get("outcome", "")).upper() != target_outcome:
+            continue
+        try:
+            shares += Decimal(str(row.get("quantity", "0")))
+        except (TypeError, ValueError, InvalidOperation):
+            continue
+    base_units = int(round(shares * USDC_BASE_UNITS_PER_USD))
     return BalanceAllowance(balance=base_units, allowances={})
 
 

{polysimulator-0.4.1 → polysimulator-0.4.2}/polysim_polymarket/clients/_common.py

@@ -571,3 +571,20 @@ def list_markets_forward(
     if ascending is not None:
         forward["ascending"] = ascending
     return forward
+
+
+def resolve_page_size(page_size: int) -> int:
+    """Validate + clamp a ``list_markets`` page size to the effective request limit.
+
+    Mirrors py-sdk's ``paginate_offset`` guard — a ``page_size < 1`` raises
+    ``UserInputError("page_size must be a positive integer.")`` (a non-int /
+    bool is also rejected). PolySimulator's ``/v1/markets`` hard-caps a page at
+    :data:`PAGE_LIMIT` (100) rows, so a larger ``page_size`` is clamped down to
+    that ceiling — the returned value is the effective ``limit`` the fetch +
+    cursor boundary use, so ``page_size`` is honoured rather than ignored.
+    """
+    if not isinstance(page_size, int) or isinstance(page_size, bool):
+        raise UserInputError("page_size must be a positive integer.")
+    if page_size < 1:
+        raise UserInputError("page_size must be a positive integer.")
+    return min(page_size, PAGE_LIMIT)

{polysimulator-0.4.1 → polysimulator-0.4.2}/polysim_polymarket/clients/_trade.py

@@ -138,6 +138,27 @@ _ACCEPTED_STATUS_MAP: dict[str, str] = {
     "queued": "delayed",
 }
 
+# Coarse backend rejection statuses with no finer py-sdk error code. ``/v1/orders``
+# (and the per-row ``/v1/orders/batch`` entries) can return HTTP 200 with a row
+# whose status is ``REJECTED`` / ``ERROR`` / ``FAILED`` / ``CANCELLED``. These map
+# to a RejectedOrder with the "unknown" catch-all code (the more specific statuses
+# in ``_STATUS_TO_ERROR_CODE`` keep their codes). Kept for naming clarity even
+# though acceptance is now decided by the allowlist below, not this denylist —
+# any status outside the accepted set is rejected regardless.
+_REJECTED_STATUSES: frozenset[str] = frozenset(
+    {"rejected", "error", "failed", "cancelled", "canceled"}
+)
+
+# Acceptance ALLOWLIST — mirrors py-sdk's ``order_response._is_accepted``. The real
+# py-sdk accepts a row ONLY when ``status in {live, matched, delayed}`` AND
+# ``success`` is truthy AND ``order_id != ''`` AND ``error_msg == ''``. We project
+# the paper backend's wider status vocabulary onto those three post-statuses via
+# ``_ACCEPTED_STATUS_MAP``, so the mirror's accepted set is exactly the keys of
+# that map. An UNKNOWN / unexpected status is therefore NOT accepted (it falls
+# through to RejectedOrder), matching py-sdk's strict allowlist rather than the
+# previous denylist (which mistook an unrecognised status for ``matched``).
+_ACCEPTED_STATUSES: frozenset[str] = frozenset(_ACCEPTED_STATUS_MAP)
+
 
 # ── numeric / side validation ────────────────────────────────────────────────
 # ``coerce_positive_decimal`` + ``validate_side`` are NOT re-implemented here:
@@ -149,7 +170,14 @@ _ACCEPTED_STATUS_MAP: dict[str, str] = {
 # not import ``_trade``.
 
 
-def _validate_token_id(token_id: object) -> str:
+def validate_token_id(token_id: object) -> str:
+    """Reject a non-string / empty ``token_id`` like py-sdk's token guard.
+
+    A non-``str`` raises ``"token_id must be a string, got <type>."`` and an
+    empty string raises ``"token_id is required"``. Public so the secure client
+    can validate a token UP FRONT — before any reverse-resolution network call —
+    rather than only inside ``build_*_order`` after resolution.
+    """
     if not isinstance(token_id, str):
         raise UserInputError(f"token_id must be a string, got {type(token_id).__name__}.")
     if not token_id:
@@ -210,7 +238,7 @@ def build_limit_order(
     Returns a ``SignedOrder`` carrying the trading-semantic fields + the unsigned
     paper body; signing fields stay empty placeholders.
     """
-    _validate_token_id(token_id)
+    validate_token_id(token_id)
     validated_price = coerce_positive_decimal("price", price)
     validated_size = coerce_positive_decimal("size", size)
     validate_side(side)
@@ -232,14 +260,18 @@ def build_limit_order(
 
     gtd_expiration = expiration if expiration is not None and expiration > 0 else 0
     order_type = "GTD" if gtd_expiration > 0 else "GTC"
+    # Serialize the monetary/size fields as decimal STRINGS, not floats: the
+    # backend's order body is a string-decimal contract, and a float would let
+    # binary-float drift (e.g. 0.1) ride onto the wire. ``str(Decimal(...))``
+    # carries the exact decimal the caller gave.
     body: dict[str, Any] = {
         "market_id": market_id,
         "outcome": outcome,
         "side": side,
-        "price": float(validated_price),
+        "price": str(validated_price),
         "order_type": "limit",
         "time_in_force": order_type,
-        "quantity": float(validated_size),
+        "quantity": str(validated_size),
     }
     if post_only:
         body["post_only"] = True
@@ -288,7 +320,7 @@ def build_market_order(
     when given, else the :data:`DEFAULT_BUY_WORST_PRICE` /
     :data:`DEFAULT_SELL_WORST_PRICE` default — so the FOK/FAK is never uncapped.
     """
-    _validate_token_id(token_id)
+    validate_token_id(token_id)
     validate_side(side)
     if order_type not in _VALID_MARKET_ORDER_TYPES:
         raise UserInputError(f"order_type must be 'FAK' or 'FOK', got {order_type!r}.")
@@ -319,9 +351,10 @@ def build_market_order(
             if max_price is not None
             else DEFAULT_BUY_WORST_PRICE
         )
-        # USD notional for a market BUY -> sent as ``amount`` (server derives shares).
-        body["amount"] = float(validated_amount)
-        body["price"] = float(cap)
+        # USD notional for a market BUY -> sent as ``amount`` (server derives
+        # shares). Serialized as a decimal string (string-decimal contract).
+        body["amount"] = str(validated_amount)
+        body["price"] = str(cap)
     else:  # SELL
         if shares is None:
             raise UserInputError("shares is required for SELL market orders.")
@@ -337,9 +370,9 @@ def build_market_order(
             if min_price is not None
             else DEFAULT_SELL_WORST_PRICE
         )
-        # Share count for a market SELL -> sent as ``quantity``.
-        body["quantity"] = float(validated_shares)
-        body["price"] = float(cap)
+        # Share count for a market SELL -> sent as ``quantity`` (decimal string).
+        body["quantity"] = str(validated_shares)
+        body["price"] = str(cap)
 
     return _make_signed_order(
         token_id=token_id,
@@ -414,11 +447,16 @@ def adapt_order_response(raw: Any) -> OrderResponse:
     """Adapt a PolySim ``POST /v1/orders`` reply onto py-sdk's ``OrderResponse``.
 
     A malformed reply (not a dict) raises ``UnexpectedResponseError``. Otherwise
-    we read the order id + status and decide accepted vs rejected: an explicit
-    ``success: false`` (or a recognised error status) yields a
-    :class:`RejectedOrder` with a mapped :data:`OrderResponseErrorCode`; anything
-    else is an :class:`AcceptedOrder`. Field names track py-sdk so a ported bot's
-    ``resp.ok`` / ``resp.order_id`` / ``resp.status`` read identically.
+    we decide accepted vs rejected with py-sdk's strict ALLOWLIST
+    (``order_response._is_accepted``): a row is an :class:`AcceptedOrder` ONLY when
+    its status is a recognised accepted post-status AND ``success`` is not
+    explicitly false AND it carries a non-empty ``order_id`` AND no error message —
+    exactly py-sdk's ``status in {live, matched, delayed} AND success AND
+    order_id != '' AND error_msg == ''``. ANYTHING else (including an UNKNOWN /
+    unexpected status the backend never documented) is a :class:`RejectedOrder`
+    with a mapped :data:`OrderResponseErrorCode` (specific codes for the known
+    rejection statuses, ``"unknown"`` otherwise). Field names track py-sdk so a
+    ported bot's ``resp.ok`` / ``resp.order_id`` / ``resp.status`` read identically.
     """
     if not isinstance(raw, dict):
         raise UnexpectedResponseError("order response did not match expected shape")
@@ -427,13 +465,23 @@ def adapt_order_response(raw: Any) -> OrderResponse:
     status_key = status_raw.lower()
     success = raw.get("success")
     order_id = str(raw.get("order_id", "") or raw.get("id", "") or "")
+    error_message = str(
+        raw.get("error") or raw.get("message") or raw.get("detail") or ""
+    )
 
-    rejected = success is False or status_key in _STATUS_TO_ERROR_CODE
-    if rejected:
+    # py-sdk allowlist: accepted requires ALL four — a recognised accepted status,
+    # success not explicitly false, a non-empty order id, and no error message.
+    # (The paper backend omits ``success`` on accepted rows, so absence is truthy;
+    # only an explicit ``success: false`` rejects on that axis.)
+    accepted = (
+        status_key in _ACCEPTED_STATUSES
+        and success is not False
+        and order_id != ""
+        and error_message == ""
+    )
+    if not accepted:
         code = _STATUS_TO_ERROR_CODE.get(status_key, "unknown")
-        message = str(
-            raw.get("error") or raw.get("message") or raw.get("detail") or status_raw or "rejected"
-        )
+        message = error_message or status_raw or "rejected"
         return RejectedOrder(code=code, message=message)
 
     return AcceptedOrder(
@@ -517,4 +565,5 @@ __all__ = [
     "paper_order_kwargs",
     "split_token_local",
     "validate_cancel_order_ids",
+    "validate_token_id",
 ]

{polysimulator-0.4.1 → polysimulator-0.4.2}/polysim_polymarket/clients/async_public.py

@@ -433,18 +433,15 @@ class AsyncPublicClient:
         parity and ignored.
         """
         forward = _common.list_markets_forward(closed=closed, order=order, ascending=ascending)
+        limit = _common.resolve_page_size(page_size)
 
         async def fetch(cursor: str | None) -> Page[Market]:
             offset = _decode_cursor(cursor)
             if offset < 0:
                 return Page(items=(), has_more=False)
-            rows = await self._client.list_markets(
-                limit=_common.PAGE_LIMIT, offset=offset, **forward
-            )
+            rows = await self._client.list_markets(limit=limit, offset=offset, **forward)
             items = tuple(_common.adapt_market(row) for row in rows)
-            next_cur = _next_cursor(offset, len(rows), _common.PAGE_LIMIT)
-            return Page(
-                items=items, has_more=len(rows) >= _common.PAGE_LIMIT, next_cursor=next_cur
-            )
+            next_cur = _next_cursor(offset, len(rows), limit)
+            return Page(items=items, has_more=len(rows) >= limit, next_cursor=next_cur)
 
         return AsyncPaginator(fetch=fetch)

{polysimulator-0.4.1 → polysimulator-0.4.2}/polysim_polymarket/clients/async_secure.py

@@ -57,7 +57,7 @@ import logging
 from collections.abc import Sequence
 from decimal import Decimal
 from types import TracebackType
-from typing import TYPE_CHECKING, Any, Literal, overload
+from typing import Any, Literal, overload
 
 from polysim_polymarket.clients import _account, _onchain, _trade
 from polysim_polymarket.clients.async_public import AsyncPublicClient
@@ -106,13 +106,14 @@ from polysim_polymarket.streams import (
 )
 from polysim_polymarket.streams._stream_open import open_secure_stream as _open_secure_stream
 
-if TYPE_CHECKING:
-    # ``TransactionHandle`` is the py-sdk name for the ASYNC on-chain return type
-    # (an alias of the async paper handle, defined in ``_onchain``). Imported under
-    # TYPE_CHECKING so the on-chain methods can annotate ``-> TransactionHandle``
-    # with the bare py-sdk name (annotation-string parity) without a runtime
-    # import; the returned object is the same ``_onchain`` async paper handle.
-    from polysim_polymarket.clients._onchain import TransactionHandle
+# ``TransactionHandle`` is the py-sdk name for the ASYNC on-chain return type (an
+# alias of the async paper handle, defined in ``_onchain``). The on-chain methods
+# annotate ``-> TransactionHandle`` with the bare py-sdk name (annotation parity);
+# ``_onchain`` is already imported above, so bind the name into this module's
+# globals at RUNTIME (not only under TYPE_CHECKING) — otherwise
+# ``typing.get_type_hints(AsyncSecureClient.<onchain method>)`` raises
+# ``NameError``. The returned object is the same ``_onchain`` async paper handle.
+TransactionHandle = _onchain.TransactionHandle
 
 
 class AsyncSecureClient:
@@ -489,11 +490,20 @@ class AsyncSecureClient:
 
         Async twin of ``SecureClient.get_balance_allowance``: validates
         ``asset_type`` (case-SENSITIVE) via the shared
-        :func:`_account.validate_asset_type`, reads ``GET /v1/account/balance``
-        (awaited), and adapts the paper-cash figure onto py-sdk's base-unit
-        :class:`BalanceAllowance` via :func:`_account.adapt_balance_allowance`.
+        :func:`_account.validate_asset_type`. ``COLLATERAL`` awaits
+        ``GET /v1/account/balance`` and adapts the paper-cash figure;
+        ``CONDITIONAL`` (token_id required) resolves the token, awaits
+        ``GET /v1/account/positions`` and reports the open position's share count
+        as the conditional-token balance (matching real py-sdk's CONDITIONAL
+        semantics — the held conditional token, not collateral; flat = 0).
         """
         _account.validate_asset_type(asset_type)
+        if asset_type == "CONDITIONAL":
+            if not token_id:
+                raise UserInputError("token_id is required for a CONDITIONAL balance.")
+            market_id, outcome = await self._resolve_coordinates(token_id)
+            positions = await self._client.positions()
+            return _account.adapt_conditional_balance(positions, market_id, outcome)
         payload = await self._client.balance()
         return _account.adapt_balance_allowance(payload)
 
@@ -598,7 +608,12 @@ class AsyncSecureClient:
         reverse-resolved by awaiting ``GET /v1/markets-by-token/{id}`` (cached per
         token). All routing logic is the transport-free ``_trade`` seam; only the
         awaited fetch lives here.
+
+        ``token_id`` is validated (non-empty string) UP FRONT — before the
+        reverse-resolution network call — so a bad token raises ``UserInputError``
+        rather than hitting the network.
         """
+        _trade.validate_token_id(token_id)
         if not _trade.needs_token_reverse_resolution(token_id):
             return _trade.split_token_local(token_id)
         cached = self._token_coordinates.get(token_id)

{polysimulator-0.4.1 → polysimulator-0.4.2}/polysim_polymarket/clients/public.py

@@ -428,16 +428,15 @@ class PublicClient:
         shared cursor<->offset helpers.
         """
         forward = _common.list_markets_forward(closed=closed, order=order, ascending=ascending)
+        limit = _common.resolve_page_size(page_size)
 
         def fetch(cursor: str | None) -> Page[Market]:
             offset = _decode_cursor(cursor)
             if offset < 0:
                 return Page(items=(), has_more=False)
-            rows = self._client.list_markets(limit=_common.PAGE_LIMIT, offset=offset, **forward)
+            rows = self._client.list_markets(limit=limit, offset=offset, **forward)
             items = tuple(_common.adapt_market(row) for row in rows)
-            next_cur = _next_cursor(offset, len(rows), _common.PAGE_LIMIT)
-            return Page(
-                items=items, has_more=len(rows) >= _common.PAGE_LIMIT, next_cursor=next_cur
-            )
+            next_cur = _next_cursor(offset, len(rows), limit)
+            return Page(items=items, has_more=len(rows) >= limit, next_cursor=next_cur)
 
         return Paginator(fetch=fetch)

{polysimulator-0.4.1 → polysimulator-0.4.2}/polysim_polymarket/clients/secure.py

@@ -67,7 +67,7 @@ import logging
 from collections.abc import Sequence
 from decimal import Decimal
 from types import TracebackType
-from typing import TYPE_CHECKING, Any, Literal
+from typing import Any, Literal
 
 from polysim_polymarket.clients import _account, _onchain, _trade
 from polysim_polymarket.clients.public import PublicClient
@@ -106,13 +106,15 @@ from polysim_polymarket.models import (
 )
 from polysim_polymarket.pagination import Page, Paginator, _EmptyPaginator
 
-if TYPE_CHECKING:
-    # ``SyncTransactionHandle`` is the py-sdk name for the on-chain return type (an
-    # alias of the paper handle, defined in ``_onchain``). Imported under
-    # TYPE_CHECKING so the on-chain methods can annotate ``-> SyncTransactionHandle``
-    # with the bare py-sdk name (annotation-string parity) without a runtime import;
-    # the returned object is the same ``_onchain`` paper handle either way.
-    from polysim_polymarket.clients._onchain import SyncTransactionHandle
+# ``SyncTransactionHandle`` is the py-sdk name for the on-chain return type (an
+# alias of the paper handle, defined in ``_onchain``). The on-chain methods
+# annotate ``-> SyncTransactionHandle`` with the bare py-sdk name (annotation
+# parity); ``_onchain`` is already imported above, so bind the name into this
+# module's globals at RUNTIME (not only under TYPE_CHECKING) — otherwise
+# ``typing.get_type_hints(SecureClient.<onchain method>)`` raises ``NameError``,
+# breaking any tool / doc generator that introspects the client. The returned
+# object is the same ``_onchain`` paper handle either way.
+SyncTransactionHandle = _onchain.SyncTransactionHandle
 
 
 class SecureClient:
@@ -450,13 +452,25 @@ class SecureClient:
         case-SENSITIVE (``"COLLATERAL"`` / ``"CONDITIONAL"`` only — py-sdk's
         contract); anything else raises ``UserInputError`` before any read.
 
-        Maps to PolySimulator paper cash: reads ``GET /v1/account/balance`` and
-        adapts the (USD, float) paper-cash figure onto py-sdk's base-unit
-        :class:`BalanceAllowance` shape (USDC has 6 decimals, so 1 USD = 1_000_000
-        base units). Paper trading has no on-chain allowance, so ``allowances`` is
-        empty — matching the v1 mirror's "no allowance on paper" semantics.
+        * ``COLLATERAL`` reads ``GET /v1/account/balance`` and adapts the (USD)
+          paper-cash figure onto py-sdk's base-unit shape (USDC has 6 decimals,
+          so 1 USD = 1_000_000 base units).
+        * ``CONDITIONAL`` reports the conditional TOKEN balance — matching the
+          real py-sdk, where a CONDITIONAL read returns the held conditional-token
+          balance for ``token_id`` (NOT collateral). ``token_id`` is required; it
+          is resolved to ``(market_id, outcome)`` and the open position's share
+          count is reported in base units (a flat position is a genuine 0).
+
+        Paper trading has no on-chain allowance, so ``allowances`` is empty —
+        matching the v1 mirror's "no allowance on paper" semantics.
         """
         _account.validate_asset_type(asset_type)
+        if asset_type == "CONDITIONAL":
+            if not token_id:
+                raise UserInputError("token_id is required for a CONDITIONAL balance.")
+            market_id, outcome = self._resolve_coordinates(token_id)
+            positions = self._client.positions()
+            return _account.adapt_conditional_balance(positions, market_id, outcome)
         payload = self._client.balance()
         return _account.adapt_balance_allowance(payload)
 
@@ -572,7 +586,12 @@ class SecureClient:
         market + outcome. All the routing logic is the transport-free
         :mod:`~polysim_polymarket.clients._trade` seam; only the network fetch
         lives here.
+
+        ``token_id`` is validated (non-empty string) UP FRONT — before the
+        reverse-resolution ``GET /v1/markets-by-token`` network call — so a bad
+        token raises ``UserInputError`` rather than hitting the network.
         """
+        _trade.validate_token_id(token_id)
         if not _trade.needs_token_reverse_resolution(token_id):
             return _trade.split_token_local(token_id)
         cached = self._token_coordinates.get(token_id)

{polysimulator-0.4.1 → polysimulator-0.4.2}/polysim_polymarket/models.py

@@ -21,7 +21,7 @@ exactly so the scalar types match. Timestamps mirror py-sdk's epoch-ms parsing.
 from __future__ import annotations
 
 from dataclasses import dataclass
-from datetime import UTC, datetime
+from datetime import datetime, timezone
 from decimal import Decimal
 from typing import Annotated, Literal, NamedTuple, TypeAlias
 
@@ -80,7 +80,7 @@ def _parse_epoch_ms_timestamp(value: object) -> object:
         raise ValueError(f"invalid epoch-ms timestamp: {value!r}")
     ms = int(value)
     try:
-        return datetime.fromtimestamp(ms / 1000, tz=UTC)
+        return datetime.fromtimestamp(ms / 1000, tz=timezone.utc)
     except (OverflowError, OSError, ValueError) as error:
         raise ValueError(f"invalid epoch-ms timestamp: {value!r}") from error
 

{polysimulator-0.4.1 → polysimulator-0.4.2}/polysim_polymarket/rfq.py

@@ -24,13 +24,29 @@ from __future__ import annotations
 from collections.abc import AsyncIterator, Generator
 from dataclasses import dataclass, field
 from decimal import Decimal
-from enum import StrEnum
+from enum import Enum
 from types import TracebackType
 from typing import Any, Literal, Protocol, TypeAlias, runtime_checkable
 
 from polysim_polymarket.clients._onchain import RFQ_NOT_SIMULATED
 from polysim_polymarket.errors import PolyException
 
+
+class StrEnum(str, Enum):
+    """3.10-safe stand-in for ``enum.StrEnum`` (3.11+).
+
+    ``enum.StrEnum`` only exists from 3.11; the package floor is 3.10, so we
+    mirror its observable behaviour with the classic ``(str, Enum)`` mixin —
+    members compare/hash equal to their string value and ``str(member)`` is the
+    value. The one cosmetic difference (``StrEnum``'s ``__str__`` returns the
+    value directly) is replicated below so a ported bot's ``str(RfqSide.YES)``
+    yields ``"YES"`` on both Python versions.
+    """
+
+    def __str__(self) -> str:
+        return str(self.value)
+
+
 # Id aliases — bare ``str`` NewType-equivalents (py-sdk uses ``TypeAlias = str``).
 RfqId: TypeAlias = str
 RfqQuoteId: TypeAlias = str

{polysimulator-0.4.1 → polysimulator-0.4.2}/polysim_polymarket/streams/_adapt.py

@@ -67,6 +67,7 @@ SEAMS — documented, not fabricated:
 
 from __future__ import annotations
 
+from datetime import datetime, timezone
 from typing import Any
 
 from polysim_polymarket.streams._crypto_events import (
@@ -151,6 +152,34 @@ def _split_condition_id(token_id: str) -> str:
     return tid
 
 
+def _parse_fill_timestamp(value: Any) -> datetime | None:
+    """Parse a fill frame's ``filled_at`` into an aware UTC datetime, or ``None``.
+
+    The backend stamps ``filled_at`` as an ISO-8601 string (``Order.filled_at``'s
+    ``.isoformat()``), but a frame may also carry an epoch-seconds / epoch-ms
+    value. The user-event payloads' ``timestamp`` is an
+    ``EpochSecondsOrMsTimestamp`` whose validator accepts a ``datetime`` as-is but
+    NOT an ISO string, so we resolve ISO here (normalising a trailing ``Z`` for
+    3.10's ``fromisoformat``) and let an already-numeric value flow through the
+    validator. A bad/None value yields ``None`` (the timestamp stays unset)
+    rather than sinking an otherwise-valid event.
+    """
+    if value is None or value == "":
+        return None
+    if isinstance(value, datetime):
+        return value
+    if isinstance(value, str) and not value.isdecimal():
+        text = value
+        if text.endswith(("Z", "z")):
+            text = text[:-1] + "+00:00"
+        try:
+            dt = datetime.fromisoformat(text)
+        except ValueError:
+            return None
+        return dt.replace(tzinfo=timezone.utc) if dt.tzinfo is None else dt
+    return None
+
+
 def _coerce_epoch_ms_str(value: Any) -> str | None:
     """Render an epoch-ms timestamp as the digit-string the strict market
     ``EpochMsTimestamp`` validator wants. Non-integer / non-digit inputs become
@@ -306,41 +335,66 @@ def adapt_execution_frame(frame: dict[str, Any], spec: UserSpec) -> list[UserEve
     if token_id is None:
         return []
 
-    trade = UserTradeEvent.model_validate(
-        {
-            "type": "trade",
-            "payload": {
-                "id": order_id,
-                "taker_order_id": order_id,
-                "market": market,
-                "asset_id": token_id,
-                "side": side,
-                "size": quantity,
-                "price": price,
-                "status": "MATCHED",
-                "owner": "",
-                "outcome": outcome,
-            },
-        }
-    )
-    order = UserOrderEvent.model_validate(
-        {
-            "type": "order",
-            "payload": {
-                "id": order_id,
-                "owner": "",
-                "market": market,
-                "asset_id": token_id,
-                "side": side,
-                "original_size": quantity,
-                "size_matched": quantity,
-                "price": price,
-                "type": "UPDATE",
-                "status": "MATCHED",
-                "outcome": outcome,
-            },
-        }
-    )
+    # The fill's ``filled_at`` is the trade/order timestamp. Carry it onto both
+    # payloads' ``timestamp`` (an ``EpochSecondsOrMsTimestamp``). That validator
+    # accepts an epoch number / digit-string and a ``datetime`` as-is, but NOT an
+    # ISO string — and the backend stamps ``filled_at`` as ISO — so resolve an
+    # ISO value to a ``datetime`` here and pass an epoch value through unchanged.
+    # A ``None`` / unparseable value leaves ``timestamp`` at its default ``None``.
+    raw_filled_at = frame.get("filled_at")
+    filled_at: Any
+    if isinstance(raw_filled_at, bool):
+        # ``bool`` is an ``int`` subclass — never a valid epoch; don't let
+        # ``True`` slip through as the epoch ``1`` (1970) timestamp.
+        filled_at = None
+    elif isinstance(raw_filled_at, (int, float, datetime)):
+        # epoch seconds/ms or an already-resolved datetime — the validator
+        # accepts these as-is.
+        filled_at = raw_filled_at
+    elif isinstance(raw_filled_at, str):
+        # a digit-string epoch passes straight through; an ISO (or other)
+        # string is resolved to a datetime here (or ``None`` if unparseable).
+        filled_at = (
+            raw_filled_at
+            if raw_filled_at.isdecimal()
+            else _parse_fill_timestamp(raw_filled_at)
+        )
+    else:
+        # dict / list / unexpected type — never forward it into ``timestamp``,
+        # which would make ``model_validate`` raise and sink the whole fill.
+        filled_at = None
+
+    trade_payload: dict[str, Any] = {
+        "id": order_id,
+        "taker_order_id": order_id,
+        "market": market,
+        "asset_id": token_id,
+        "side": side,
+        "size": quantity,
+        "price": price,
+        "status": "MATCHED",
+        "owner": "",
+        "outcome": outcome,
+    }
+    order_payload: dict[str, Any] = {
+        "id": order_id,
+        "owner": "",
+        "market": market,
+        "asset_id": token_id,
+        "side": side,
+        "original_size": quantity,
+        "size_matched": quantity,
+        "price": price,
+        "type": "UPDATE",
+        "status": "MATCHED",
+        "outcome": outcome,
+    }
+    if filled_at is not None and filled_at != "":
+        trade_payload["timestamp"] = filled_at
+        order_payload["timestamp"] = filled_at
+
+    trade = UserTradeEvent.model_validate({"type": "trade", "payload": trade_payload})
+    order = UserOrderEvent.model_validate({"type": "order", "payload": order_payload})
     return [trade, order]
 
 

{polysimulator-0.4.1 → polysimulator-0.4.2}/polysim_polymarket/streams/_handle.py

@@ -19,7 +19,11 @@ import asyncio
 import contextlib
 from collections.abc import AsyncIterator, Awaitable, Callable
 from types import TracebackType
-from typing import Generic, Protocol, Self, TypeVar, runtime_checkable
+from typing import Generic, Protocol, TypeVar, runtime_checkable
+
+# ``typing.Self`` is 3.11-only; the package floor is 3.10, so source it from
+# ``typing_extensions`` (a declared dependency) for a single 3.10-safe symbol.
+from typing_extensions import Self
 
 T = TypeVar("T")
 T_co = TypeVar("T_co", covariant=True)
@@ -62,6 +66,10 @@ class AsyncSubscriptionHandle(Generic[T]):
         self._ended = False
         self._dropped = 0
         self._end_error: BaseException | None = None
+        # Set once the end sentinel has been consumed by ``__anext__``. After
+        # that the handle is permanently terminal: a further ``__anext__`` must
+        # re-raise the terminal outcome WITHOUT blocking on the (now-empty) queue.
+        self._terminated = False
         self._closing: asyncio.Task[None] | None = None
         self._on_close: Callable[[AsyncSubscriptionHandle[T]], Awaitable[None]] | None = None
 
@@ -116,8 +124,16 @@ class AsyncSubscriptionHandle(Generic[T]):
         return self
 
     async def __anext__(self) -> T:
+        # Once the end sentinel has been consumed the handle is terminal: re-raise
+        # the terminal outcome immediately instead of blocking on the empty queue
+        # (the sentinel is single-use — a second ``get()`` would hang forever).
+        if self._terminated:
+            if self._end_error is not None:
+                raise self._end_error
+            raise StopAsyncIteration
         item = await self._queue.get()
         if isinstance(item, _EndSentinel):
+            self._terminated = True
             if self._end_error is not None:
                 raise self._end_error
             raise StopAsyncIteration

{polysimulator-0.4.1 → polysimulator-0.4.2}/polysim_polymarket/streams/_validators.py

@@ -10,7 +10,7 @@ permissive parsers field-for-field so the parsed scalar types match.
 
 from __future__ import annotations
 
-from datetime import UTC, datetime
+from datetime import datetime, timezone
 from decimal import Decimal
 from typing import TYPE_CHECKING, Annotated
 
@@ -44,7 +44,7 @@ def _parse_epoch_ms_timestamp(value: object) -> object:
         raise ValueError(f"invalid epoch-ms timestamp: {value!r}")
     ms = int(value)
     try:
-        return datetime.fromtimestamp(ms / 1000, tz=UTC)
+        return datetime.fromtimestamp(ms / 1000, tz=timezone.utc)
     except (OverflowError, OSError, ValueError) as error:
         raise ValueError(f"invalid epoch-ms timestamp: {value!r}") from error
 
@@ -58,18 +58,23 @@ def _parse_epoch_ms_or_iso_timestamp(value: object) -> object:
         raise ValueError(f"expected timestamp, got bool {value!r}")
     if isinstance(value, int):
         try:
-            return datetime.fromtimestamp(value / 1000, tz=UTC)
+            return datetime.fromtimestamp(value / 1000, tz=timezone.utc)
         except (OverflowError, OSError, ValueError) as error:
             raise ValueError(f"invalid epoch-ms timestamp: {value!r}") from error
     if isinstance(value, str):
         if value.isdecimal():
             ms = int(value)
             try:
-                return datetime.fromtimestamp(ms / 1000, tz=UTC)
+                return datetime.fromtimestamp(ms / 1000, tz=timezone.utc)
             except (OverflowError, OSError, ValueError) as error:
                 raise ValueError(f"invalid epoch-ms timestamp: {value!r}") from error
+        # 3.10's ``datetime.fromisoformat`` does NOT accept a trailing ``Z``
+        # (Zulu/UTC) — that only landed in 3.11. The package floor is 3.10, so
+        # normalise a trailing ``Z`` to ``+00:00`` before parsing, matching how
+        # the rest of the SDK (``polysim_sdk.updown._parse_iso``) handles it.
+        iso = value[:-1] + "+00:00" if value.endswith(("Z", "z")) else value
         try:
-            return datetime.fromisoformat(value)
+            return datetime.fromisoformat(iso)
         except ValueError as error:
             raise ValueError(f"invalid timestamp: {value!r}") from error
     raise ValueError(f"expected epoch-ms or ISO timestamp, got {type(value).__name__}")
@@ -92,7 +97,7 @@ def _parse_epoch_seconds_or_ms_timestamp(value: object) -> object:
         raise ValueError(f"expected epoch timestamp, got {type(value).__name__}")
     seconds = magnitude / 1000 if magnitude >= _EPOCH_MS_THRESHOLD else magnitude
     try:
-        return datetime.fromtimestamp(seconds, tz=UTC)
+        return datetime.fromtimestamp(seconds, tz=timezone.utc)
     except (OverflowError, OSError, ValueError) as error:
         raise ValueError(f"invalid epoch timestamp: {value!r}") from error
 
@@ -113,7 +118,7 @@ def _parse_epoch_seconds_timestamp(value: object) -> object:
     else:
         raise ValueError(f"expected epoch-seconds timestamp, got {type(value).__name__}")
     try:
-        return datetime.fromtimestamp(seconds, tz=UTC)
+        return datetime.fromtimestamp(seconds, tz=timezone.utc)
     except (OverflowError, OSError, ValueError) as error:
         raise ValueError(f"invalid epoch-seconds timestamp: {value!r}") from error
 

{polysimulator-0.4.1 → polysimulator-0.4.2}/polysim_sdk/__init__.py

@@ -26,6 +26,7 @@ Example:
     print(fill["fee"], fill["slippage_bps"])
 """
 
+from polysim_sdk._version import __version__
 from polysim_sdk.aio import AsyncPolySimClient
 from polysim_sdk.client import PolySimClient
 from polysim_sdk.constants import OrderType, Side
@@ -49,6 +50,5 @@ __all__ = [
     "RateLimitError",
     "ValidationError",
     "retry_on_market_warmup",
+    "__version__",
 ]
-
-__version__ = "0.2.2"

{polysimulator-0.4.1 → polysimulator-0.4.2}/polysim_sdk/_http.py

@@ -30,6 +30,7 @@ from urllib.parse import urljoin
 
 import httpx
 
+from polysim_sdk._version import DEFAULT_USER_AGENT
 from polysim_sdk.exceptions import (
     ApiError,
     EdgeBlockedError,
@@ -206,7 +207,7 @@ class SyncTransport:
         timeout: float = DEFAULT_TIMEOUT_SECONDS,
         max_retries: int = DEFAULT_MAX_RETRIES,
         floor_interval: float = DEFAULT_FLOOR_INTERVAL_SECONDS,
-        user_agent: str = "polysim-sdk/0.2.2",
+        user_agent: str = DEFAULT_USER_AGENT,
     ) -> None:
         self.base_url = base_url.rstrip("/")
         self._max_retries = max_retries
@@ -317,7 +318,7 @@ class AsyncTransport:
         timeout: float = DEFAULT_TIMEOUT_SECONDS,
         max_retries: int = DEFAULT_MAX_RETRIES,
         floor_interval: float = DEFAULT_FLOOR_INTERVAL_SECONDS,
-        user_agent: str = "polysim-sdk/0.2.2",
+        user_agent: str = DEFAULT_USER_AGENT,
     ) -> None:
         self.base_url = base_url.rstrip("/")
         self._max_retries = max_retries

{polysimulator-0.4.1 → polysimulator-0.4.2}/polysim_sdk/_shared.py

@@ -31,14 +31,23 @@ END_CURSOR = "LTE="
 
 
 def _decode_cursor(cursor: str | None) -> int:
-    """base64 cursor -> integer offset. START/empty -> 0, END -> -1."""
+    """base64 cursor -> integer offset. START/empty -> 0, END -> -1.
+
+    ANY decode failure (bad base64, non-ASCII / non-numeric payload, a wrong
+    input type) falls back to ``0`` rather than propagating an unexpected error
+    type — a malformed cursor must never crash a paginator. The catch is broad
+    (``Exception``) on purpose: ``base64.b64decode`` / ``bytes.decode`` /
+    ``int()`` can raise ``binascii.Error`` / ``UnicodeDecodeError`` / ``ValueError``
+    / ``TypeError`` (and a future codec could surface another), all of which mean
+    the same thing here — "unparseable cursor, start from 0".
+    """
     if not cursor or cursor == START_CURSOR:
         return 0
     if cursor == END_CURSOR:
         return -1
     try:
         return int(base64.b64decode(cursor).decode())
-    except (ValueError, TypeError):
+    except Exception:
         return 0
 
 

polysimulator-0.4.2/polysim_sdk/_version.py

@@ -0,0 +1,28 @@
+"""Single source of truth for the SDK version + default User-Agent.
+
+The version is read once from the installed package metadata
+(``importlib.metadata.version("polysimulator")``) so ``polysim_sdk.__version__``
+and the outbound ``User-Agent`` can never drift from ``[project].version`` in
+``pyproject.toml``. A literal fallback covers an editable / not-yet-installed
+checkout where the distribution metadata is absent.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+# Fallback for a checkout with no installed distribution metadata (e.g. running
+# straight from source without ``pip install -e``). Kept in sync with
+# ``[project].version`` as a last resort only — the metadata read is canonical.
+_FALLBACK_VERSION = "0.4.2"
+
+try:
+    __version__ = version("polysimulator")
+except PackageNotFoundError:  # pragma: no cover - exercised only in bare checkouts
+    __version__ = _FALLBACK_VERSION
+
+# The default outbound User-Agent. Built once from the resolved version so every
+# transport (sync/async HTTP + SSE + WS) sends a UA that matches the package.
+DEFAULT_USER_AGENT = f"polysim-sdk/{__version__}"
+
+__all__ = ["DEFAULT_USER_AGENT", "__version__"]

{polysimulator-0.4.1 → polysimulator-0.4.2}/polysim_sdk/aio.py

@@ -32,6 +32,7 @@ from polysim_sdk._http import (
     AsyncTransport,
     unwrap_list,
 )
+from polysim_sdk._version import DEFAULT_USER_AGENT
 
 
 class AsyncPolySimClient:
@@ -49,7 +50,7 @@ class AsyncPolySimClient:
         timeout: float = DEFAULT_TIMEOUT_SECONDS,
         max_retries: int = DEFAULT_MAX_RETRIES,
         floor_interval: float = DEFAULT_FLOOR_INTERVAL_SECONDS,
-        user_agent: str = "polysim-sdk/0.2.2",
+        user_agent: str = DEFAULT_USER_AGENT,
     ) -> None:
         resolved_key = api_key or os.environ.get("POLYSIM_API_KEY")
         if not resolved_key:
@@ -607,7 +608,7 @@ class AsyncPolySimClient:
         timeout: float = DEFAULT_TIMEOUT_SECONDS,
         max_retries: int = DEFAULT_MAX_RETRIES,
         floor_interval: float = DEFAULT_FLOOR_INTERVAL_SECONDS,
-        user_agent: str = "polysim-sdk/0.2.2",
+        user_agent: str = DEFAULT_USER_AGENT,
     ) -> dict[str, Any]:
         """``POST /v1/keys/bootstrap`` — JWT-authed first-key mint, no key needed.
 

{polysimulator-0.4.1 → polysimulator-0.4.2}/polysim_sdk/client.py

@@ -25,6 +25,7 @@ from polysim_sdk._http import (
     SyncTransport,
     unwrap_list,
 )
+from polysim_sdk._version import DEFAULT_USER_AGENT
 
 
 class PolySimClient:
@@ -43,7 +44,7 @@ class PolySimClient:
         timeout: float = DEFAULT_TIMEOUT_SECONDS,
         max_retries: int = DEFAULT_MAX_RETRIES,
         floor_interval: float = DEFAULT_FLOOR_INTERVAL_SECONDS,
-        user_agent: str = "polysim-sdk/0.2.2",
+        user_agent: str = DEFAULT_USER_AGENT,
     ) -> None:
         resolved_key = api_key or os.environ.get("POLYSIM_API_KEY")
         if not resolved_key:
@@ -713,7 +714,7 @@ class PolySimClient:
         timeout: float = DEFAULT_TIMEOUT_SECONDS,
         max_retries: int = DEFAULT_MAX_RETRIES,
         floor_interval: float = DEFAULT_FLOOR_INTERVAL_SECONDS,
-        user_agent: str = "polysim-sdk/0.2.2",
+        user_agent: str = DEFAULT_USER_AGENT,
     ) -> dict[str, Any]:
         """``POST /v1/keys/bootstrap`` — mint the FIRST key from a Supabase JWT.
 

{polysimulator-0.4.1 → polysimulator-0.4.2}/polysim_sdk/sse.py

@@ -32,6 +32,7 @@ from typing import TYPE_CHECKING, Any
 import httpx
 
 from polysim_sdk._http import raise_for_status, resolve_url
+from polysim_sdk._version import DEFAULT_USER_AGENT
 
 if TYPE_CHECKING:
     from polysim_sdk.aio import AsyncPolySimClient
@@ -170,7 +171,7 @@ def spot_stream(
     backoff = reconnect_min_interval
     attempts = 0
     url = resolve_url(client.base_url, "/prices/stream")
-    headers = _sse_headers(client._api_key, "polysim-sdk/0.2.2")
+    headers = _sse_headers(client._api_key, DEFAULT_USER_AGENT)
     with httpx.Client(timeout=_stream_timeout()) as http:
         while True:
             try:
@@ -228,7 +229,7 @@ async def aspot_stream(
     backoff = reconnect_min_interval
     attempts = 0
     url = resolve_url(client.base_url, "/prices/stream")
-    headers = _sse_headers(client._api_key, "polysim-sdk/0.2.2")
+    headers = _sse_headers(client._api_key, DEFAULT_USER_AGENT)
     async with httpx.AsyncClient(timeout=_stream_timeout()) as http:
         while True:
             try:

{polysimulator-0.4.1 → polysimulator-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "polysimulator"
-version = "0.4.1"
+version = "0.4.2"
 description = "Python SDK for the PolySimulator paper-trading API, with py-clob-client v1 drop-in parity (not py-clob-client-v2) and a polysim_polymarket paper-mode mirror of Polymarket's unified py-sdk (polymarket-client 0.1.0b8)."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -27,6 +27,10 @@ dependencies = [
     # polysim_polymarket (py-sdk mirror) parses read models with pydantic v2,
     # matching the real polymarket-client's modelling layer.
     "pydantic>=2,<3",
+    # ``typing_extensions.Self`` backfills ``typing.Self`` (3.11+) for the 3.10
+    # floor the package declares. (pydantic already pulls it in transitively;
+    # declared explicitly so the import is a first-class dependency.)
+    "typing_extensions>=4",
 ]
 
 [project.optional-dependencies]