Upload builderbrain/polymarket_client.py

builderbrain/polymarket_client.py

@@ -3,13 +3,22 @@ Polymarket API Client + Builder Code Router
 ===========================================
 
 Handles:
-- Live market data ingestion (prices, liquidity, orderbook)
-- Builder code registration and routing
-- Order construction and execution
-- Paper trading mode for hackathon demo
+- Live market data ingestion via Polymarket Gamma API
+- Builder code registration and order attribution
+- Order construction and execution (paper or live)
 
-Builder codes earn fees on every trade routed through them.
-This is the monetization layer for the intelligence agent.
+Builder Code Details (from Polymarket docs):
+- Register at: https://polymarket.com/settings?tab=builder
+- Code format: bytes32 (e.g. 0x0000...0001)
+- Attached per order as an order FIELD (not header/query param):
+    { "builderCode": "0x...", "price": 0.55, "size": 100, ... }
+- Serialized on-chain as the `builder` field
+- No extra auth required beyond normal CLOB credentials
+- Track volume at: https://builders.polymarket.com
+
+API:
+- Gamma API: https://gamma-api.polymarket.com
+- CLOB API: https://clob.polymarket.com
 """
 
 import requests
@@ -54,14 +63,14 @@ class OrderIntent:
     outcome: str  # 'YES' or 'NO'
     size: float  # USD notional
     price: float  # limit price 0-1
-    builder_code: Optional[str] = None
+    builder_code: Optional[str] = None  # bytes32 hex string, e.g. "0x0000...0001"
     client_order_id: Optional[str] = None
 
 
 @dataclass
 class BuilderCode:
     """A registered builder code for fee sharing."""
-    code: str
+    code: str  # bytes32 hex string
     name: str
     description: str
     fee_share_bps: int  # basis points earned on routed volume
@@ -78,8 +87,13 @@ class PolymarketClient:
     """
     Polymarket API client with builder code support.
     
-    Uses Gamma API for market data.
+    Uses Gamma API for market data, CLOB API for orderbook.
     Supports paper trading for hackathon demos.
+    
+    Builder Code Registration:
+    1. Go to https://polymarket.com/settings?tab=builder
+    2. Copy your bytes32 builder code
+    3. Pass it to BuilderCodeRouter or OrderIntent.builder_code
     """
     
     GAMMA_API = "https://gamma-api.polymarket.com"
@@ -119,7 +133,6 @@ class PolymarketClient:
             
             markets = []
             for m in data.get("markets", data if isinstance(data, list) else []):
-                # Handle different API response shapes
                 if isinstance(m, dict):
                     markets.append(self._parse_market(m))
             
@@ -130,14 +143,11 @@ class PolymarketClient:
     
     def _parse_market(self, raw: Dict) -> PolymarketMarket:
         """Parse raw API response into PolymarketMarket."""
-        # Handle nested structure
         market_data = raw.get("market", raw)
         
-        # Prices can be in different fields depending on API version
         yes_price = market_data.get("bestYesPrice", market_data.get("yesPrice", 0.5))
         no_price = market_data.get("bestNoPrice", market_data.get("noPrice", 0.5))
         
-        # Normalize prices to 0-1
         if yes_price > 1:
             yes_price /= 100
         if no_price > 1:
@@ -160,7 +170,7 @@ class PolymarketClient:
         )
     
     def fetch_orderbook(self, market_id: str) -> Optional[Dict]:
-        """Fetch L2 orderbook for a market."""
+        """Fetch L2 orderbook for a market from CLOB API."""
         url = f"{self.CLOB_API}/book/{market_id}"
         try:
             resp = self.session.get(url, timeout=10)
@@ -179,7 +189,20 @@ class PolymarketClient:
         description: str,
         fee_share_bps: int = 10,
     ) -> BuilderCode:
-        """Register a builder code for fee sharing."""
+        """
+        Register a builder code for fee sharing.
+        
+        Note: The actual registration happens on Polymarket at:
+        https://polymarket.com/settings?tab=builder
+        
+        This method just registers it locally for tracking.
+        
+        Args:
+            code: bytes32 hex string, e.g. "0x00000000000000000000000000000001"
+            name: Human-readable builder name
+            description: What this builder does
+            fee_share_bps: Basis points earned on routed volume
+        """
         bc = BuilderCode(
             code=code,
             name=name,
@@ -198,7 +221,7 @@ class PolymarketClient:
         Route an order with builder code attribution.
         
         In paper trade mode, simulates execution.
-        In live mode, would submit to Polymarket CLOB.
+        In live mode, would submit to Polymarket CLOB with builderCode field.
         """
         # Attach builder code if provided
         if builder_code and builder_code in self.builder_codes:
@@ -225,7 +248,7 @@ class PolymarketClient:
             "size_usd": order.size,
             "price": order.price,
             "filled_at": datetime.utcnow().isoformat(),
-            "builder_code": order.builder_code,
+            "builder_code": order.builder_code,  # bytes32 hex
             "paper_trade": True,
             "fees_paid_usd": order.size * 0.002,  # 20 bps
         }
@@ -244,13 +267,29 @@ class PolymarketClient:
         return execution
     
     def _live_execute(self, order: OrderIntent) -> Dict:
-        """Placeholder for live execution via CLOB API."""
-        # TODO: Implement Polymarket CLOB signing + submission
-        # Requires API key + wallet integration
+        """
+        Placeholder for live execution via Polymarket CLOB.
+        
+        In production, submit to CLOB with builderCode as order field:
+        
+        Example (TypeScript pattern from Polymarket docs):
+            const response = await client.createAndPostOrder(
+              {
+                tokenID: "0x...",
+                price: 0.55,
+                size: 100,
+                side: Side.BUY,
+                builderCode: "0x0000...0001",  // bytes32 hex
+              },
+              { tickSize: "0.01", negRisk: false },
+            );
+        
+        The builderCode is serialized into the on-chain order as the `builder` field.
+        """
         return {
             "status": "PENDING",
             "order": asdict(order),
-            "note": "Live execution requires CLOB API key + wallet",
+            "note": "Live execution requires CLOB API key + wallet + builder code registration at polymarket.com/settings?tab=builder",
         }
     
     # ────────────────────────────── Portfolio ──────────────────────────────
@@ -285,6 +324,8 @@ class BuilderCodeRouter:
     - Market category alignment
     - Fee share optimization
     - Volume tracking for leaderboard
+    
+    Builder Leaderboard: https://builders.polymarket.com
     """
     
     def __init__(self, client: PolymarketClient):
@@ -305,8 +346,6 @@ class BuilderCodeRouter:
             return self.category_map.get(market.category)
         
         elif strategy == "max_fee_share":
-            # Route to builder code with highest fee share
-            # (incentivizes registering competitive codes)
             best = None
             best_bps = 0
             for code, bc in self.client.builder_codes.items():
@@ -316,7 +355,6 @@ class BuilderCodeRouter:
             return best
         
         elif strategy == "volume_leader":
-            # Route to builder with most volume (social proof)
             best = None
             best_vol = 0
             for code, bc in self.client.builder_codes.items():
@@ -344,7 +382,7 @@ class BuilderCodeRouter:
             outcome=outcome,
             size=size_usd,
             price=price,
-            builder_code=builder_code,
+            builder_code=builder_code,  # bytes32 hex string
         )
         
         return self.client.route_order(order, builder_code)