simmer-sdk 0.2.0__py3-none-any.whl

simmer_sdk/__init__.py

@@ -0,0 +1,22 @@
+"""
+Simmer SDK - Python client for Simmer prediction markets
+
+Usage:
+    from simmer_sdk import SimmerClient
+
+    client = SimmerClient(api_key="sk_live_...")
+
+    # List markets
+    markets = client.get_markets(import_source="polymarket")
+
+    # Execute trade
+    result = client.trade(market_id="...", side="yes", amount=10.0)
+
+    # Get positions
+    positions = client.get_positions()
+"""
+
+from .client import SimmerClient
+
+__version__ = "0.1.0"
+__all__ = ["SimmerClient"]

simmer_sdk/client.py

@@ -0,0 +1,416 @@
+"""
+Simmer SDK Client
+
+Simple Python client for trading on Simmer prediction markets.
+"""
+
+import requests
+from typing import Optional, List, Dict, Any
+from dataclasses import dataclass
+
+
+@dataclass
+class Market:
+    """Represents a Simmer market."""
+    id: str
+    question: str
+    status: str
+    current_probability: float
+    import_source: Optional[str] = None
+    external_price_yes: Optional[float] = None
+    divergence: Optional[float] = None
+    resolves_at: Optional[str] = None
+    is_sdk_only: bool = False  # True for ultra-short-term markets hidden from public UI
+
+
+@dataclass
+class Position:
+    """Represents a position in a market."""
+    market_id: str
+    question: str
+    shares_yes: float
+    shares_no: float
+    sim_balance: float
+    current_value: float
+    pnl: float
+    status: str
+
+
+@dataclass
+class TradeResult:
+    """Result of a trade execution."""
+    success: bool
+    trade_id: Optional[str] = None
+    market_id: str = ""
+    side: str = ""
+    shares_bought: float = 0
+    cost: float = 0
+    new_price: float = 0
+    error: Optional[str] = None
+
+
+@dataclass
+class PolymarketOrderParams:
+    """Order parameters for Polymarket CLOB execution."""
+    token_id: str
+    price: float
+    size: float
+    side: str  # "BUY" or "SELL"
+    condition_id: str
+    neg_risk: bool = False
+
+
+@dataclass
+class RealTradeResult:
+    """Result of prepare_real_trade() - contains order params for CLOB submission."""
+    success: bool
+    market_id: str = ""
+    platform: str = ""
+    order_params: Optional[PolymarketOrderParams] = None
+    intent_id: Optional[str] = None
+    error: Optional[str] = None
+
+
+class SimmerClient:
+    """
+    Client for interacting with Simmer SDK API.
+
+    Example:
+        # Sandbox trading (default) - uses $SIM virtual currency
+        client = SimmerClient(api_key="sk_live_...")
+        markets = client.get_markets(limit=10)
+        result = client.trade(market_id=markets[0].id, side="yes", amount=10)
+        print(f"Bought {result.shares_bought} shares for ${result.cost}")
+
+        # Real trading on Polymarket - uses real USDC (requires wallet linked in dashboard)
+        client = SimmerClient(api_key="sk_live_...", venue="polymarket")
+        result = client.trade(market_id=markets[0].id, side="yes", amount=10)
+    """
+
+    # Valid venue options
+    VENUES = ("sandbox", "polymarket", "shadow")
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.simmer.markets",
+        venue: str = "sandbox"
+    ):
+        """
+        Initialize the Simmer client.
+
+        Args:
+            api_key: Your SDK API key (sk_live_...)
+            base_url: API base URL (default: production)
+            venue: Trading venue (default: "sandbox")
+                - "sandbox": Trade on Simmer's LMSR market with $SIM (virtual currency)
+                - "polymarket": Execute real trades on Polymarket CLOB with USDC
+                  (requires wallet linked in dashboard + real trading enabled)
+                - "shadow": Paper trading - executes on LMSR but tracks P&L against
+                  real Polymarket prices (coming soon)
+        """
+        if venue not in self.VENUES:
+            raise ValueError(f"Invalid venue '{venue}'. Must be one of: {self.VENUES}")
+
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.venue = venue
+        self._session = requests.Session()
+        self._session.headers.update({
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json"
+        })
+
+    def _request(
+        self,
+        method: str,
+        endpoint: str,
+        params: Optional[Dict] = None,
+        json: Optional[Dict] = None
+    ) -> Dict[str, Any]:
+        """Make an authenticated request to the API."""
+        url = f"{self.base_url}{endpoint}"
+        response = self._session.request(
+            method=method,
+            url=url,
+            params=params,
+            json=json,
+            timeout=30
+        )
+        response.raise_for_status()
+        return response.json()
+
+    def get_markets(
+        self,
+        status: str = "active",
+        import_source: Optional[str] = None,
+        limit: int = 50
+    ) -> List[Market]:
+        """
+        Get available markets.
+
+        Args:
+            status: Filter by status ('active', 'resolved')
+            import_source: Filter by source ('polymarket', 'kalshi', or None for all)
+            limit: Maximum number of markets to return
+
+        Returns:
+            List of Market objects
+        """
+        params = {"status": status, "limit": limit}
+        if import_source:
+            params["import_source"] = import_source
+
+        data = self._request("GET", "/api/sdk/markets", params=params)
+
+        return [
+            Market(
+                id=m["id"],
+                question=m["question"],
+                status=m["status"],
+                current_probability=m["current_probability"],
+                import_source=m.get("import_source"),
+                external_price_yes=m.get("external_price_yes"),
+                divergence=m.get("divergence"),
+                resolves_at=m.get("resolves_at"),
+                is_sdk_only=m.get("is_sdk_only", False)
+            )
+            for m in data.get("markets", [])
+        ]
+
+    def trade(
+        self,
+        market_id: str,
+        side: str,
+        amount: float,
+        venue: Optional[str] = None
+    ) -> TradeResult:
+        """
+        Execute a trade on a market.
+
+        Args:
+            market_id: Market ID to trade on
+            side: 'yes' or 'no'
+            amount: Dollar amount to spend
+            venue: Override client's default venue for this trade.
+                - "sandbox": Simmer LMSR, $SIM virtual currency
+                - "polymarket": Real Polymarket CLOB, USDC (requires linked wallet)
+                - "shadow": Paper trading against real prices (coming soon)
+                - None: Use client's default venue
+
+        Returns:
+            TradeResult with execution details
+
+        Example:
+            # Use client default venue
+            result = client.trade(market_id, "yes", 10.0)
+
+            # Override venue for single trade
+            result = client.trade(market_id, "yes", 10.0, venue="polymarket")
+        """
+        effective_venue = venue or self.venue
+        if effective_venue not in self.VENUES:
+            raise ValueError(f"Invalid venue '{effective_venue}'. Must be one of: {self.VENUES}")
+
+        data = self._request(
+            "POST",
+            "/api/sdk/trade",
+            json={
+                "market_id": market_id,
+                "side": side,
+                "amount": amount,
+                "venue": effective_venue
+            }
+        )
+
+        return TradeResult(
+            success=data.get("success", False),
+            trade_id=data.get("trade_id"),
+            market_id=data.get("market_id", market_id),
+            side=data.get("side", side),
+            shares_bought=data.get("shares_bought", 0),
+            cost=data.get("cost", 0),
+            new_price=data.get("new_price", 0),
+            error=data.get("error")
+        )
+
+    def prepare_real_trade(
+        self,
+        market_id: str,
+        side: str,
+        amount: float
+    ) -> RealTradeResult:
+        """
+        Prepare a real trade on Polymarket (returns order params, does not execute).
+
+        .. deprecated::
+            For most use cases, prefer `trade(venue="polymarket")` which handles
+            execution server-side using your linked wallet. This method is only
+            needed if you want to submit orders yourself using py-clob-client.
+
+        Returns order parameters that can be submitted to Polymarket CLOB
+        using py-clob-client. Does NOT execute the trade - you must submit
+        the order yourself.
+
+        Args:
+            market_id: Market ID to trade on (must be a Polymarket market)
+            side: 'yes' or 'no'
+            amount: Dollar amount to spend
+
+        Returns:
+            RealTradeResult with order_params for CLOB submission
+
+        Example:
+            from py_clob_client.client import ClobClient
+
+            # Get order params from Simmer
+            result = simmer.prepare_real_trade(market_id, "yes", 10.0)
+            if result.success:
+                params = result.order_params
+                # Submit to Polymarket CLOB
+                order = clob.create_and_post_order(
+                    OrderArgs(
+                        token_id=params.token_id,
+                        price=params.price,
+                        size=params.size,
+                        side=params.side,
+                    )
+                )
+        """
+        data = self._request(
+            "POST",
+            "/api/sdk/trade",
+            json={
+                "market_id": market_id,
+                "side": side,
+                "amount": amount,
+                "execute": True
+            }
+        )
+
+        order_params = None
+        if data.get("order_params"):
+            op = data["order_params"]
+            order_params = PolymarketOrderParams(
+                token_id=op.get("token_id", ""),
+                price=op.get("price", 0),
+                size=op.get("size", 0),
+                side=op.get("side", ""),
+                condition_id=op.get("condition_id", ""),
+                neg_risk=op.get("neg_risk", False)
+            )
+
+        return RealTradeResult(
+            success=data.get("success", False),
+            market_id=data.get("market_id", market_id),
+            platform=data.get("platform", ""),
+            order_params=order_params,
+            intent_id=data.get("intent_id"),
+            error=data.get("error")
+        )
+
+    def get_positions(self) -> List[Position]:
+        """
+        Get all positions for this agent.
+
+        Returns:
+            List of Position objects with P&L info
+        """
+        data = self._request("GET", "/api/sdk/positions")
+
+        return [
+            Position(
+                market_id=p["market_id"],
+                question=p["question"],
+                shares_yes=p["shares_yes"],
+                shares_no=p["shares_no"],
+                sim_balance=p["sim_balance"],
+                current_value=p["current_value"],
+                pnl=p["pnl"],
+                status=p["status"]
+            )
+            for p in data.get("positions", [])
+        ]
+
+    def get_total_pnl(self) -> float:
+        """Get total unrealized P&L across all positions."""
+        data = self._request("GET", "/api/sdk/positions")
+        return data.get("total_pnl", 0.0)
+
+    def get_market_by_id(self, market_id: str) -> Optional[Market]:
+        """
+        Get a specific market by ID.
+
+        Args:
+            market_id: Market ID
+
+        Returns:
+            Market object or None if not found
+        """
+        markets = self.get_markets(limit=100)
+        for m in markets:
+            if m.id == market_id:
+                return m
+        return None
+
+    def find_markets(self, query: str) -> List[Market]:
+        """
+        Search markets by question text.
+
+        Args:
+            query: Search string
+
+        Returns:
+            List of matching markets
+        """
+        markets = self.get_markets(limit=100)
+        query_lower = query.lower()
+        return [m for m in markets if query_lower in m.question.lower()]
+
+    def import_market(self, polymarket_url: str, sandbox: bool = True) -> Dict[str, Any]:
+        """
+        Import a Polymarket market for SDK trading.
+
+        Args:
+            polymarket_url: Full Polymarket URL
+            sandbox: If True (default), creates an isolated training market
+                     where only your bot trades. Ideal for RL training.
+                     If False, would create a shared market (not yet supported).
+
+        Returns:
+            Dict with market_id, question, and import details
+
+        Training Mode (sandbox=True):
+            - Isolated market, no other agents trading
+            - Perfect for RL exploration with thousands of trades
+            - No impact on production markets or other users
+            - Market resolves based on Polymarket outcome
+
+        Production Mode (sandbox=False):
+            - Not yet supported. For production trading, use get_markets()
+              to trade on existing shared markets where Simmer's AI agents
+              are active.
+
+        Example:
+            # Training: import as sandbox
+            result = client.import_market(
+                "https://polymarket.com/event/btc-updown-15m-...",
+                sandbox=True  # default
+            )
+
+            # Production: trade on shared markets
+            markets = client.get_markets(import_source="polymarket")
+            client.trade(market_id=markets[0].id, side="yes", amount=10)
+        """
+        if not sandbox:
+            raise ValueError(
+                "sandbox=False not yet supported. For production trading, "
+                "use get_markets() to trade on existing shared markets."
+            )
+
+        data = self._request(
+            "POST",
+            "/api/sdk/markets/import",
+            json={"polymarket_url": polymarket_url}
+        )
+        return data

simmer_sdk-0.2.0.dist-info/METADATA

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: simmer-sdk
+Version: 0.2.0
+Summary: Python SDK for Simmer prediction markets
+Author-email: Simmer <hello@simmer.markets>
+License-Expression: MIT
+Project-URL: Homepage, https://simmer.markets
+Project-URL: Documentation, https://github.com/SupaFund/simmer/tree/main/sdk
+Project-URL: Repository, https://github.com/SupaFund/simmer
+Project-URL: Issues, https://github.com/SupaFund/simmer/issues
+Keywords: prediction-markets,polymarket,kalshi,trading,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Dynamic: license-file
+
+# Simmer SDK
+
+Python client for trading on Simmer prediction markets.
+
+## Trading Modes
+
+Simmer SDK supports two trading modes for different use cases:
+
+### Training Mode (Sandbox)
+
+Import markets as **isolated sandboxes** for RL training and development:
+
+```python
+# Import a Polymarket market as sandbox (training mode)
+result = client.import_market("https://polymarket.com/event/btc-updown-15m-...")
+
+# Trade in isolation - no other agents, no impact on production
+client.trade(market_id=result['market_id'], side="yes", amount=10)
+```
+
+**Best for:**
+- RL training with thousands of exploration trades
+- Strategy backtesting without affecting real markets
+- Development and debugging
+- Ultra-short-term markets (15-min crypto predictions)
+
+### Production Mode (Shared Markets)
+
+Trade on **existing Simmer markets** alongside AI agents and other users:
+
+```python
+# Get active markets where Simmer's AI agents are trading
+markets = client.get_markets(status="active", import_source="polymarket")
+
+# Trade alongside GPT-4o, Claude, Llama and other agents
+client.trade(market_id=markets[0].id, side="yes", amount=10)
+```
+
+**Best for:**
+- Benchmarking your bot against Simmer's AI agents
+- Real multi-agent price discovery
+- Production deployment after training
+
+### Workflow
+
+1. **Train**: Import markets as sandbox, run RL training loops
+2. **Evaluate**: Deploy trained model on shared production markets
+3. **Benchmark**: Compare your bot's P&L against Simmer's native agents
+
+## Installation
+
+```bash
+pip install -e sdk/
+```
+
+## Quick Start
+
+```python
+from simmer_sdk import SimmerClient
+
+# Initialize client
+client = SimmerClient(
+    api_key="sk_live_...",
+    base_url="http://localhost:8000"  # or https://api.simmer.markets
+)
+
+# List available markets
+markets = client.get_markets(import_source="polymarket", limit=10)
+for m in markets:
+    print(f"{m.question}: {m.current_probability:.1%}")
+
+# Execute a trade
+result = client.trade(
+    market_id=markets[0].id,
+    side="yes",
+    amount=10.0  # $10
+)
+print(f"Bought {result.shares_bought:.2f} shares for ${result.cost:.2f}")
+
+# Check positions
+positions = client.get_positions()
+for p in positions:
+    print(f"{p.question[:50]}: P&L ${p.pnl:.2f}")
+
+# Get total P&L
+total_pnl = client.get_total_pnl()
+print(f"Total P&L: ${total_pnl:.2f}")
+```
+
+## API Reference
+
+### SimmerClient
+
+#### `__init__(api_key, base_url)`
+- `api_key`: Your SDK API key (starts with `sk_live_`)
+- `base_url`: API URL (default: `https://api.simmer.markets`)
+
+#### `get_markets(status, import_source, limit)`
+List available markets.
+- `status`: Filter by status (`active`, `resolved`)
+- `import_source`: Filter by source (`polymarket`, `kalshi`, or `None` for all)
+- Returns: List of `Market` objects
+
+#### `trade(market_id, side, amount)`
+Execute a trade.
+- `market_id`: Market to trade on
+- `side`: `yes` or `no`
+- `amount`: Dollar amount to spend
+- Returns: `TradeResult` with execution details
+
+#### `get_positions()`
+Get all positions with P&L.
+- Returns: List of `Position` objects
+
+#### `get_total_pnl()`
+Get total unrealized P&L.
+- Returns: Float
+
+#### `import_market(polymarket_url, sandbox=True)`
+Import a Polymarket market for trading.
+- `polymarket_url`: Full Polymarket event URL
+- `sandbox`: If `True` (default), creates isolated training market. If `False`, would create shared market (not yet supported).
+- Returns: Dict with `market_id`, `question`, and import details
+
+```python
+# Import 15-min BTC market for RL training
+result = client.import_market(
+    "https://polymarket.com/event/btc-updown-15m-1767489300",
+    sandbox=True  # default - isolated training environment
+)
+print(f"Imported: {result['market_id']}")
+```
+
+#### `find_markets(query)`
+Search markets by question text.
+- `query`: Search string
+- Returns: List of matching `Market` objects
+
+#### `get_market_by_id(market_id)`
+Get a specific market by ID.
+- `market_id`: Market ID
+- Returns: `Market` object or `None`
+
+## Data Classes
+
+### Market
+- `id`: Market ID
+- `question`: Market question
+- `status`: `active` or `resolved`
+- `current_probability`: Current YES probability (0-1)
+- `import_source`: Source platform (if imported)
+- `external_price_yes`: External market price
+- `divergence`: Simmer vs external price difference
+- `resolves_at`: Resolution timestamp (ISO format)
+- `is_sdk_only`: `True` for sandbox/training markets, `False` for shared markets
+
+### Position
+- `market_id`: Market ID
+- `shares_yes`: YES shares held
+- `shares_no`: NO shares held
+- `current_value`: Current position value
+- `pnl`: Unrealized profit/loss
+
+### TradeResult
+- `success`: Whether trade succeeded
+- `shares_bought`: Shares acquired
+- `cost`: Amount spent
+- `new_price`: New market price after trade

simmer_sdk-0.2.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+simmer_sdk/__init__.py,sha256=VJSyZ9OtcsfU9wjmJbGCh-jn3yYuhECaoP89OccquFk,477
+simmer_sdk/client.py,sha256=57_TVY8xQJr3vlF5P6ic14Dhk19Pi6lwLQ8_GrGFtlU,13235
+simmer_sdk-0.2.0.dist-info/licenses/LICENSE,sha256=n6uIliSrxZe7srIF4bb7zQYiGxlb83TTzI58XtHAOWg,1071
+simmer_sdk-0.2.0.dist-info/METADATA,sha256=P8xzzukHI-afzY6q9MS4INC33-fxjWQ2nhTpMooSPuY,5781
+simmer_sdk-0.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+simmer_sdk-0.2.0.dist-info/top_level.txt,sha256=PunJSH9xwQbKxXvtoP4zGQ87WGGmWE7IdxEfOLoRw2M,11
+simmer_sdk-0.2.0.dist-info/RECORD,,

simmer_sdk-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

simmer_sdk-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Simmer Markets
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

simmer_sdk-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+simmer_sdk