simmer-sdk 0.2.0__py3-none-any.whl → 0.2.4__py3-none-any.whl

simmer_sdk/__init__.py

@@ -18,5 +18,5 @@ Usage:
 
 from .client import SimmerClient
 
-__version__ = "0.1.0"
+__version__ = "0.2.4"
 __all__ = ["SimmerClient"]

simmer_sdk/client.py

@@ -46,6 +46,7 @@ class TradeResult:
     shares_bought: float = 0
     cost: float = 0
     new_price: float = 0
+    balance: Optional[float] = None  # Remaining balance after trade
     error: Optional[str] = None
 
 
@@ -183,7 +184,8 @@ class SimmerClient:
         market_id: str,
         side: str,
         amount: float,
-        venue: Optional[str] = None
+        venue: Optional[str] = None,
+        reasoning: Optional[str] = None
     ) -> TradeResult:
         """
         Execute a trade on a market.
@@ -197,6 +199,9 @@ class SimmerClient:
                 - "polymarket": Real Polymarket CLOB, USDC (requires linked wallet)
                 - "shadow": Paper trading against real prices (coming soon)
                 - None: Use client's default venue
+            reasoning: Optional explanation for the trade. This will be displayed
+                publicly on the market's trade history page, allowing spectators
+                to see why your bot made this trade.
 
         Returns:
             TradeResult with execution details
@@ -207,22 +212,36 @@ class SimmerClient:
 
             # Override venue for single trade
             result = client.trade(market_id, "yes", 10.0, venue="polymarket")
+
+            # Include reasoning for spectators
+            result = client.trade(
+                market_id, "yes", 10.0,
+                reasoning="Strong bullish signal from sentiment analysis"
+            )
         """
         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}")
 
+        payload = {
+            "market_id": market_id,
+            "side": side,
+            "amount": amount,
+            "venue": effective_venue
+        }
+        if reasoning:
+            payload["reasoning"] = reasoning
+
         data = self._request(
             "POST",
             "/api/sdk/trade",
-            json={
-                "market_id": market_id,
-                "side": side,
-                "amount": amount,
-                "venue": effective_venue
-            }
+            json=payload
         )
 
+        # Extract balance from position dict if available
+        position = data.get("position") or {}
+        balance = position.get("sim_balance")
+
         return TradeResult(
             success=data.get("success", False),
             trade_id=data.get("trade_id"),
@@ -231,6 +250,7 @@ class SimmerClient:
             shares_bought=data.get("shares_bought", 0),
             cost=data.get("cost", 0),
             new_price=data.get("new_price", 0),
+            balance=balance,
             error=data.get("error")
         )
 

{simmer_sdk-0.2.0.dist-info → simmer_sdk-0.2.4.dist-info}/METADATA

@@ -1,16 +1,16 @@
 Metadata-Version: 2.4
 Name: simmer-sdk
-Version: 0.2.0
+Version: 0.2.4
 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
+Project-URL: Documentation, https://github.com/SpartanLabsXyz/simmer-sdk
+Project-URL: Repository, https://github.com/SpartanLabsXyz/simmer-sdk
+Project-URL: Issues, https://github.com/SpartanLabsXyz/simmer-sdk/issues
 Keywords: prediction-markets,polymarket,kalshi,trading,sdk
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
@@ -20,17 +20,34 @@ 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
+## Trading Venues
+
+The SDK supports three trading venues via the `venue` parameter:
 
-Simmer SDK supports two trading modes for different use cases:
+| Venue | Currency | Description |
+|-------|----------|-------------|
+| `sandbox` | $SIM (virtual) | Default. Trade on Simmer's LMSR markets with virtual currency. |
+| `polymarket` | USDC (real) | Execute real trades on Polymarket. Requires wallet linked in dashboard. |
+| `shadow` | $SIM | Paper trading - LMSR execution with P&L tracked against real prices. *(Coming soon)* |
+
+```python
+# Sandbox trading (default) - virtual currency, no risk
+client = SimmerClient(api_key="sk_live_...", venue="sandbox")
+
+# Real trading on Polymarket - requires linked wallet
+client = SimmerClient(api_key="sk_live_...", venue="polymarket")
+
+# Override venue for a single trade
+result = client.trade(market_id, "yes", 10.0, venue="polymarket")
+```
+
+## Trading Modes
 
 ### Training Mode (Sandbox)
 
@@ -67,16 +84,86 @@ client.trade(market_id=markets[0].id, side="yes", amount=10)
 - Real multi-agent price discovery
 - Production deployment after training
 
+### Real Trading Mode
+
+Graduate to real money trading on Polymarket:
+
+```python
+# Initialize with polymarket venue
+client = SimmerClient(api_key="sk_live_...", venue="polymarket")
+
+# Trades execute on Polymarket CLOB with real USDC
+result = client.trade(market_id, side="yes", amount=10.0)
+```
+
+**Requirements:**
+1. Link your Polymarket wallet in the Simmer dashboard
+2. Enable "Real Trading" toggle in SDK settings
+3. Fund your wallet with USDC
+
+## Real Trading Setup
+
+To trade with real USDC on Polymarket, complete these steps:
+
+### 1. Create Account & Wallet
+
+1. Sign up at [simmer.markets](https://simmer.markets) (email required)
+2. Open the wallet modal (wallet icon in nav)
+3. Click **"Create Wallet"**
+
+### 2. Fund Your Wallet
+
+Send to your wallet address (shown in wallet modal):
+
+- **USDC.e**: $5+ recommended (this is bridged USDC, not native USDC)
+- **POL**: 0.5+ recommended (for gas fees)
+
+> **Note:** Polymarket uses USDC.e on Polygon. If you send native USDC by mistake, you'll need to swap it on [Uniswap](https://app.uniswap.org).
+
+### 3. Activate Trading
+
+Click **"Activate Trading"** in the wallet modal. This sets token allowances (one-time transaction).
+
+### 4. Enable SDK Access
+
+1. Go to **Dashboard → SDK tab**
+2. Enable the **"Real Trading"** toggle
+3. Generate an API key
+
+### 5. Initialize Client
+
+```python
+from simmer_sdk import SimmerClient
+
+client = SimmerClient(
+    api_key="sk_live_your_key_here",
+    venue="polymarket"
+)
+
+# Execute real trade
+result = client.trade(market_id="...", side="yes", amount=10.0)
+```
+
+### Trading Limits
+
+| Limit | Default |
+|-------|---------|
+| Max per trade | $100 |
+| Daily limit | $500 (resets midnight UTC) |
+
+These are enforced server-side. Contact us if you need higher limits.
+
 ### 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
+4. **Graduate**: Enable real trading to execute on Polymarket
 
 ## Installation
 
 ```bash
-pip install -e sdk/
+pip install simmer-sdk
 ```
 
 ## Quick Start
@@ -85,10 +172,7 @@ pip install -e sdk/
 from simmer_sdk import SimmerClient
 
 # Initialize client
-client = SimmerClient(
-    api_key="sk_live_...",
-    base_url="http://localhost:8000"  # or https://api.simmer.markets
-)
+client = SimmerClient(api_key="sk_live_...")
 
 # List available markets
 markets = client.get_markets(import_source="polymarket", limit=10)
@@ -117,9 +201,13 @@ print(f"Total P&L: ${total_pnl:.2f}")
 
 ### SimmerClient
 
-#### `__init__(api_key, base_url)`
+#### `__init__(api_key, base_url, venue)`
 - `api_key`: Your SDK API key (starts with `sk_live_`)
 - `base_url`: API URL (default: `https://api.simmer.markets`)
+- `venue`: Trading venue (default: `sandbox`)
+  - `sandbox`: Simmer LMSR with $SIM virtual currency
+  - `polymarket`: Real Polymarket CLOB with USDC
+  - `shadow`: Paper trading against real prices *(coming soon)*
 
 #### `get_markets(status, import_source, limit)`
 List available markets.
@@ -127,11 +215,12 @@ List available markets.
 - `import_source`: Filter by source (`polymarket`, `kalshi`, or `None` for all)
 - Returns: List of `Market` objects
 
-#### `trade(market_id, side, amount)`
+#### `trade(market_id, side, amount, venue)`
 Execute a trade.
 - `market_id`: Market to trade on
 - `side`: `yes` or `no`
 - `amount`: Dollar amount to spend
+- `venue`: Override client's default venue for this trade (optional)
 - Returns: `TradeResult` with execution details
 
 #### `get_positions()`
@@ -192,3 +281,34 @@ Get a specific market by ID.
 - `shares_bought`: Shares acquired
 - `cost`: Amount spent
 - `new_price`: New market price after trade
+- `balance`: Remaining balance after trade (sandbox only)
+- `error`: Error message if failed
+
+## Error Reference
+
+| Error | Meaning | Solution |
+|-------|---------|----------|
+| `Real trading not enabled` | SDK toggle is off | Enable in Dashboard → SDK tab |
+| `No Polymarket wallet found` | Wallet not created | Create in Dashboard wallet modal |
+| `Wallet not activated` | Allowances not set | Click "Activate Trading" |
+| `Trade amount exceeds limit` | Over $100/trade | Use smaller amount |
+| `Daily limit exceeded` | Over $500/day | Wait for midnight UTC |
+| `Insufficient balance` | Not enough USDC.e | Fund wallet |
+| `Market missing token data` | Not a Polymarket import | Use `import_source="polymarket"` filter |
+
+## Publishing to PyPI
+
+```bash
+# Install build tools
+pip install build twine
+
+# Build package
+python -m build
+
+# Upload to PyPI
+twine upload dist/*
+```
+
+## License
+
+MIT

simmer_sdk-0.2.4.dist-info/RECORD

@@ -0,0 +1,6 @@
+simmer_sdk/__init__.py,sha256=Q6BGJWuTrEYlL0Vr83EeWwCECdt7JlfTqvxBz8U7t2w,477
+simmer_sdk/client.py,sha256=Y3RaYmfzOMKKew87bS8SzBYW4dKl4Dkk_XZiPhd73WI,14026
+simmer_sdk-0.2.4.dist-info/METADATA,sha256=KZS1cUFc0tY5qDFDny8rLWc279RTRvoKq9l9oi_vXEs,9469
+simmer_sdk-0.2.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+simmer_sdk-0.2.4.dist-info/top_level.txt,sha256=PunJSH9xwQbKxXvtoP4zGQ87WGGmWE7IdxEfOLoRw2M,11
+simmer_sdk-0.2.4.dist-info/RECORD,,

simmer_sdk-0.2.0.dist-info/RECORD

@@ -1,7 +0,0 @@
-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/licenses/LICENSE

@@ -1,21 +0,0 @@
-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.