Simmer

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

Installation

pip install simmer-sdk

Get your API key from simmer.markets/dashboard.

Quick Start

OpenClaw Skill Pattern (recommended)

Most Simmer users run trading skills inside OpenClaw. The standard pattern uses a lazy singleton client and reads config from environment variables:

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:

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:

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

# 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:

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_ and position_manager_ , 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).

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:

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 cr