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

polymarket_apis/__init__.py

@@ -1,2 +0,0 @@
-def hello() -> str:
-    return "Hello from polymarket-apis!"

polymarket_apis/clients/clob_client.py

@@ -16,6 +16,7 @@ from ..types.clob_types import (
     CreateOrderOptions,
     DailyEarnedReward,
     MarketOrderArgs,
+    MarketRewards,
     Midpoint,
     OpenOrder,
     OrderArgs,
@@ -31,7 +32,6 @@ from ..types.clob_types import (
     Price,
     PriceHistory,
     RequestArgs,
-    RewardsMarket,
     Spread,
     TickSize,
     TokenBidAskDict,
@@ -480,6 +480,7 @@ class PolymarketClobClient:
             self.creds,
             RequestArgs(method="POST", request_path=POST_ORDERS, body=body),
         )
+
         try:
             response = self.client.post(
                 self._build_url("/orders"),
@@ -524,12 +525,15 @@ class PolymarketClobClient:
             return self.builder.calculate_buy_market_price(
                 book.asks, amount, order_type,
             )
-        if book.bids is None:
-            msg = "No bid orders available"
-            raise LiquidityError(msg)
-        return self.builder.calculate_sell_market_price(
-            book.bids, amount, order_type,
-        )
+        if side == "SELL":
+            if book.bids is None:
+                msg = "No bid orders available"
+                raise LiquidityError(msg)
+            return self.builder.calculate_sell_market_price(
+                book.bids, amount, order_type,
+            )
+        msg = 'Side must be "BUY" or "SELL"'
+        raise ValueError(msg)
 
     def create_market_order(self, order_args: MarketOrderArgs, options: Optional[PartialCreateOrderOptions] = None):
         """Creates and signs a market order."""
@@ -633,9 +637,9 @@ class PolymarketClobClient:
         response.raise_for_status()
         return response.json()
 
-    def get_rewards_market(self, condition_id: Keccak256) -> RewardsMarket:
+    def get_market_rewards(self, condition_id: Keccak256) -> MarketRewards:
         """
-        Get the RewardsMarket for a given market (condition_id).
+        Get the MarketRewards for a given market (condition_id).
 
         - metadata, tokens, max_spread, min_size, rewards_config, market_competitiveness.
         """
@@ -644,7 +648,7 @@ class PolymarketClobClient:
 
         response = self.client.get(self._build_url("/rewards/markets/" + condition_id), headers=headers)
         response.raise_for_status()
-        return next(RewardsMarket(**market) for market in response.json()["data"])
+        return next(MarketRewards(**market) for market in response.json()["data"])
 
     def get_trades(
             self,
@@ -653,7 +657,7 @@ class PolymarketClobClient:
             trade_id: Optional[str] = None,
             before: Optional[datetime] = None,
             after: Optional[datetime] = None,
-            maker_address: Optional[int] = None,
+            proxy_address: Optional[int] = None,
             next_cursor="MA==") -> list[PolygonTrade]:
         """Fetches the trade history for a user."""
         params = {}
@@ -667,8 +671,8 @@ class PolymarketClobClient:
             params["before"] = int(before.replace(microsecond=0).timestamp())
         if after:
             params["after"] = int(after.replace(microsecond=0).timestamp())
-        if maker_address:
-            params["maker_address"] = maker_address
+        if proxy_address:
+            params["maker_address"] = proxy_address
 
         request_args = RequestArgs(method="GET", request_path=TRADES)
         headers = create_level_2_headers(self.signer, self.creds, request_args)

polymarket_apis/clients/data_client.py

@@ -155,7 +155,7 @@ class PolymarketDataClient:
     def get_value(
             self,
             user: str,
-            condition_id: Optional[Union[str, list[str]]] = None,
+            condition_ids: Optional[Union[str, list[str]]] = None,
     ) -> ValueResponse:
         """
         Get the current value of a user's position in a set of markets.
@@ -166,10 +166,10 @@ class PolymarketDataClient:
             - list[str] --> sum of the values of positions.
         """
         params = {"user": user}
-        if isinstance(condition_id, str):
-            params["market"] = condition_id
-        if isinstance(condition_id, list):
-            params["market"] = ",".join(condition_id)
+        if isinstance(condition_ids, str):
+            params["market"] = condition_ids
+        if isinstance(condition_ids, list):
+            params["market"] = ",".join(condition_ids)
 
         response = self.client.get(self._build_url("/value"), params=params)
         response.raise_for_status()

polymarket_apis/clients/gamma_client.py

@@ -30,13 +30,15 @@ class PolymarketGammaClient:
             offset: Optional[int] = None,
             order: Optional[str] = None,
             ascending: bool = True,
-            ids: Optional[list[int]] = None,
-            slugs: Optional[list[str]] = None,
             archived: Optional[bool] = None,
             active: Optional[bool] = None,
             closed: Optional[bool] = None,
+            slugs: Optional[list[str]] = None,
+            market_ids: Optional[list[int]] = None,
             token_ids: Optional[list[str]] = None,
             condition_ids: Optional[list[str]] = None,
+            tag_id: Optional[int] = None,
+            related_tags: Optional[bool] = False,
             liquidity_num_min: Optional[float] = None,
             liquidity_num_max: Optional[float] = None,
             volume_num_min: Optional[float] = None,
@@ -45,8 +47,6 @@ class PolymarketGammaClient:
             start_date_max: Optional[datetime] = None,
             end_date_min: Optional[datetime] = None,
             end_date_max: Optional[datetime] = None,
-            tag_id: Optional[int] = None,
-            related_tags: Optional[bool] = False,
     ) -> list[GammaMarket]:
         params = {}
         if limit:
@@ -56,8 +56,6 @@ class PolymarketGammaClient:
         if order:
             params["order"] = order
             params["ascending"] = ascending
-        if ids:
-            params["id"] = ids
         if slugs:
             params["slug"] = slugs
         if archived is not None:
@@ -66,6 +64,8 @@ class PolymarketGammaClient:
             params["active"] = active
         if closed is not None:
             params["closed"] = closed
+        if market_ids:
+            params["id"] = market_ids
         if token_ids:
             params["clob_token_ids"] = token_ids
         if condition_ids:
@@ -243,13 +243,16 @@ class PolymarketGammaClient:
             sort: Literal["volume", "volume_24hr", "liquidity", "start_date", "end_date", "competitive"] = "volume_24hr",
             page: int = 1,
             limit_per_type: int = 50, # max is 50
+            presets: Optional[Literal["EventsHybrid", "EventsTitle"] | list[Literal["EventsHybrid", "EventsTitle"]]] = None,
     ) -> EventList:
         """Search for events by query. Should emulate the website search function."""
-        params = {"q": query,"page": page, "limit_per_type": limit_per_type, "events_status": status, "active": active, "presets": "EventsTitle"}
+        params = {"q": query,"page": page, "limit_per_type": limit_per_type, "events_status": status, "active": active}
         if sort:
             params["sort"] = sort
         if sort == "end_date":
             params["ascending"] = "true"
+        if presets:
+            params["presets"] = presets
         response = self.client.get(self._build_url("/public-search"), params=params)
         response.raise_for_status()
         return EventList(**response.json())

polymarket_apis/clients/graphql_client.py

@@ -1,182 +1,43 @@
-from typing import Literal, Optional
+from typing import Literal
 
 from gql import Client, gql
-from gql.transport.httpx import HTTPXAsyncTransport
-from graphql import GraphQLInputObjectType, GraphQLObjectType
+from gql.transport.httpx import HTTPXAsyncTransport, HTTPXTransport
 
 from ..utilities.config import GRAPHQL_ENDPOINTS
 
+EndpointName = Literal[
+            "activity_subgraph",
+            "fpmm_subgraph",
+            "open_interest_subgraph",
+            "orderbook_subgraph",
+            "pnl_subgraph",
+            "positions_subgraph",
+            "sports_oracle_subgraph",
+            "wallet_subgraph",
+            ]
 
-class PolymarketGraphQLClient:
-    def __init__(self,
-                endpoint_name: Literal[
-                    "activity_subgraph",
-                    "fpmm_subgraph",
-                    "open_interest_subgraph",
-                    "orderbook_subgraph",
-                    "pnl_subgraph",
-                    "positions_subgraph",
-                    "sports_oracle_subgraph",
-                    "wallet_subgraph",
-                ]):
-        if endpoint_name not in GRAPHQL_ENDPOINTS:
-            msg = f"Invalid endpoint name: {endpoint_name}. Must be one of {list(GRAPHQL_ENDPOINTS.keys())}"
-            raise ValueError(msg)
-        endpoint_url = GRAPHQL_ENDPOINTS[endpoint_name]
-        self.transport = HTTPXAsyncTransport(url=endpoint_url)
-        self.client = Client(transport=self.transport, fetch_schema_from_transport=True)
-        self.schema = None
-        self.object_types = []
-        self.query_fields = []
-        self.subscription_fields = []
-        self.filter_input_types = []
-
-    async def _init_schema(self):
-        async with self.client as session:
-            self.schema = session.schema
-
-    async def _get_query_fields(self):
-        if self.query_fields:
-            return self.query_fields
-        if not self.schema:
-            await self._init_schema()
-        self.query_fields = [field for field in self.schema.type_map["Query"].fields if not field.startswith("_")]
-
-        return self.query_fields
-
-    async def _get_subscription_fields(self):
-        if self.subscription_fields:
-            return self.subscription_fields
-        if not self.schema:
-            await self._init_schema()
-        if "Subscription" in self.schema.type_map:
-            self.subscription_fields = [field for field in self.schema.type_map["Subscription"].fields if not field.startswith("_")]
-        else:
-            self.subscription_fields = []
-        return self.subscription_fields
-
-    async def _get_object_types(self):
-        if self.object_types:
-            return self.object_types
-        if not self.schema:
-            await self._init_schema()
-        for object_name, object in self.schema.type_map.items():
-            if type(object) is GraphQLObjectType and not object_name.startswith("_"):
-                self.object_types.append(object_name)
-        return self.object_types
-
-    async def _get_filter_input_types(self):
-        if self.filter_input_types:
-            return self.filter_input_types
-        if not self.schema:
-            await self._init_schema()
-        for object_name, object in self.schema.type_map.items():
-            if isinstance(object, GraphQLInputObjectType) and not object_name.startswith("_"):
-                self.filter_input_types.append(object_name)
-        return self.filter_input_types
-
-    async def list_queries(self):
-        if self.query_fields:
-            return self.query_fields
-        return await self._get_query_fields()
 
-    async def list_subscriptions(self):
-        if self.subscription_fields:
-            return self.subscription_fields
-        return await self._get_subscription_fields()
-
-    async def list_object_types(self):
-        if self.object_types:
-            return self.object_types
-        return await self._get_object_types()
-
-    async def list_filter_input_types(self):
-        if self.filter_input_types:
-            return self.filter_input_types
-        return await self._get_filter_input_types()
-
-    async def get_fields(self, object_name: str):
-        if self.schema is None:
-            await self._init_schema()
-        if object_name not in self.schema.type_map:
-            msg = "Invalid object name"
-            raise ValueError(msg)
-        return list(self.schema.type_map[object_name].fields.keys())
-
-    async def query(
-        self,
-        endpoint: str,
-        fields: list[str],
-        filters: Optional[dict] = None,
-        relationships: Optional[dict] = None,
-    ):
-        if not self.schema:
-            await self._init_schema()
-        if not self.query_fields:
-            await self._get_query_fields()
-        if not self.object_types:
-            await self._get_object_types()
-
-        if endpoint not in self.query_fields:
-            msg = f"Invalid endpoint: {endpoint}"
-            raise ValueError(msg)
-
-        endpoint_field = self.schema.type_map["Query"].fields[endpoint]
-        required_args = [
-            arg_name for arg_name, arg in endpoint_field.args.items()
-            if arg.type.to_kwargs().get("required", False)
-        ]
-        missing_args = [arg for arg in required_args if not (filters and arg in filters)]
-        if missing_args:
-            msg = f"Missing required argument(s) for '{endpoint}': {', '.join(missing_args)}"
-            raise ValueError(msg)
+class PolymarketGraphQLClient:
+    """Synchronous GraphQL client for Polymarket subgraphs."""
 
-        def build_selection(fields, relationships):
-            selections = []
-            for field in fields:
-                if relationships and field in relationships:
-                    subfields = relationships[field]
-                    selections.append(f"{field} {{ {' '.join(subfields)} }}")
-                else:
-                    selections.append(field)
-            return " ".join(selections)
+    def __init__(self, endpoint_name: EndpointName) -> None:
+        endpoint_url = GRAPHQL_ENDPOINTS[endpoint_name]
+        self.transport = HTTPXTransport(url=endpoint_url)
+        self.client = Client(transport=self.transport, fetch_schema_from_transport=False)
 
-        def build_args(filters):
-            """Build GraphQL arguments, handling both simple and complex where clauses."""
-            if not filters:
-                return ""
+    def query(self, query_string: str) -> dict:
+        with self.client as session:
+            return session.execute(gql(query_string))
 
-            arg_strs = []
-            for k, v in filters.items():
-                if k == "where" and isinstance(v, dict):
-                    # Handle complex where clause
-                    where_conditions = []
-                    for where_key, where_value in v.items():
-                        if isinstance(where_value, str):
-                            where_conditions.append(f"{where_key}: {where_value}")
-                        else:
-                            where_conditions.append(f"{where_key}: {where_value}")
-                    where_str = "{" + ", ".join(where_conditions) + "}"
-                    arg_strs.append(f"{k}: {where_str}")
-                # Handle simple key-value filters
-                elif isinstance(v, str):
-                    arg_strs.append(f'{k}: "{v}"')
-                else:
-                    arg_strs.append(f"{k}: {v}")
 
-            return "(" + ", ".join(arg_strs) + ")"
+class AsyncPolymarketGraphQLClient:
+    """Asynchronous GraphQL client for Polymarket subgraphs."""
 
-        selection_set = build_selection(fields, relationships)
-        args = build_args(filters)
+    def __init__(self, endpoint_name: EndpointName) -> None:
+        endpoint_url = GRAPHQL_ENDPOINTS[endpoint_name]
+        self.transport = HTTPXAsyncTransport(url=endpoint_url)
+        self.client = Client(transport=self.transport, fetch_schema_from_transport=False)
 
-        query_str = f"""
-        query {{
-            {endpoint}{args} {{
-                {selection_set}
-            }}
-        }}
-        """
-        print(query_str)
+    async def query(self, query_string: str) -> dict:
         async with self.client as session:
-            result = await session.execute(gql(query_str))
-        return result
+            return await session.execute(gql(query_string))

polymarket_apis/clients/web3_client.py

@@ -195,6 +195,7 @@ class PolymarketWeb3Client:
         self.w3.eth.wait_for_transaction_receipt(tx_hash)
 
         print("Done!")
+
     def redeem_position(self, condition_id: Keccak256, amounts: list[float], neg_risk: bool = True):
         """
         Redeem a position into usdc.

polymarket_apis/clients/websockets_client.py

@@ -6,8 +6,6 @@ from lomond import WebSocket
 from lomond.persist import persist
 from pydantic import ValidationError
 
-from polymarket_apis.utilities.exceptions import AuthenticationRequiredError
-
 from ..types.clob_types import ApiCreds
 from ..types.websockets_types import (
     ActivityOrderMatchEvent,
@@ -32,6 +30,7 @@ from ..types.websockets_types import (
     TickSizeChangeEvent,
     TradeEvent,
 )
+from ..utilities.exceptions import AuthenticationRequiredError
 
 
 def _process_market_event(event):

polymarket_apis/types/clob_types.py

@@ -153,7 +153,7 @@ class PolymarketRewardItem(BaseModel):
     market_competitiveness: float
 
 
-class RewardsMarket(BaseModel):
+class MarketRewards(BaseModel):
     condition_id: Keccak256
     question: str
     market_slug: str
@@ -254,7 +254,7 @@ class OpenOrder(BaseModel):
     price: float
     outcome: str
     expiration: datetime
-    order_type: Literal["GTC", "FOK", "GTD"]
+    order_type: Literal["GTC", "GTD"]
     associate_trades: list[str]
     created_at: datetime
 

polymarket_apis/types/data_types.py

@@ -12,11 +12,11 @@ class Position(BaseModel):
 
     # Asset information
     token_id: str = Field(alias="asset")
+    complementary_token_id: str = Field(alias="oppositeAsset")
     condition_id: Keccak256 = Field(alias="conditionId")
     outcome: str
+    complementary_outcome: str = Field(alias="oppositeOutcome")
     outcome_index: int = Field(alias="outcomeIndex")
-    opposite_outcome: str = Field(alias="oppositeOutcome")
-    opposite_asset: str = Field(alias="oppositeAsset")
 
     # Position details
     size: float

polymarket_apis/types/gamma_types.py

@@ -332,7 +332,7 @@ class Pagination(BaseModel):
     total_results: int = Field(alias="totalResults")
 
 class EventList(BaseModel):
-    events: list[QueryEvent]
+    events: Optional[list[QueryEvent]] = None
     pagination: Pagination
 
 class QueryMarket(BaseModel):

polymarket_apis/types/websockets_types.py

@@ -67,7 +67,7 @@ class OrderEvent(BaseModel):
     size_matched: float
     original_size: float
     outcome: str
-    order_type: Literal["GTC", "FOK", "GTD"]
+    order_type: Literal["GTC", "GTD", "FOK", "FAK"]
 
     created_at: datetime
     expiration: Optional[datetime] = None
@@ -284,16 +284,16 @@ class MarketStatusChangeEvent(BaseModel):
     topic: Literal["clob_market"]
 
 class LiveDataOrderEvent(BaseModel):
-    connection_id: str
     payload: OrderEvent
     timestamp: datetime
+    connection_id: str
     type: Literal["order"]
     topic: Literal["clob_user"]
 
 class LiveDataTradeEvent(BaseModel):
-    connection_id: str
     payload: TradeEvent
     timestamp: datetime
+    connection_id: str
     type: Literal["trade"]
     topic: Literal["clob_user"]
 

polymarket_apis/utilities/order_builder/builder.py

@@ -220,7 +220,7 @@ class OrderBuilder:
     def calculate_sell_market_price(
             self,
             bids: list[OrderSummary], # expected to be sorted from worst to best price (low to high)
-            amount_to_match: float, # in usdc
+            amount_to_match: float, # in shares
             order_type: OrderType,
     ) -> float:
         if not bids:
@@ -231,8 +231,10 @@ class OrderBuilder:
         for p in reversed(bids):
             sum += float(p.size)
             if sum >= amount_to_match:
+                print(f"market order price {p.price}")
                 return float(p.price)
 
+
         if order_type == OrderType.FOK:
             msg = "no match"
             raise ValueError(msg)

polymarket_apis/utilities/order_builder/helpers.py

@@ -1,32 +1,34 @@
 import hashlib
-from decimal import Decimal
-from math import ceil, floor
+from decimal import ROUND_CEILING, ROUND_FLOOR, ROUND_HALF_UP, Decimal
 
 from ...types.clob_types import OrderBookSummary, TickSize
 
 
 def round_down(x: float, sig_digits: int) -> float:
-    return floor(x * (10**sig_digits)) / (10**sig_digits)
+    exp = Decimal(1).scaleb(-sig_digits)
+    return float(Decimal(str(x)).quantize(exp=exp, rounding=ROUND_FLOOR))
 
 
 def round_normal(x: float, sig_digits: int) -> float:
-    return round(x * (10**sig_digits)) / (10**sig_digits)
+    exp = Decimal(1).scaleb(-sig_digits)
+    return float(Decimal(str(x)).quantize(exp=exp, rounding=ROUND_HALF_UP))
 
 
 def round_up(x: float, sig_digits: int) -> float:
-    return ceil(x * (10**sig_digits)) / (10**sig_digits)
+    exp = Decimal(1).scaleb(-sig_digits)
+    return float(Decimal(str(x)).quantize(exp=exp, rounding=ROUND_CEILING))
 
 
 def to_token_decimals(x: float) -> int:
-    f = (10**6) * x
-    if decimal_places(f) > 0:
-        f = round_normal(f, 0)
-    return int(f)
+    exp = Decimal(1)
+    return int(
+        Decimal(str(x)) * Decimal(10**6).quantize(exp=exp, rounding=ROUND_HALF_UP),
+    )
 
 
 def decimal_places(x: float) -> int:
     """
-    Returns the number of decimal places in a float.
+    Returns the number of decimal places in a numeric value.
 
     Assumes x is always a finite, non-special value (not NaN or Infinity).
     """
@@ -34,7 +36,7 @@ def decimal_places(x: float) -> int:
     if not isinstance(exponent, int):
         msg = "Input must be a finite float."
         raise TypeError(msg)
-    return abs(exponent)
+    return max(0, -exponent)
 
 
 

polymarket_apis/utilities/schemas/activity-subgraph.graphql

@@ -0,0 +1,86 @@
+type Split @entity {
+  "Transaction Hash"
+  id: ID!
+  "Timestamp at which split occurred"
+  timestamp: BigInt!
+  "Address which is performing this split"
+  stakeholder: String!
+  "Condition on which split is occuring"
+  condition: String!
+  "The amount of collateral/outcome tokens being split"
+  amount: BigInt!
+}
+
+type Merge @entity {
+  "Transaction Hash"
+  id: ID!
+  "Timestamp at which merge occurred"
+  timestamp: BigInt!
+  "Address which is performing this merge"
+  stakeholder: String!
+  "Token which is collateralising positions being merged"
+  condition: String!
+  "The amount of collateral/outcome tokens being merged"
+  amount: BigInt!
+}
+
+type Redemption @entity {
+  "Transaction Hash"
+  id: ID!
+  "Timestamp at which redemption occurred"
+  timestamp: BigInt!
+  "Address which is redeeming these outcomes"
+  redeemer: String!
+  "Condition on which redemption is occuring"
+  condition: String!
+  "Outcomes which are being redeemed"
+  indexSets: [BigInt!]!
+  "The amount of collateral being claimed"
+  payout: BigInt!
+}
+
+type NegRiskConversion @entity {
+  "Transaction Hash"
+  id: ID!
+  "Timestamp at which conversion occurred"
+  timestamp: BigInt!
+  "Address which is performing this conversion"
+  stakeholder: String!
+  "Neg Risk Market Id assigned to the event"
+  negRiskMarketId: String!
+  "The amount of each token being converted"
+  amount: BigInt!
+  "The index set of the outcome tokens being converted"
+  indexSet: BigInt!
+  "The number of questions at the time of conversion"
+  questionCount: Int!
+}
+
+# Neg Risk Events/Markets
+type NegRiskEvent @entity {
+  "negRiskMarketId"
+  id: ID!
+  "Question Count"
+  questionCount: Int!
+}
+
+# Fixed Product Market Makers
+type FixedProductMarketMaker @entity {
+  "Market maker address"
+  id: ID!
+}
+
+# Metadata for the market, keyed by positionId
+type Position @entity {
+  "ERC1155 TokenID of the CTF Asset"
+  id: ID!
+  "Condition that the token is linked to"
+  condition: String!
+  "Outcome Index"
+  outcomeIndex: BigInt!
+}
+
+type Condition @entity {
+  "Condition ID"
+  id: ID!
+}

polymarket_apis/utilities/schemas/open-interest.graphql

@@ -0,0 +1,30 @@
+type Condition @entity {
+  "conditionId"
+  id: ID!
+}
+
+# Neg Risk Events/Markets
+type NegRiskEvent @entity {
+  "negRiskMarketId"
+  id: ID!
+  "Fee Bps"
+  feeBps: BigInt!
+  "Question Count"
+  questionCount: Int!
+}
+
+# Market Open Interest
+type MarketOpenInterest @entity {
+  "Condition ID"
+  id: ID!
+  "Open interest for the market"
+  amount: BigInt!
+}
+
+# Global Open Interest
+type GlobalOpenInterest @entity {
+  "Empty string"
+  id: ID!
+  "Global Open Interest"
+  amount: BigInt!
+}

polymarket_apis-0.3.0.dist-info/METADATA

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: polymarket-apis
+Version: 0.3.0
+Summary: Unified Polymarket APIs - clob, gamma, data, web3, websockets
+Author-email: Razvan Gheorghe <razvan@gheorghe.me>
+Requires-Python: >=3.12
+Requires-Dist: gql[httpx]>=4.0.0
+Requires-Dist: httpx[http2]>=0.25.1
+Requires-Dist: lomond>=0.3.3
+Requires-Dist: poly-eip712-structs>=0.0.1
+Requires-Dist: py-order-utils>=0.3.2
+Requires-Dist: pydantic>=2.10.5
+Requires-Dist: web3>=7.0
+Requires-Dist: wsaccel>=0.6.7
+Description-Content-Type: text/markdown
+
+# polymarket-apis [![PyPI version](https://img.shields.io/pypi/v/polymarket-apis.svg)](https://pypi.org/project/polymarket-apis/)
+
+Polymarket CLOB, Gamma, Data, Web3, Websockets and GraphQL clients.
+
+## Polymarket Mental Models
+
+### Events, Markets and Outcomes
+
+The Polymarket ecosystem is organized hierarchically:
+
+```mermaid
+flowchart LR
+    A([Event]) --- B([Market A])
+    A --- C([Market B])
+    A ~~~ Dot1@{ shape: sm-circ}
+    A ~~~ Dot2@{ shape: sm-circ}
+    A ~~~ Dot3@{ shape: sm-circ}
+    A -.- D([Market n])
+    B --- E([Outcome 1])
+    B --- F([Outcome 2])
+    C --- G([Outcome 1])
+    C --- H([Outcome 2])
+```
+
+- **Event** — represents a proposition or question such as “How many Fed rate cuts in 2025?”.  
+  - Identified by a human-readable **`slug`** (e.g. `how-many-fed-rate-cuts-in-2025`) and an **event `id`** (e.g. `16085`).
+
+- **Market** — represents a specific option for the related event (e.g. 1 rate cut in 2025). An Event has 1 or more corresponding Markets. (e.g. 9 options in this case - {0, 1, 2, ..., 7, 8 or more} rate cuts in 2025)
+  - Identified by a **`condition id`** (e.g. `0x8e9b6942b4dac3117dadfacac2edb390b6d62d59c14152774bb5fcd983fc134e` for 1 rate cut in 2025), a human-readable **`slug`** (e.g. `'will-1-fed-rate-cut-happen-in-2025'`) and a **market `id`** (e.g. `516724`).
+
+- **Outcome** — represents a binary option related to a market. (most commonly `Yes`/`No`, but can be e.g. `Paris Saint-Germain`/`Inter Milan` in the case of a match where draws are not possible)
+  - Identified by a **`token id`** (e.g. `15353185604353847122370324954202969073036867278400776447048296624042585335546` for the `Yes` outcome in the 1 rate cut in 2025 market)
+
+### Tokens
+- **Tokens** are the blockchain implementation of **Outcomes** - tradable digital assets on the Polygon blockchain that users buy, hold and sell on Polygon. 
+- This helps ensure the logic of binary outcome prediction markets through smart contracts (e.g. collateralization, token prices going to $1.00 or $0.00 after resolution, splits/merges).
+
+### Splits and Merges
+- Holding 1 `Yes` share + 1 `No` share in a **Market** (e.g. `'will-1-fed-rate-cut-happen-in-2025'`) covers the entire universe of possibilities and guarantees a $1.00 payout regardless of outcome. This mathematical relationship enables Polymarket's core mechanisms: splitting (1 USDC → 1 `Yes` + 1 `No`) and merging (1 `Yes` + 1 `No` → 1 USDC) at any point before resolution.
+- Splits are the only way tokens are created. Either a user splits USDC into equal shares of the complementary tokens or Polymarket automatically splits USDC when it matches an `Yes` buy order at e.g. 30¢ with a `No` buy order at 70¢.
+
+### Unified Order Book
+- Polymarket uses traditional exchange mechanics - a Central Limit Order Book (CLOB), where users place buy and sell orders that get matched by price and time priority.
+- However, because the `Yes` and `No` outcomes form a complete probability universe, certain orders become mathematically equivalent - allowing the matching engine to find trades as exemplified above.
+- This unified structure means every **BUY** order for `Outcome 1` at price **X** is simultaneously visible as a **SELL** order for `Outcome 2` at price **(100¢ - X)**, creating deeper liquidity and tighter spreads than separate order books would allow.
+
+### Negative Risk and Conversions
+- If the **Markets** in and **Event** collectively cover a complete universe of possibilities (e.g. {0, 1, 2, ..., 7, 8 or more} rate cuts in 2025) and only one winner is possible, two collections of positions (made up of tokens and USDC) become mathematically equivalent and the **Event** is said to support negative risk.
+  - e.g. Hold 1 `No` token in the 0 rate cuts in 2025. This is equivalent to holding 1 `Yes` token in each of the other **Markets** {1, 2, ..., 7, 8 or more}.
+- An interesting consequence is that holding `No` tokens in more than one **Market** is equivalent to `Yes` tokens ***and*** some USDC.
+  - e.g. Hold 1 `No` token on each of {0, 1, 2, ..., 7, 8 or more} rate cuts in 2025. Because only one winner is possible, this guarantees that 8 out of the 9 **Markets** resolve to `No`. This is equivalent to a position of 8 USDC.
+  - e.g. Hold 1 `No` token on each of {0, 1} rate cuts in 2025. This is equivalent to 1 `Yes` token in {2, ..., 7, 8 or more} and 1 USDC.
+- Polymarket allows for the one way (for capital efficiency) conversion from `No` tokens to a collection of `Yes` tokens and USDC before resolution through a smart contract.
+
+## Clients overview
+- ### PolymarketClobClient - Order book related operations
+  - #### Order book
+    - get one or more order books, best price, spread, midpoint, last trade price by `token_id`(s)
+  - #### Orders
+    - create and post limit or market orders
+    - cancel one or more orders by `order_id`(s)
+    - get active orders
+  - #### Trades
+    - get trade history for a user with filtering by `condition_id`, `token_id`, `trade_id`, time window
+  - #### Rewards
+    - check if one or more orders are scoring for liquidity rewards by `order_id`(s)
+    - get daily earned rewards
+    - check if a **Market** offers rewards by `condition_id` - **get_market_rewards()**
+    - get all active markets that offer rewards sorted by different metrics and ordered, filtered by a query, show your favourites from the web app  - **get_reward_markets()** (*naming would do with some work*)
+  - #### Miscellaneous
+    - get price history
+    - get **ClobMarket** by `condition_id`
+    - get all **ClobMarkets**
+
+  ### PolymarketGammaClient - Market/Event related operations
+    - #### Market
+      - get **GammaMarket** by `market_id`
+      - get **GammaMarkets** with pagination (offset and limit), filter by `slug`s, `market_id`s, `token_id`s, `condition_id`s, `tag_id` or filtered by active, closed, archived, liquidity window, volume window, start date window, end date window and ordered
+    - #### Event
+      - get **Event** by `event_id`
+      - get **Events** with pagination, filter by `slug`s, `event_id`s, `tag_id` or filtered by active, closed, archived, liquidity window, volume window, start date window, end date window and ordered
+      - get all **Events** given some filtration
+      - search **Events**, filter by text query, active/resolved, sort by volume/volume_24hr/liquidity/start_date/end_date/competitive (tries to mimic the web app search bar)
+    - #### Miscellaneous
+      - grok event summary by **Event** `slug`
+      - grok election market explanation by candidate name and election title
+
+  ### PolymarketDataClient - Portfolio related operations
+  - #### Positions
+    - get positions with pagination (offset and limit) by user address, filter by `condition_id`, position size, redeemability, mergeability, title
+  - #### Trades
+    - get trades with pagination, filter by `condition id`, user address, side, taker only or not, cash amount/token amount
+  - #### Activity
+    - get activity with pagination by user address, filter by type (trade, split, merge, redeem, reward, conversion), `condition_id`, time window, side, sort by timestamp/tokens/cash
+  - #### Holders
+    - get top holders by `condition_id`
+  - #### Value
+    - get positions value by user address and condition_ids
+      - `condition_ids` is ***None*** → total value of positions
+      - `condition_ids` is ***str*** → value of positions on a market
+      - `condition_ids` is ***list[str]*** → sum of values of positions on multiple markets
+  - #### Miscellaneous
+    - get pnl timeseries by user address for a period (1d, 1w, 1m, all) with frequency (1h, 3h, 12h, 1d)
+    - get overall pnl/volume by user address for a recent window (1d, 7d, 30d, all)
+    - get user rank on the profit/volume leaderboards by user address for a recent window (1d, 7d, 30d, all)
+    - get top users on the profit/volume leaderboards (at most 100) for a recent window (1d, 7d, 30d, all)
+
+  ### PolymarketWeb3Client - Blockchain related operations
+  - #### Balance
+    - get usdc balance by user address
+    - get token balance by `token_id` and user address
+  - #### Token/USDC conversions
+    - split USDC into complementary tokens - needs `condition_id`, amount, neg_risk bool
+    - merge complementary tokens into USDC - needs `condition_id`, amount, neg_risk bool
+    - redeem token into USDC - needs `condition_id`, amounts array [`Yes` shares, `No` shares], neg_risk bool
+    - convert 1 or more `No` tokens in a *negative risk* **Event** into a collection of USDC and `Yes` tokens on the other **Markets** in the **Event**
+
+  ### PolymarketWebsocketsClient - Real time data subscriptions
+  - subscribe to **market socket** with `token_ids` list, receive different event types:
+    - order book summary
+    - price change
+    - tick size change
+    - last trade price
+  - subscribe to **user socket** with **ApiCreds**, receive different event types:
+    - order (status - live, canceled, matched)
+    - trade (status - matched, mined, confirmed, retrying, failed)
+  - subscribe to **live data socket** with any combination described [here](https://github.com/Polymarket/real-time-data-client?tab=readme-ov-file#subscribe) - ***newest endpoint*** - includes the other sockets, receive:
+    - all of the above event types
+    - market (created, resolved)
+    - comment/reaction (created, removed)
+    - trades/orders_matched (all, not just yours) - filter by **Event** `slug` or **Market** `slug`
+    - crypto price
+    - request/quote (created, edited, canceled, expired) - rqf not public yet
+
+  ### PolymarketGraphQLClient/AsyncPolymarketGraphQLClient - Goldsky hosted Subgraphs queries
+  - instantiate with an endpoint name from:
+    - activity_subgraph
+    - fpmm_subgraph
+    - open_interest_subgraph
+    - orderbook_subgraph
+    - pnl_subgraph
+    - positions_subgraph
+    - sports_oracle_subgraph
+    - wallet_subgraph
+  - ****query()**** takes in a GraphQL query string and returns the raw json

{polymarket_apis-0.2.5.dist-info → polymarket_apis-0.3.0.dist-info}/RECORD

@@ -1,17 +1,17 @@
-polymarket_apis/__init__.py,sha256=8a6dT19YqnOcLEmprl8vavi97JpaRrcDWBTllGsrmbE,61
+polymarket_apis/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 polymarket_apis/clients/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-polymarket_apis/clients/clob_client.py,sha256=pE-q-4hAUyKIUHN5tbBxX4o4uzMGiMcTNQ2dIJLQkDY,31025
-polymarket_apis/clients/data_client.py,sha256=sAJqesjKT8cRNr-j4OsXj-xYHEOzt0WWCvXcvejX7uI,8641
-polymarket_apis/clients/gamma_client.py,sha256=yGi7l0vceBgrwMlqLFZYyQ_Lj13hNaDwaBtLSDoTAnM,12190
-polymarket_apis/clients/graphql_client.py,sha256=Jgrz107EVpHRSAXvY45hRUKuPndl9-41_EaqIYbb5mo,6907
-polymarket_apis/clients/web3_client.py,sha256=0SX25LMP59FWzfsoshxt-_XNPcPXnmvwmCaHu3K4K2E,11222
-polymarket_apis/clients/websockets_client.py,sha256=wueJ54ZgJgeiJmKi5EEIB8_YwkdD3y2Dr4t9WjFMXuU,7581
+polymarket_apis/clients/clob_client.py,sha256=HO9ACvdODfj6n_W7lkgpCAtm7Y-vEhGK-8bmEtnh8sI,31152
+polymarket_apis/clients/data_client.py,sha256=zkfYoejsrAjwbhBfpMVLiM3YYoXqgvLhnHZ5fc7QVZI,8646
+polymarket_apis/clients/gamma_client.py,sha256=-GhPBoRnnMl1Ex6oGI6ToKfGXGXVRjVZ-G1vO4eJjVI,12370
+polymarket_apis/clients/graphql_client.py,sha256=kN3hk0kKmZhwnN5YfC-8XbebNyoho7dRdZC9p6aC8_A,1511
+polymarket_apis/clients/web3_client.py,sha256=XQApKIAkS0-TAWrApI1DFDvW0udbpkWzXiyGXo-GNec,11223
+polymarket_apis/clients/websockets_client.py,sha256=gJiJ087PenrpNG4Y2ffu0S1he82TQOJhD9JbLyMbc_U,7566
 polymarket_apis/types/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-polymarket_apis/types/clob_types.py,sha256=O7_6x5gtLjjkcVhcUMv7aIyFhdk2LRfRObPibRwdC44,11699
+polymarket_apis/types/clob_types.py,sha256=LboySm6z_Pb-sf30BHATfi1-CC0LFT_CHv-gzJdkxk0,11692
 polymarket_apis/types/common.py,sha256=eTY2kjOArzrZRVSmEJvxEyxGJeMx045R073EMZMzCKM,1629
-polymarket_apis/types/data_types.py,sha256=K-bE5g1owFozvznmQZ0MicxGccqVSuEibuVzXFAoa4E,4408
-polymarket_apis/types/gamma_types.py,sha256=CfjuQbkNaM-PcZoezSZvMk4ru7a4AzXh64Clbf13MHc,12518
-polymarket_apis/types/websockets_types.py,sha256=96xQl6xQ4ReL-b4a-UYNittPvXJBXuzX1RBxlJHJg-s,11993
+polymarket_apis/types/data_types.py,sha256=5vLo4CnAXApHhbPrtj_xnYQPeRnTYhjuY8EGJU7KeUU,4421
+polymarket_apis/types/gamma_types.py,sha256=xSafNRgkYXqIq3Vd5J3k018ue79rEiulczwUHuP8Uxo,12535
+polymarket_apis/types/websockets_types.py,sha256=4a__lrxnFWkWnOa8i-6wsV5Q0AaLq3srPNDhnKyfGAo,12000
 polymarket_apis/utilities/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 polymarket_apis/utilities/config.py,sha256=IfIBJa6rSi-e-9_HjeI8j4cD3MXtzRjoLzgcgn5tHbc,2448
 polymarket_apis/utilities/constants.py,sha256=OdxaAsyYzAK1RXty5VtvidMgan8YW-JfHS3Rdxp6n_U,580
@@ -19,8 +19,10 @@ polymarket_apis/utilities/endpoints.py,sha256=bxZyrJBPbVauWc-eR0RMh6KDqU-SmO_3Lf
 polymarket_apis/utilities/exceptions.py,sha256=58vuiLuZxX6d05qa29jgEOC4ZYBv368JaO8DAFMD0Dc,363
 polymarket_apis/utilities/headers.py,sha256=Cc5WEnIBLYAgfwvmCXRBwA2zUYME8fDy4PbwlwlB6Oo,1510
 polymarket_apis/utilities/order_builder/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-polymarket_apis/utilities/order_builder/builder.py,sha256=-eQ092J6Wkproy2SY6USFGWAniS5ZMBg85Ij_cnqqPs,8332
-polymarket_apis/utilities/order_builder/helpers.py,sha256=QN39noGcWrGAy89dJc8DvEGJwiX0fMVc62R-pkclAu4,1714
+polymarket_apis/utilities/order_builder/builder.py,sha256=GMKkc96ZpLBBBQDRqIRKs8Kjl75zUbdRpS8IAFV_7Fg,8390
+polymarket_apis/utilities/order_builder/helpers.py,sha256=eMcx17W41rKQ7hDP4Ch8QRtS3WQ5zNMyKtgmOe8-3fk,1944
+polymarket_apis/utilities/schemas/activity-subgraph.graphql,sha256=B6FnnOUvix2qE4S4puPgzt-fSz_SlnJaEKrKE0kGCuc,2033
+polymarket_apis/utilities/schemas/open-interest.graphql,sha256=42sNE49KfEJMoxDapKvo38eOYiaiOWZyINTKevWhpUY,478
 polymarket_apis/utilities/signing/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 polymarket_apis/utilities/signing/eip712.py,sha256=fGLurznnfY5M0VCP1Txyq_FYQRfggyHoTwz-PGIK2Eg,895
 polymarket_apis/utilities/signing/hmac.py,sha256=vAYb98tMHWqNqAJNFXUnAddS38dA_aOy3Wp3DcP_7PM,702
@@ -36,6 +38,6 @@ polymarket_apis/utilities/web3/abis/ProxyWalletFactory.json,sha256=5KjBHUWdkc_kd
 polymarket_apis/utilities/web3/abis/UChildERC20Proxy.json,sha256=ZyQC38U0uxInlmnW2VXDVD3TJfTIRmSNMkTxQsaG7oA,27396
 polymarket_apis/utilities/web3/abis/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 polymarket_apis/utilities/web3/abis/custom_contract_errors.py,sha256=ZCeJPK5tobPAR9vaNxw_pQZwKyZc_R0GdggfWaeXvOs,1176
-polymarket_apis-0.2.5.dist-info/METADATA,sha256=B3ij72Emt46fd9e8pfCxn7rtxG2lulL5T9Xz33Et8Uo,558
-polymarket_apis-0.2.5.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-polymarket_apis-0.2.5.dist-info/RECORD,,
+polymarket_apis-0.3.0.dist-info/METADATA,sha256=dYODMIGPXBh9NVImiRM-P7EXzL26gE6GZYRq6dzxFaU,10454
+polymarket_apis-0.3.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+polymarket_apis-0.3.0.dist-info/RECORD,,

polymarket_apis-0.2.5.dist-info/METADATA

@@ -1,18 +0,0 @@
-Metadata-Version: 2.4
-Name: polymarket-apis
-Version: 0.2.5
-Summary: Unified Polymarket APIs - clob, gamma, data, web3, websockets
-Author-email: Razvan Gheorghe <razvan@gheorghe.me>
-Requires-Python: >=3.12
-Requires-Dist: httpx[http2]>=0.25.1
-Requires-Dist: lomond>=0.3.3
-Requires-Dist: poly-eip712-structs>=0.0.1
-Requires-Dist: py-order-utils>=0.3.2
-Requires-Dist: pydantic>=2.10.5
-Requires-Dist: web3>=7.0
-Requires-Dist: wsaccel>=0.6.7
-Description-Content-Type: text/markdown
-
-# polymarket-apis
-
-Polymarket CLOB, Gamma, Data and Web3 and Websockets clients.