polymarket-apis 0.3.0__py3-none-any.whl → 0.3.9__py3-none-any.whl

polymarket_apis/clients/websockets_client.py

@@ -61,6 +61,7 @@ def _process_market_event(event):
         print(e.errors())
         print(event.json)
 
+
 def _process_user_event(event):
     try:
         message = event.json
@@ -75,6 +76,7 @@ def _process_user_event(event):
         print(event.text)
         print(e.errors(), "\n")
 
+
 def _process_live_data_event(event):
     try:
         message = event.json
@@ -87,7 +89,12 @@ def _process_live_data_event(event):
                 print(CommentEvent(**message), "\n")
             case "reaction_created" | "reaction_removed":
                 print(ReactionEvent(**message), "\n")
-            case "request_created" | "request_edited" | "request_canceled" | "request_expired":
+            case (
+                "request_created"
+                | "request_edited"
+                | "request_canceled"
+                | "request_expired"
+            ):
                 print(RequestEvent(**message), "\n")
             case "quote_created" | "quote_edited" | "quote_canceled" | "quote_expired":
                 print(QuoteEvent(**message), "\n")
@@ -117,13 +124,16 @@ def _process_live_data_event(event):
         print(e.errors(), "\n")
         print(event.text)
 
+
 class PolymarketWebsocketsClient:
     def __init__(self):
         self.url_market = "wss://ws-subscriptions-clob.polymarket.com/ws/market"
         self.url_user = "wss://ws-subscriptions-clob.polymarket.com/ws/user"
         self.url_live_data = "wss://ws-live-data.polymarket.com"
 
-    def market_socket(self, token_ids: list[str], process_event: Callable = _process_market_event):
+    def market_socket(
+        self, token_ids: list[str], process_event: Callable = _process_market_event
+    ):
         """
         Connect to the market websocket and subscribe to market events for specific token IDs.
 
@@ -142,7 +152,9 @@ class PolymarketWebsocketsClient:
             elif event.name == "text":
                 process_event(event)
 
-    def user_socket(self, creds: ApiCreds, process_event: Callable = _process_user_event):
+    def user_socket(
+        self, creds: ApiCreds, process_event: Callable = _process_user_event
+    ):
         """
         Connect to the user websocket and subscribe to user events.
 
@@ -161,7 +173,12 @@ class PolymarketWebsocketsClient:
             elif event.name == "text":
                 process_event(event)
 
-    def live_data_socket(self, subscriptions: list[dict[str, Any]], process_event: Callable = _process_live_data_event, creds: Optional[ApiCreds] = None):
+    def live_data_socket(
+        self,
+        subscriptions: list[dict[str, Any]],
+        process_event: Callable = _process_live_data_event,
+        creds: Optional[ApiCreds] = None,
+    ):
         # info on how to subscribe found at https://github.com/Polymarket/real-time-data-client?tab=readme-ov-file#subscribe
         """
         Connect to the live data websocket and subscribe to specified events.
@@ -175,13 +192,13 @@ class PolymarketWebsocketsClient:
         websocket = WebSocket(self.url_live_data)
 
         needs_auth = any(sub.get("topic") == "clob_user" for sub in subscriptions)
-        if needs_auth and creds is None:
-            msg = "ApiCreds credentials are required for the clob_user topic subscriptions"
-            raise AuthenticationRequiredError(msg)
 
         for event in persist(websocket):
             if event.name == "ready":
                 if needs_auth:
+                    if creds is None:
+                        msg = "ApiCreds credentials are required for the clob_user topic subscriptions"
+                        raise AuthenticationRequiredError(msg)
                     subscriptions_with_creds = []
                     for sub in subscriptions:
                         if sub.get("topic") == "clob_user":

polymarket_apis/types/__init__.py

@@ -0,0 +1,167 @@
+# python
+"""
+Type definitions for Polymarket APIs.
+
+This module contains all the Pydantic models and type definitions used across
+the Polymarket APIs.
+"""
+
+from .clob_types import (
+    ApiCreds,
+    AssetType,
+    BidAsk,
+    BookParams,
+    ClobMarket,
+    ContractConfig,
+    CreateOrderOptions,
+    DailyEarnedReward,
+    MarketOrderArgs,
+    MarketRewards,
+    Midpoint,
+    OpenOrder,
+    OrderArgs,
+    OrderBookSummary,
+    OrderCancelResponse,
+    OrderPostResponse,
+    OrderType,
+    PaginatedResponse,
+    PartialCreateOrderOptions,
+    PolygonTrade,
+    PostOrdersArgs,
+    Price,
+    PriceHistory,
+    RewardMarket,
+    Spread,
+    TickSize,
+    Token,
+    TokenBidAsk,
+    TokenBidAskDict,
+    TokenValue,
+    TokenValueDict,
+)
+from .common import (
+    EmptyString,
+    EthAddress,
+    FlexibleDatetime,
+    Keccak256,
+    TimeseriesPoint,
+)
+from .data_types import (
+    Activity,
+    Holder,
+    HolderResponse,
+    Position,
+    Trade,
+    User,
+    UserMetric,
+    UserRank,
+    ValueResponse,
+)
+from .gamma_types import (
+    ClobReward,
+    Event,
+    GammaMarket,
+    Pagination,
+    Series,
+    Tag,
+)
+from .websockets_types import (
+    ActivityOrderMatchEvent,
+    ActivityTradeEvent,
+    CommentEvent,
+    CryptoPriceSubscribeEvent,
+    CryptoPriceUpdateEvent,
+    ErrorEvent,
+    LastTradePriceEvent,
+    LiveDataLastTradePriceEvent,
+    LiveDataOrderBookSummaryEvent,
+    LiveDataOrderEvent,
+    LiveDataPriceChangeEvent,
+    LiveDataTickSizeChangeEvent,
+    LiveDataTradeEvent,
+    MarketStatusChangeEvent,
+    OrderBookSummaryEvent,
+    OrderEvent,
+    PriceChangeEvent,
+    QuoteEvent,
+    ReactionEvent,
+    RequestEvent,
+    TickSizeChangeEvent,
+    TradeEvent,
+)
+
+__all__ = [
+    "Activity",
+    "ActivityOrderMatchEvent",
+    "ActivityTradeEvent",
+    "ApiCreds",
+    "AssetType",
+    "BidAsk",
+    "BookParams",
+    "ClobMarket",
+    "ClobReward",
+    "CommentEvent",
+    "ContractConfig",
+    "CreateOrderOptions",
+    "CryptoPriceSubscribeEvent",
+    "CryptoPriceUpdateEvent",
+    "DailyEarnedReward",
+    "EmptyString",
+    "ErrorEvent",
+    "EthAddress",
+    "Event",
+    "FlexibleDatetime",
+    "GammaMarket",
+    "Holder",
+    "HolderResponse",
+    "Keccak256",
+    "LastTradePriceEvent",
+    "LiveDataLastTradePriceEvent",
+    "LiveDataOrderBookSummaryEvent",
+    "LiveDataOrderEvent",
+    "LiveDataPriceChangeEvent",
+    "LiveDataTickSizeChangeEvent",
+    "LiveDataTradeEvent",
+    "MarketOrderArgs",
+    "MarketRewards",
+    "MarketStatusChangeEvent",
+    "Midpoint",
+    "OpenOrder",
+    "OrderArgs",
+    "OrderBookSummary",
+    "OrderBookSummaryEvent",
+    "OrderCancelResponse",
+    "OrderEvent",
+    "OrderPostResponse",
+    "OrderType",
+    "PaginatedResponse",
+    "Pagination",
+    "PartialCreateOrderOptions",
+    "PolygonTrade",
+    "Position",
+    "PostOrdersArgs",
+    "Price",
+    "PriceChangeEvent",
+    "PriceHistory",
+    "QuoteEvent",
+    "ReactionEvent",
+    "RequestEvent",
+    "RewardMarket",
+    "Series",
+    "Spread",
+    "Tag",
+    "TickSize",
+    "TickSizeChangeEvent",
+    "TimeseriesPoint",
+    "Token",
+    "TokenBidAsk",
+    "TokenBidAskDict",
+    "TokenValue",
+    "TokenValueDict",
+    "Trade",
+    "TradeEvent",
+    "User",
+    "UserMetric",
+    "UserRank",
+    "ValueResponse",
+]

polymarket_apis/types/clob_types.py

@@ -17,10 +17,11 @@ from pydantic import (
 )
 
 from ..types.common import EthAddress, Keccak256, TimeseriesPoint
-from ..utilities.constants import ZERO_ADDRESS
+from ..utilities.constants import ADDRESS_ZERO
 
 logger = logging.getLogger(__name__)
 
+
 class ApiCreds(BaseModel):
     key: str = Field(alias="apiKey")
     secret: str
@@ -122,11 +123,13 @@ class Rewards(BaseModel):
     rewards_min_size: int = Field(alias="min_size")
     rewards_max_spread: float = Field(alias="max_spread")
 
+
 class EarnedReward(BaseModel):
     asset_address: EthAddress
     earnings: float
     asset_rate: float
 
+
 class DailyEarnedReward(BaseModel):
     date: datetime
     asset_address: EthAddress
@@ -134,12 +137,12 @@ class DailyEarnedReward(BaseModel):
     earnings: float
     asset_rate: float
 
-class PolymarketRewardItem(BaseModel):
+
+class RewardMarket(BaseModel):
     market_id: str
     condition_id: Keccak256
     question: str
     market_slug: str
-    market_description: str
     event_slug: str
     image: str
     maker_address: EthAddress
@@ -165,6 +168,7 @@ class MarketRewards(BaseModel):
     rewards_min_size: int
     market_competitiveness: float
 
+
 class ClobMarket(BaseModel):
     # Core market information
     token_ids: list[Token] = Field(alias="tokens")
@@ -215,7 +219,9 @@ class ClobMarket(BaseModel):
 
     @field_validator("neg_risk_market_id", "neg_risk_request_id", mode="wrap")
     @classmethod
-    def validate_neg_risk_fields(cls, value: str, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Optional[str]:
+    def validate_neg_risk_fields(
+        cls, value: str, handler: ValidatorFunctionWrapHandler, info: ValidationInfo
+    ) -> str | None:
         try:
             return handler(value)
         except ValidationError as e:
@@ -227,12 +233,18 @@ class ClobMarket(BaseModel):
                 return value
             if neg_risk and value == "":
                 for _ in e.errors():
-                    msg = ("Poorly setup market: negative risk is True, but either neg_risk_market_id or neg_risk_request_id is missing. "
-                           f" Question: {info.data.get("question")}; Market slug: {info.data.get('market_slug')} \n")
+                    msg = (
+                        "Poorly setup market: negative risk is True, but either neg_risk_market_id or neg_risk_request_id is missing. "
+                        f" Question: {info.data.get('question')}; Market slug: {info.data.get('market_slug')} \n"
+                    )
                     logger.warning(msg)
+            return None
+
     @field_validator("condition_id", "question_id", mode="wrap")
     @classmethod
-    def validate_condition_fields(cls, value: str, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> str:
+    def validate_condition_fields(
+        cls, value: str, handler: ValidatorFunctionWrapHandler, info: ValidationInfo
+    ) -> str:
         try:
             return handler(value)
         except ValueError:
@@ -241,6 +253,7 @@ class ClobMarket(BaseModel):
                 return value
             raise
 
+
 class OpenOrder(BaseModel):
     order_id: Keccak256 = Field(alias="id")
     status: str
@@ -258,6 +271,7 @@ class OpenOrder(BaseModel):
     associate_trades: list[str]
     created_at: datetime
 
+
 class MakerOrder(BaseModel):
     token_id: str = Field(alias="asset_id")
     order_id: Keccak256
@@ -268,6 +282,7 @@ class MakerOrder(BaseModel):
     outcome: str
     fee_rate_bps: float
 
+
 class PolygonTrade(BaseModel):
     trade_id: str = Field(alias="id")
     taker_order_id: Keccak256
@@ -277,7 +292,7 @@ class PolygonTrade(BaseModel):
     size: float
     fee_rate_bps: float
     price: float
-    status: str # change to literals MINED, CONFIRMED
+    status: str  # change to literals MINED, CONFIRMED
     match_time: datetime
     last_update: datetime
     outcome: str
@@ -288,6 +303,7 @@ class PolygonTrade(BaseModel):
     maker_orders: list[MakerOrder]
     trader_side: Literal["TAKER", "MAKER"]
 
+
 class TradeParams(BaseModel):
     id: Optional[str] = None
     maker_address: Optional[str] = None
@@ -304,12 +320,13 @@ class OpenOrderParams(BaseModel):
 
 
 class DropNotificationParams(BaseModel):
-    ids: Optional[list[str]]= None
+    ids: Optional[list[str]] = None
 
 
 class OrderSummary(BaseModel):
-    price: Optional[float] = None
-    size: Optional[float] = None
+    price: float
+    size: float
+
 
 class PriceLevel(OrderSummary):
     side: Literal["BUY", "SELL"]
@@ -375,6 +392,7 @@ class RoundConfig(BaseModel):
     size: int
     amount: int
 
+
 class OrderArgs(BaseModel):
     token_id: str
     """
@@ -411,7 +429,7 @@ class OrderArgs(BaseModel):
     Timestamp after which the order is expired.
     """
 
-    taker: str = ZERO_ADDRESS
+    taker: str = ADDRESS_ZERO
     """
     Address of the order taker. The zero address is used to indicate a public order.
     """
@@ -449,19 +467,21 @@ class MarketOrderArgs(BaseModel):
     Nonce used for onchain cancellations.
     """
 
-    taker: str = ZERO_ADDRESS
+    taker: str = ADDRESS_ZERO
     """
     Address of the order taker. The zero address is used to indicate a public order.
     """
 
     order_type: OrderType = OrderType.FOK
 
+
 class PostOrdersArgs(BaseModel):
     order: SignedOrder
     order_type: OrderType = OrderType.GTC
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
+
 class ContractConfig(BaseModel):
     """Contract Configuration."""
 
@@ -486,9 +506,10 @@ class OrderPostResponse(BaseModel):
     order_id: Union[Keccak256, Literal[""]] = Field(alias="orderID")
     taking_amount: str = Field(alias="takingAmount")
     making_amount: str = Field(alias="makingAmount")
-    status: str = Literal["live", "matched", "delayed"]
+    status: Literal["live", "matched", "delayed"]
     success: bool
 
+
 class OrderCancelResponse(BaseModel):
     not_canceled: Optional[dict[Keccak256, str]]
     canceled: Optional[list[Keccak256]]

polymarket_apis/types/common.py

@@ -1,51 +1,121 @@
 import re
-from datetime import datetime
-from typing import Annotated
+from datetime import UTC, datetime
+from typing import Annotated, Any
 
-from pydantic import AfterValidator, BaseModel, BeforeValidator, Field
+from dateutil import parser
+from hexbytes import HexBytes
+from pydantic import AfterValidator, BaseModel, BeforeValidator, ConfigDict, Field
 
 
-def validate_keccak256(v: str) -> str:
+def parse_flexible_datetime(v: str | datetime) -> datetime:
+    """Parse datetime from multiple formats using dateutil."""
+    if v in {"NOW*()", "NOW()"}:
+        return datetime.fromtimestamp(0, tz=UTC)
+
+    if isinstance(v, str):
+        parsed = parser.parse(v)
+        if not isinstance(parsed, datetime):
+            msg = f"Failed to parse '{v}' as datetime, got {type(parsed)}"
+            raise TypeError(msg)
+        return parsed
+    return v
+
+
+def validate_keccak256(v: str | HexBytes | bytes) -> str:
+    """Validate and normalize Keccak256 hash format."""
+    # Convert HexBytes/bytes to string
+    if isinstance(v, HexBytes | bytes):
+        v = v.hex()
+
+    # Ensure string and add 0x prefix if missing
+    if not isinstance(v, str):
+        msg = f"Expected string or bytes, got {type(v)}"
+        raise TypeError(msg)
+
+    if not v.startswith("0x"):
+        v = "0x" + v
+
+    # Validate format: 0x followed by 64 hex characters
     if not re.match(r"^0x[a-fA-F0-9]{64}$", v):
-        msg = "Invalid Keccak256 hash format"
+        msg = f"Invalid Keccak256 hash format: {v}"
         raise ValueError(msg)
+
     return v
 
-def parse_timestamp(v: str) -> datetime:
-    if isinstance(v, datetime):
+
+def validate_eth_address(v: str | HexBytes | bytes) -> str:
+    """Validate and normalize Ethereum address format."""
+    # Convert HexBytes/bytes to string
+    if isinstance(v, HexBytes | bytes):
+        v = v.hex()
+
+    # Ensure string and add 0x prefix if missing
+    if not isinstance(v, str):
+        msg = f"Expected string or bytes, got {type(v)}"
+        raise TypeError(msg)
+
+    if not v.startswith("0x"):
+        v = "0x" + v
+
+    # Validate format: 0x followed by 40 hex characters
+    if not re.match(r"^0x[a-fA-F0-9]{40}$", v, re.IGNORECASE):
+        msg = f"Invalid Ethereum address format: {v}"
+        raise ValueError(msg)
+
+    return v
+
+
+def hexbytes_to_str(v: Any) -> str:
+    """Convert HexBytes to hex string with 0x prefix."""
+    if isinstance(v, HexBytes):
+        hex_str = v.hex()
+        return hex_str if hex_str.startswith("0x") else f"0x{hex_str}"
+    if isinstance(v, bytes):
+        return "0x" + v.hex()
+    if isinstance(v, str) and not v.startswith("0x"):
+        return f"0x{v}"
+    return v
+
+
+def validate_keccak_or_padded(v: Any) -> str:
+    """
+    Validate Keccak256 or accept padded addresses (32 bytes with leading zeros).
+
+    Some log topics are padded addresses, not proper Keccak256 hashes.
+    """
+    # First convert HexBytes/bytes to string with 0x prefix
+    if isinstance(v, HexBytes | bytes):
+        v = v.hex()
+
+    # Ensure it's a string
+    if not isinstance(v, str):
+        msg = f"Expected string or bytes, got {type(v)}"
+        raise TypeError(msg)
+
+    # Add 0x prefix if missing
+    if not v.startswith("0x"):
+        v = "0x" + v
+
+    # Accept 66 character hex strings (0x + 64 hex chars)
+    if len(v) == 66 and all(c in "0123456789abcdefABCDEF" for c in v[2:]):
         return v
-    # Normalize '+00' to '+0000' for timezone
-    if v.endswith("+00"):
-        v = v[:-3] + "+0000"
-
-    # Pad fractional seconds to 6 digits if present
-    if "." in v:
-        dot_pos = v.find(".")
-        tz_pos = v.find("+", dot_pos)  # Find timezone start after '.'
-        if tz_pos == -1:
-            tz_pos = v.find("-", dot_pos)
-
-        if tz_pos != -1:
-            frac = v[dot_pos+1:tz_pos]
-            if len(frac) < 6:
-                frac = frac.ljust(6, "0")
-                v = f"{v[:dot_pos+1]}{frac}{v[tz_pos:]}"
-
-    # Try parsing with and without microseconds
-    for fmt in ("%Y-%m-%d %H:%M:%S.%f%z", "%Y-%m-%d %H:%M:%S%z"):
-        try:
-            return datetime.strptime(v, fmt) # noqa: DTZ007
-        except ValueError:
-            continue
-    msg = f"Time data '{v}' does not match expected formats."
+
+    msg = (
+        f"Invalid hash format: expected 66 characters (0x + 64 hex), got {len(v)}: {v}"
+    )
     raise ValueError(msg)
 
 
-TimestampWithTZ = Annotated[datetime, BeforeValidator(parse_timestamp)]
-EthAddress = Annotated[str, Field(pattern=r"^0x[A-Fa-f0-9]{40}$")]
+FlexibleDatetime = Annotated[datetime, BeforeValidator(parse_flexible_datetime)]
+EthAddress = Annotated[str, AfterValidator(validate_eth_address)]
 Keccak256 = Annotated[str, AfterValidator(validate_keccak256)]
+HexString = Annotated[str, BeforeValidator(hexbytes_to_str)]
+Keccak256OrPadded = Annotated[str, BeforeValidator(validate_keccak_or_padded)]
 EmptyString = Annotated[str, Field(pattern=r"^$", description="An empty string")]
 
+
 class TimeseriesPoint(BaseModel):
-    value: float
-    timestamp: datetime
+    model_config = ConfigDict(populate_by_name=True)
+
+    value: float = Field(alias="p")
+    timestamp: datetime = Field(alias="t")

polymarket_apis/types/data_types.py

@@ -1,11 +1,43 @@
 from datetime import UTC, datetime
-from typing import Literal
+from typing import Literal, Optional
 
-from pydantic import BaseModel, Field, field_validator
+from pydantic import BaseModel, Field, field_validator, model_validator
 
 from .common import EmptyString, EthAddress, Keccak256
 
 
+class GQLPosition(BaseModel):
+    user: EthAddress
+    token_id: str
+    complementary_token_id: str
+    condition_id: Keccak256
+    outcome_index: int
+    balance: float
+
+    @model_validator(mode="before")
+    def _flatten(cls, values):
+        asset = values.get("asset")
+        if isinstance(asset, dict):
+            if "id" in asset:
+                values.setdefault("token_id", asset["id"])
+            if "complement" in asset:
+                values.setdefault("complementary_token_id", asset["complement"])
+            condition = asset.get("condition")
+            if isinstance(condition, dict) and "id" in condition:
+                values.setdefault("condition_id", condition["id"])
+            if "outcomeIndex" in asset:
+                values.setdefault("outcome_index", asset["outcomeIndex"])
+            values.pop("asset", None)
+        return values
+
+    @field_validator("balance", mode="before")
+    @classmethod
+    def _parse_balance(cls, value):
+        if isinstance(value, str):
+            value = int(value)
+        return value / 10**6
+
+
 class Position(BaseModel):
     # User identification
     proxy_wallet: EthAddress = Field(alias="proxyWallet")
@@ -44,7 +76,7 @@ class Position(BaseModel):
     @field_validator("end_date", mode="before")
     def handle_empty_end_date(cls, v):
         if v == "":
-            return datetime(2099,12,31, tzinfo=UTC)
+            return datetime(2099, 12, 31, tzinfo=UTC)
         return v
 
 
@@ -145,6 +177,7 @@ class ValueResponse(BaseModel):
     # Value information
     value: float
 
+
 class User(BaseModel):
     proxy_wallet: EthAddress = Field(alias="proxyWallet")
     name: str
@@ -152,10 +185,22 @@ class User(BaseModel):
     profile_image: str = Field(alias="profileImage")
     profile_image_optimized: str = Field(alias="profileImageOptimized")
 
+
 class UserMetric(User):
     amount: float
     pseudonym: str
 
+
 class UserRank(User):
     amount: float
     rank: int
+
+
+class MarketValue(BaseModel):
+    condition_id: Keccak256 = Field(alias="market")
+    value: float
+
+
+class EventLiveVolume(BaseModel):
+    total: Optional[float]
+    markets: Optional[list[MarketValue]]