Metadata-Version: 2.2
Name: simmer-sdk
Version: 0.27.1
Summary: Python SDK for trading prediction markets with AI agents - powers installable trading skills across agent runtimes
Author-email: Simmer <hello@simmer.markets>
Project-URL: Homepage, https://simmer.markets
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
Project-URL: Skills, https://github.com/SpartanLabsXyz/simmer-sdk/tree/main/skills
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: solders<0.28.0,>=0.27.1
Requires-Dist: base58>=2.1.1
Requires-Dist: eth-account>=0.13.0
Requires-Dist: py-order-utils>=0.3.0
Requires-Dist: py-clob-client<1.0.0,>=0.30.0
Requires-Dist: py-clob-client-v2<2.0.0,>=1.2.0
Requires-Dist: polynode<0.16.0,>=0.15.1
Provides-Extra: ows
Requires-Dist: open-wallet-standard<2.0.0,>=1.3.0; extra == "ows"
Provides-Extra: hyperliquid
Requires-Dist: hyperliquid-python-sdk<1.0.0,>=0.24.0; extra == "hyperliquid"
Provides-Extra: backtest
Requires-Dist: duckdb>=0.10.0; extra == "backtest"
Requires-Dist: fastapi>=0.110.0; extra == "backtest"
Requires-Dist: uvicorn>=0.27.0; extra == "backtest"
Requires-Dist: pytz>=2023.3; extra == "backtest"

# Simmer SDK

[![PyPI version](https://badge.fury.io/py/simmer-sdk.svg)](https://pypi.org/project/simmer-sdk/)

Simmer is the leading prediction market harness for AI agents. Autonomous agents place trades on venues like Polymarket, Kalshi and Hyperliquid through a unified API — with self-custody wallets, safety rails, and smart context.

- **Prediction market harness for AI agents** — designed for autonomous agents, with full support for manual trading too. Users install trading skills and let their agents trade autonomously.
- **$SIM simulated trading** — paper-trade with virtual currency before risking real funds.
- **Multi-venue** — trade Polymarket, Kalshi and Hyperliquid through one unified API.

## What's in this repo

| | |
|--|--|
| [`skills/`](skills/) | 28 skills an agent installs and runs. `skills/simmer/SKILL.md` is the canonical source for [simmer.markets/skill.md](https://simmer.markets/skill.md). |
| [`mcp/`](mcp/) | MCP server, published to npm as [`simmer-mcp`](https://www.npmjs.com/package/simmer-mcp). |
| [`simmer_sdk/`](simmer_sdk/) | Python SDK, published to PyPI as [`simmer-sdk`](https://pypi.org/project/simmer-sdk/). |

## Installation

```bash
pip install simmer-sdk
```

Get your API key from [simmer.markets/dashboard](https://simmer.markets/dashboard).

## Quick Start

### OpenClaw Skill Pattern (recommended)

Most Simmer users run trading skills inside [OpenClaw](https://openclaw.ai). The standard pattern uses a lazy singleton client and reads config from environment variables:

```python
import os
from simmer_sdk import SimmerClient

SKILL_SLUG = "my-skill-slug"   # Must match your ClawHub slug
TRADE_SOURCE = f"sdk:{SKILL_SLUG}"

_client = None
def get_client(live: bool = False):
    global _client
    if _client is None:
        venue = os.environ.get("TRADING_VENUE", "sim")
        # `live` controls paper vs real execution and is a constructor arg, not a
        # per-trade flag. live=False => paper preview (no real order placed).
        _client = SimmerClient(api_key=os.environ["SIMMER_API_KEY"], venue=venue, live=live)
    return _client

def run(live: bool = False):
    client = get_client(live)

    # Find markets. Unfiltered browse is windowed to the newest ~1,000 active
    # markets — filter with sort="volume", q="...", or tags="..." to reach the rest.
    markets = client.get_markets(status="active", sort="volume", limit=20)

    # Get trading context (safeguards, slippage, conflict detection)
    ctx = client.get_market_context(markets[0].id)

    # Trade — always tag source and skill_slug
    if not ctx.conflict and ctx.recommended_action != "hold":
        result = client.trade(
            market_id=markets[0].id,
            side="yes",
            amount=10.0,
            source=TRADE_SOURCE,
            skill_slug=SKILL_SLUG,
            reasoning="Signal detected — buying YES"
        )
        print(f"{'PAPER: ' if not live else ''}Bought {result.shares_bought:.2f} shares")

if __name__ == "__main__":
    import sys
    run(live="--live" in sys.argv)
```

Set environment variables:
```bash
export SIMMER_API_KEY=sk_live_...
export TRADING_VENUE=sim            # sim | polymarket | kalshi
export WALLET_PRIVATE_KEY=0x...    # Required for Polymarket self-custody
```

> **Default to dry-run.** Skills should require `--live` to execute real trades. Paper-trade with `$SIM` until your edge is consistent, then graduate to real money.

### Raw SDK

For developers building custom integrations:

```python
from simmer_sdk import SimmerClient

client = SimmerClient(api_key="sk_live_...")

# Browse markets (unfiltered browse is windowed to the newest ~1,000 active
# markets — use sort="volume", q="...", or tags="..." for discovery)
markets = client.get_markets(sort="volume", limit=10)
for m in markets:
    print(f"{m.question}: {m.current_probability:.1%}")

# Trade with $SIM (virtual currency)
result = client.trade(market_id=markets[0].id, side="yes", amount=10.0)
print(f"Bought {result.shares_bought:.2f} shares for ${result.cost:.2f}")

# Check P&L
for p in client.get_positions():
    print(f"{p.question[:50]}: P&L ${p.pnl:.2f}")
```

## Trading Venues

| Venue | Currency | Description |
|-------|----------|-------------|
| `sim` | $SIM (virtual) | Default. Paper trading on Simmer's LMSR markets. |
| `polymarket` | USDC.e (real) | Real trades on Polymarket (Polygon). Requires `WALLET_PRIVATE_KEY`. |
| `kalshi` | USDC (real) | Real trades on Kalshi. Requires Pro plan. |

```python
# Paper trading (default)
client = SimmerClient(api_key="sk_live_...", venue="sim")

# Real trading on Polymarket
client = SimmerClient(api_key="sk_live_...", venue="polymarket", live=True)

# Read-only validation/status client. Does not process constructor-time risk exits.
client = SimmerClient.readonly(api_key="sk_live_...", venue="polymarket")

# Override venue for a single trade
client.trade(market_id, side="yes", amount=10.0, venue="polymarket")
```

`TRADING_VENUE` environment variable is read at client init — OpenClaw skills use this to select venue at startup without code changes.

> **Constructor side effect:** for live Polymarket clients with `WALLET_PRIVATE_KEY` or `OWS_WALLET`, regular `SimmerClient(...)` construction checks pending risk alerts and may submit stop-loss/take-profit exit orders. This is intentional for self-custody safety: Simmer's server cannot sign those exits. Pass `process_risk_alerts=False` to skip this constructor check for dry runs. Use `SimmerClient.readonly(...)` for API-key validation, preflight/status checks, and other non-trading paths.

> **Spread caveat:** $SIM fills instantly (AMM, no spread). Real venues have orderbook spreads of 2–5%. Target edges >5% in $SIM before graduating to real money.

> **Polymarket order types:** omit `order_type` for the SDK/server smart default: buys use `FAK` (fill what is available immediately), sells use `GTC` (rest on the book to improve fill rate on thin books). For structurally thin markets or maker-style limit entries, pass `order_type="GTC"` and an explicit `price`.

### Polymarket Protocol V2 orders

Protocol V2 markets use PositionManager positions and the ExchangeV3 signing
domain, version `"3"`. This is separate from the April V2 order format selected
by `SIMMER_POLYMARKET_EXCHANGE_VERSION`. Raw-key EOA signing and both raw-key
and OWS deposit-wallet signing support these markets. OWS EOA signing remains
legacy-only and rejects Protocol V2 metadata.

`trade()` reads the selected outcome's protocol from the Simmer market detail
response. The server must return these fields on market detail and discovery
responses before routing Protocol V2 markets through this SDK:

| Field | Current markets | Protocol V2 markets |
| --- | --- | --- |
| `polymarket_protocol_version` | Absent or `"v1"` | `"v2"` |
| `polymarket_position_id` | Absent or null | YES position ID as a decimal uint256 string |
| `polymarket_no_position_id` | Absent or null | NO position ID as a decimal uint256 string |
| `polymarket_neg_risk` | Existing boolean | `true` for the neg-risk module, `false` for binary |

For current markets, `polymarket_token_id` and `polymarket_no_token_id` remain
the signing IDs. For Protocol V2, the position ID becomes the signed `tokenId`;
legacy token IDs are not required. The server must obtain the protocol and IDs
from authoritative market metadata. The SDK does not infer them from dates,
IDs, or the neg-risk flag. Unknown or null protocol markers and incomplete V2
metadata raise `ValueError`. The SDK caches market detail for the client session.

`Market.polymarket_yes_protocol` and `Market.polymarket_no_protocol` expose
validated `MarketProtocol` values. Direct signing callers can pass
`market_protocol=MarketProtocol("v2", position_id)` to `build_and_sign_order`,
importing `MarketProtocol` from `simmer_sdk.polymarket_contracts`. The frozen
value requires a position ID for V2 and forbids one for V1. Both signing paths
consume the same value. `build_and_sign_order` rejects Protocol V2 with the legacy exchange flag.

`client.ensure_approvals(protocol_v2=True)` checks the existing approvals plus
pUSD allowance and PositionManager operator approval for ExchangeV3.
`client.check_approvals(protocol_v2=True)` requests
`GET /api/polymarket/allowances/{address}?protocol_v2=1`. The server must return
boolean entries in `allowances` named `pusd_<exchange_address>` and
`position_manager_<exchange_address>`, using the full lowercase ExchangeV3
address:

- `pusd_0xe3333700ca9d93003f00f0f71f8515005f6c00aa` is true when pUSD
  `allowance(owner, ExchangeV3) >= (2**256 - 1) // 2`, PolyNode's readiness threshold.
- `position_manager_0xe3333700ca9d93003f00f0f71f8515005f6c00aa` is the result of
  PositionManager `isApprovedForAll(owner, ExchangeV3)`.

Missing entries mean unapproved, even if an older server reports `all_set=true`.

With `protocol_v2=True` and a locally configured wallet, default-address
`check_approvals()`, `ensure_approvals()`, and `set_approvals()` require activation
status from `GET /api/sdk/agents/me`:

- If `per_agent_wallet_address` is present, `per_agent_dw_active` must be a boolean.
  When true, approval checks use `per_agent_deposit_wallet_address`.
- Otherwise, `wallet_uses_deposit_wallet` must be a boolean.
  When true, approval checks use `deposit_wallet_address`.

When the applicable flag is false, approval checks use the configured EOA address.
These calls fail closed: missing, null, or non-boolean activation status raises,
and identity lookup errors propagate. An active DW without its address also
causes approval checks to raise. Passing an explicit `address` to
`check_approvals()` skips activation discovery and checks that address directly,
including with `protocol_v2=True`.

For an EOA, `client.set_approvals(protocol_v2=True)` can submit the missing
approvals. Deposit-wallet users must use the dashboard's **Activate Trading**
flow, whose server implementation must also grant both approvals from the
deposit wallet. The SDK does not submit EOA approvals for a deposit wallet.
The default approval methods retain their existing scope. Managed wallets
without a local address cannot confirm Protocol V2 readiness through this SDK.

### Paper trading on real venues

Pass `live=False` to simulate trades with real market prices — no wallet or USDC required. For Polymarket, fills model the CLOB bid-ask spread for realistic P&L. Resolved markets auto-settle (winning shares pay $1, losers $0).

```python
client = SimmerClient(
    api_key="sk_live_...",
    venue="polymarket",
    live=False,                # Simulate fills, no real money
    starting_balance=10_000.0  # Virtual capital (default: 10,000)
)

result = client.trade(market_id=markets[0].id, side="yes", amount=50.0,
                      reasoning="Testing strategy")
print(f"Filled {result.shares_bought:.2f} shares (simulated)")

# Portfolio summary
summary = client.get_paper_summary()
print(f"Balance: ${summary['balance']:.2f}, P&L: ${summary['total_pnl']:.2f}")
```

**Graduation path:** `sim` (instant fills, no spread) → `polymarket` + `live=False` (real prices, spread modeled) → `polymarket` live (real USDC).

## Backtesting

The three modes above are all *live-forward*. To test a strategy on **historical** data before risking capital, backtest the skill bundle:

```bash
pip install 'simmer-sdk[backtest]'

# Try it offline — bundled 10-market demo slice, no data download:
simmer backtest --demo

# Backtest your own skill over a window — the tape is fetched + cached for you:
simmer backtest ./my-skill --entrypoint run.py \
    --t0 2026-03-01 --t1 2026-03-08 --cadence 12h --out report.json

# ...or by duration, and with your own local slice (BYO):
simmer backtest ./my-skill --entrypoint run.py --window 30d
simmer backtest ./my-skill --entrypoint run.py --tape ./slice --t0 2026-03-01 --t1 2026-03-08

# Narrow the fetched slice to a topic — matches question OR slug, applied
# before the volume cap, so a niche topic isn't crowded out by high-volume noise:
simmer backtest ./weather-skill --entrypoint run.py \
    --t0 2026-03-01 --t1 2026-03-08 --q temperature
```

The engine replays your **unmodified** skill against a frozen, look-ahead-safe
replay server (one subprocess per tick) and reports pnl, hit rate, max drawdown,
trades, baselines (buy-and-hold-YES / random), realism gaps, and a reproducible
`config_hash`. Programmatic equivalent:

```python
from simmer_sdk.backtest import run_backtest

# tape omitted => the window slice is fetched from the tape service and cached.
report = run_backtest("./my-skill", entrypoint="run.py",
                      t0="2026-03-01", t1="2026-03-08", cadence="12h")
print(report["summary"]["pnl"], report["summary"]["hit_rate"])
```

> Backtests use trade-tape prices (no orderbook), so they model decision quality,
> not execution realism — every report lists its `realism_gaps`. The window slice
> is fetched from Simmer's tape service and cached under `~/.simmer/tapes/`; pass
> `--tape <dir>` to use your own. Data coverage currently ends ~2026-05-05.

## Key Methods

| Method | Description |
|--------|-------------|
| `get_markets()` | List markets (filter by status, source, venue, tags, keyword) |
| `trade()` | Buy or sell shares |
| `get_positions()` | All positions with P&L |
| `get_held_markets()` | Map of market_id → source tags for held positions |
| `check_conflict()` | Check if another skill holds a position on a market |
| `get_open_orders()` | Open GTC/GTD orders on the CLOB |
| `maker_rewards_status(market_id)` | Polymarket liquidity-rewards config: max spread, daily pool, eligibility |
| `get_portfolio(venue="all")` | Portfolio summary with per-venue buckets (sim/polymarket/kalshi/total) |
| `get_market_context(market_id, venue="all")` | Per-venue positions + trading safeguards |
| `get_trades(venue="all")` | Trade history merged across venues, each row tagged with venue |
| `get_price_history()` | Price history for trend detection |
| `import_market()` | Import a Polymarket market by URL |
| `import_kalshi_market()` | Import a Kalshi market by URL |
| `list_importable_markets()` | Discover markets available to import |
| `check_market_exists()` | Check if a market is already on Simmer (no quota cost) |
| `set_monitor()` | Set stop-loss / take-profit on a position |
| `cancel_order()` | Cancel a single open order by ID |
| `cancel_market_orders()` | Cancel all open orders on a market (optional side filter) |
| `cancel_all_orders()` | Cancel all open orders across all markets |
| `create_alert()` | Price alerts with optional webhook |
| `register_webhook()` | Push notifications for trades, resolutions, price moves |
| `redeem()` | Redeem a specific winning Polymarket position |
| `auto_redeem()` | Scan all positions and redeem any winning ones automatically |
| `get_paper_summary()` | Paper mode portfolio summary (balance, P&L, positions) |
| `get_settings()` / `update_settings()` | Configure trade limits and notifications |
| `link_wallet()` | Link external EVM wallet for Polymarket |
| `set_approvals()` | Set Polymarket token approvals |
| `activate_polymarket_dw(agent_id=None)` | Set Polymarket Deposit Wallet on-chain CLOB approvals — user-primary (no arg) or per-agent (`agent_id=...`). See note. |
| `readonly()` | Constructor for validation/status clients that must not process constructor-time risk exits or submit orders |
| `troubleshoot()` | Look up any error and get a fix (no auth required) |

> **Per-agent wallets (Elite tier):** activating a per-agent (Elite dedicated) wallet takes **two** calls, approvals first: `activate_polymarket_dw(agent_id=...)` sets the deposit wallet's on-chain CLOB approvals, then `update_agent_wallet_creds(...)` caches the CLOB creds. OWS callers use `update_agent_wallet_creds(ows_wallet_name="...")`; raw-key callers with `WALLET_PRIVATE_KEY` use `update_agent_wallet_creds(agent_id="...")`. **Both approvals and cached creds are required before trading** — caching creds alone does not set on-chain allowances, so trades fail at the relayer with "insufficient allowance". See the `simmer-wallet-setup` skill for the full flow. (`set_approvals()` is the user-primary EOA path and is a no-op for per-agent deposit wallets.)

**Tip — don't pre-round prices.** simmer-sdk ≥ 0.17.1 automatically rounds the price to each Polymarket market's tick grid. Pass your raw computed price to `client.trade(..., price=p)` and the SDK handles the rest. Pre-rounding with a hardcoded tick (e.g. `round(price, 3)`) will silently produce wrong values for markets at different tick sizes.

**Error handling:** All SDK 4xx responses include a `fix` field with actionable instructions when the error matches a known pattern. You can also call `POST /api/sdk/troubleshoot` with `{"error_text": "..."}` to look up any error.

Full API reference with parameters, examples, and error codes: **[simmer.markets/docs.md](https://simmer.markets/docs.md)**

## Skill Builder Utilities

The SDK ships two helper modules for skill authors. Prefer these over rolling your own — they encode patterns from top traders and external research.

### Position sizing — `simmer_sdk.sizing`

Kelly Criterion + Expected Value sizing for binary prediction markets. Default is fractional Kelly (0.25x) with an EV gate, so trades below your edge threshold return `0.0` and the skill can simply skip them.

```python
from simmer_sdk import SimmerClient
from simmer_sdk.sizing import size_position

client = SimmerClient()
bankroll = client.get_portfolio()["available_balance"]

amount = size_position(
    p_win=0.70,         # your model's probability
    market_price=0.55,  # current YES price
    bankroll=bankroll,
    min_ev=0.03,        # skip trades with edge < 3%
)
if amount > 0:
    client.trade(market_id=..., side="yes",
                 amount=amount, reasoning="Kelly: 70% vs 55%, +15% edge")
```

| Function | Purpose |
|----------|---------|
| `size_position(p_win, market_price, bankroll, method=, kelly_multiplier=, min_ev=, max_fraction=)` | Returns dollar amount to trade. `0.0` when edge ≤ `min_ev`, Kelly is negative, or inputs are invalid. |
| `kelly_fraction(p_win, market_price)` | Raw Kelly fraction `(p - c) / (1 - c)`. |
| `expected_value(p_win, market_price)` | Edge per share (`p_win - market_price`). |
| `SIZING_CONFIG_SCHEMA` | Drop-in `CONFIG_SCHEMA` fragment exposing `SIMMER_POSITION_SIZING`, `SIMMER_KELLY_MULTIPLIER`, `SIMMER_MIN_EV` env vars. |

Methods: `"fractional_kelly"` (default, multiplier 0.25), `"kelly"` (full, aggressive), `"fixed"` (uses `kelly_multiplier` as a flat fraction). For NO bets pass `p_win=1-p_yes` and `market_price=1-yes_price`.

## Auto-Redeem

When a Polymarket market resolves and your side wins, the CTF tokens in your wallet must be redeemed to claim the USDC.e payout. Auto-redeem handles this automatically each cycle.

```python
# Redemption writes to a real-money wallet; opt in explicitly.
client = SimmerClient.from_env(venue="polymarket", live=True)
# Call at the start of each cycle to claim any pending winnings
results = client.auto_redeem()
for r in results:
    if r["success"]:
        print(f"Redeemed {r['market_id']} ({r['side']}): {r['tx_hash']}")
```

- Fetches positions where `redeemable: true` and `redeemable_side` is set (Polymarket only)
- For self-custody wallets (`WALLET_PRIVATE_KEY`): signs and broadcasts on-chain
- For managed wallets: server handles signing, no local key needed
- Requires an explicitly live client (`live=True`); paper and implicit-sim clients raise

Auto-redeem can be toggled per-agent from the Simmer dashboard.

## Skills

Pre-built trading strategies are published on [ClawHub](https://clawhub.ai) and listed in the Simmer registry. Browse and install at **[simmer.markets/skills](https://simmer.markets/skills)**.

```bash
# Install a skill via ClawHub CLI
clawhub install polymarket-weather-trader
```

Skills in this repo (`skills/`) are the official Simmer-maintained strategies. See [docs.simmer.markets/skills/building](https://docs.simmer.markets/skills/building) for the full guide to building, remixing, and publishing your own.

## Resources

| | |
|--|--|
| **Platform** | [simmer.markets](https://simmer.markets) |
| **API Reference** | [docs.simmer.markets](https://docs.simmer.markets) |
| **Onboarding Guide** | [simmer.markets/skill.md](https://simmer.markets/skill.md) |
| **Skills Registry** | [docs.simmer.markets/skills](https://docs.simmer.markets/skills/overview) |
| **ClawHub** | [clawhub.ai](https://clawhub.ai) |
| **MCP Server** | `npm install -g simmer-mcp` — docs + error troubleshooting as MCP resources ([npm](https://www.npmjs.com/package/simmer-mcp)) |
| **Telegram** | [t.me/+m7sN0OLM_780M2Fl](https://t.me/+m7sN0OLM_780M2Fl) |

## Contributing

SDK improvements and bug fixes are welcome. If you've hit an edge case with `SimmerClient` or have a useful addition, open a PR.

- **Skills** belong on [ClawHub](https://clawhub.ai), not this repo — see [docs.simmer.markets/skills/building](https://docs.simmer.markets/skills/building)
- **API bugs or feature requests** → open an issue first
- **AI-assisted PRs welcome** — just note it in the PR description
- Keep PRs focused on one thing

See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full guide.

## License

MIT
