
Simmer
io.github.adlai88Published by GitHub account adlai88v3.3.2Updated Oct 24, 2026
Trade prediction markets with AI agents — skill discovery, autoresearch, and execution.
Overview
Simmer lets an AI assistant discover prediction markets, research and paper-trade them, and optionally place real trades on Polymarket, Kalshi and Hyperliquid.
- What you can do
- Browse and import prediction markets across venues, with filters by status, volume, tags and keyword.
- Research markets and get trading context such as safeguards, slippage and conflict detection.
- Place buy and sell orders in paper mode with virtual currency, or live on real venues.
- Track positions, portfolios, P&L, trade history, open orders and price history.
- Manage orders and risk: stop-loss and take-profit monitors, cancel orders, price alerts and webhooks.
- Redeem winning positions and look up fixes for errors.
- When to use it
- Use it when you want an agent to research and trade prediction markets, or to rehearse a strategy with simulated money before risking real funds. It suits autonomous trading skills as well as manual, assistant-driven market browsing and order management.
- Requirements
- Runs locally via npx (Node.js). A Simmer API key in SIMMER_API_KEY is needed for Pro tools such as autoresearch, trading and briefings; free tools work without it. Live Polymarket trading needs a wallet key (WALLET_PRIVATE_KEY) or a managed wallet, and Kalshi live trading needs a Pro plan. Network access to Simmer and the venues is required.
Installation
In SourceWeft
- Open Simmer in the dashboard and add it to a workspace.
- Enable the server for the chats that should use its tools.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Other MCP clients
Follow the launch instructions in the repository.
README
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
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:
Set environment variables:
Default to dry-run. Skills should require
--liveto execute real trades. Paper-trade with$SIMuntil your edge is consistent, then graduate to real money.
Raw SDK
For developers building custom integrations:
Trading Venues
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_KEYorOWS_WALLET, regularSimmerClient(...)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. Passprocess_risk_alerts=Falseto skip this constructor check for dry runs. UseSimmerClient.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_typefor the SDK/server smart default: buys useFAK(fill what is available immediately), sells useGTC(rest on the book to improve fill rate on thin books). For structurally thin markets or maker-style limit entries, passorder_type="GTC"and an explicitprice.
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_<exchange_address> and
position_manager_<exchange_address>, using the full lowercase ExchangeV3
address:
pusd_0xe3333700ca9d93003f00f0f71f8515005f6c00aais true when pUSDallowance(owner, ExchangeV3) >= (2**256 - 1) // 2, PolyNode's readiness threshold.position_manager_0xe3333700ca9d93003f00f0f71f8515005f6c00aais the result of PositionManagerisApprovedForAll(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_addressis present,per_agent_dw_activemust be a boolean. When true, approval checks useper_agent_deposit_wallet_address. - Otherwise,
wallet_uses_deposit_walletmust be a boolean. When true, approval checks usedeposit_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).
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:
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:
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
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, thenupdate_agent_wallet_creds(...)caches the CLOB creds. OWS callers useupdate_agent_wallet_creds(ows_wallet_name="..."); raw-key callers withWALLET_PRIVATE_KEYuseupdate_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 thesimmer-wallet-setupskill 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
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.
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.
- Fetches positions where
redeemable: trueandredeemable_sideis 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 and listed in the Simmer registry. Browse and install at simmer.markets/skills.
Skills in this repo (skills/) are the official Simmer-maintained strategies. See docs.simmer.markets/skills/building for the full guide to building, remixing, and publishing your own.
Resources
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, not this repo — see 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 for the full guide.
License
MIT
Source: README.md at commit 4c891c0
Tools
0Version history
1- v3.3.2LatestSep 16, 2026
Score
50% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
- Reached in the last 30 days25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
- Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
- Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
- DescriptionRequired15 pts
- Logo10 pts
- Documentation15 pts
- License10 pts