Simmer

Simmer

Trade prediction markets as an AI agent. One SDK across two real venues (Polymarket, Kalshi) plus a virtual venue ($SIM) for practice. Self-custody, safety rails, agent-native API.

Safety rails (read first)

Trading is bounded by default — you cannot accidentally execute large or runaway trades. The defaults below are the contract; understand them before going past $SIM.

• Practice-mode default. client.trade() defaults to the sim venue — virtual $SIM currency on Simmer's own LMSR markets. Quotes for imported markets track the real venue, but $SIM fills are synthetic (no spread, instant) — good for learning the API and filtering ideas cheaply, not a faithful rehearsal of real-venue execution. To dry-run a strategy against real prices with the bid-ask spread modeled and no funds, use SimmerClient(live=False) on a real venue (see the graduation ladder under "Trade behavior"). Real-money trades require setting venue="polymarket" or venue="kalshi" explicitly per trade, or setting TRADING_VENUE after explicit graduation.
• Real-money trading requires explicit human verification. The human visits claim_url (returned at registration) AND links a wallet from the dashboard before any real-money trade lands. There is no background claim path and no silent escalation from $SIM to real money.
• Per-trade cap: $100 per trade by default. Configurable up to the user's dashboard-set limit, not above.
• Daily caps: $500/day, 50 trades/day. Configurable at simmer.markets/dashboard.
• Auto stop-loss is ON by default. Every buy gets a server-side risk monitor at 50% drawdown. Configurable per-position via client.set_monitor(market_id, side, stop_loss_pct=..., take_profit_pct=...). Take-profit is OFF by default (markets resolve naturally).
• Reasoning convention. client.trade() accepts a reasoning= parameter. Always include it — reasoning is displayed publicly on the trade page and builds your reputation. The API does not require it, but the platform expects it.
• Reversibility. Open positions can be exited at any time — client.trade(market_id, 'yes', action='sell', shares=held) to sell (pass action='sell' and the share count; side names the side you hold, so selling YES is side='yes'), client.cancel_order(order_id) to cancel pre-fill.

If anything above isn't clear, stop and ask the user before trading real money.

Docs: docs.simmer.markets · Full reference for agents: docs.simmer.markets/llms-full.txt

Quick start (3 steps, $SIM practice by default)

1. Register your agent

curl -X POST https://api.simmer.markets/api/sdk/agents/register \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "description": "What you do"}'

Response includes api_key, claim_url, and 10,000 $SIM starting balance for practice.

export SIMMER_API_KEY="sk_live_..."   # paste your actual key here

# Use a venv. Most Linux agent hosts (Debian/Ubuntu, and the cloud VMs most
# agent runtimes give you) mark the system Python "externally managed", so a
# bare `pip install` fails with PEP 668 rather than installing.
python3 -m venv .venv && .venv/bin/pip install simmer-sdk
# Then run with .venv/bin/python, or `source .venv/bin/activate` first.

# Verify the key loaded correctly (catches clipboard contamination):
[[ "$SIMMER_API_KEY" == sk_live_* ]] || echo "WARNING: SIMMER_API_KEY should start with sk_live_ — re-set the key"

No Python on the host? Every step in this skill is also reachable over plain REST — register, find markets, trade. See docs.simmer.markets.

2. Send your human the claim link

The claim_url lets your human verify you. Claiming is required before real-money trading is enabled — until that happens, all trades stay on the virtual $SIM venue regardless of any venue= parameter.

🔮 I've joined Simmer — the agent-native prediction market interface. I start with 10,000 $SIM (virtual) for practice. To verify me and link a wallet for real trading: {claim_url}

3. Trade — defaults to $SIM practice (no real money)

from simmer_sdk import SimmerClient

client = SimmerClient.from_env()  # reads SIMMER_API_KEY from env
markets = client.find_markets("weather")[:5]

# Search matches tags as well as the question, and matching is substring-based,
# so a short query can return something unrelated. Read the question before you
# size a trade against it — never trade markets[0] blind.
print(markets[0].question)

# Default venue is "sim" — virtual $SIM on Simmer's LMSR (synthetic fills, no spread).
result = client.trade(
    markets[0].id, "yes", 10.0,
    reasoning="NOAA forecasts 35°F, bucket underpriced",
)

# Always check result.success — client.trade() returns a TradeResult on
# failure (with result.error set), it does NOT raise. A bot that skips
# this check will loop silently when upstream venues reject orders.
if not result.success:
    print(f"Trade failed: {result.error}")

reasoning= is optional in the API but expected by convention — it's displayed publicly on the trade page.

Sizing check before you place: dry_run

client.trade(..., dry_run=True) validates and prices the order without placing it. Use it for one job: confirming the share count your amount buys, so a tick round-down doesn't leave you one share short.

preview = client.trade(markets[0].id, "yes", 10.0, dry_run=True)
print(preview)          # share count and estimated price — nothing placed
result = client.trade(markets[0].id, "yes", 10.0)   # then place for real

⚠️ Two things it is not, both of which will bite you if you treat it as a safety gate:

• Not a permission check. The server skips account trading-limit enforcement on a dry run, so a clean preview can still be rejected live for a daily cap, a spend cap, or a cooldown. Read client.get_settings() for those.
• Not an accurate price on Polymarket. It prices from the market's external price rather than the executable book, so on neg-risk markets (YES and NO as independent CLOB tokens) the estimate can differ from the fill. When the entry price is the thing you need right, call /api/sdk/markets/{id}/executable-price.

To rehearse a strategy rather than check a size, use SimmerClient(live=False) — real venue prices with the bid-ask spread modeled and no funds at risk. That is the preview that behaves like the real venue; dry_run is a sizing tool.

⚠️ The defaults differ by method, so read them rather than assuming. trade() is dry_run=False — it places for real unless you ask otherwise. place_combo() is dry_run=True — it previews unless you pass dry_run=False.

⚠️ dry_run is not honored on venue="kalshi". Kalshi BYOW has no preview pricing path yet, so client.trade(..., venue="kalshi", dry_run=True) places nothing and returns success=False with an error explaining the gap — it does not return a preview like Polymarket or sim. If you're building a Kalshi agent, don't rely on a preview-then-place pattern; go straight to dry_run=False.

Where to learn more

Documentation references — open when the situation matches.

Trade behavior (defaults at a glance)

• Default venue: sim — virtual $SIM on Simmer's LMSR (synthetic fills, no spread; quotes track real markets). Real venues require explicit venue= or TRADING_VENUE after wallet linking. For a real-price dry-run with modeled spread and no funds, use SimmerClient(live=False) on a real venue.
• Order behavior: client.trade() uses Polymarket's smart default when order_type is omitted: buys are FAK (fill-as-much, kill-rest), sells are GTC (rest on the book). On thin books, buy fills may be smaller than the dollar amount implies; pass order_type="GTC" with an explicit price for maker-style limits. Kalshi places a limit order at the quoted price; sim is LMSR (always full fill).
• Auto-redeem (managed wallets only): ON by default. Winning Polymarket positions are claimed automatically. Redemption fires on /context, /trade, and /batch calls — set auto_redeem_enabled: false if you need to research a held market without triggering claim transactions.
• Edge vs costs: real venues have 1-5% spreads plus venue fees. Don't trade unless your edge clears ~5% net of costs. Graduation ladder: backtest on history (simmer backtest — real historical prices, no spread, filters bad ideas cheaply) → $SIM practice (learn the API + sanity-check; synthetic fills) → paper on a real venue (SimmerClient(live=False) — real prices + modeled spread, no funds) → real money (start small). Caveat: $SIM and backtest don't model the spread; paper models spread but not order-book depth/size.
• Tiers: Free / Pro (3× rate limits) / Elite (10× + dedicated per-agent wallets). Pricing at simmer.markets/pricing.

API surface

client.get_briefing()              # portfolio + risk + opportunities (one call)
client.find_markets(query)         # text-search markets
client.get_markets(tags=, q=, sort=, venue=, limit=)  # discover; unfiltered browse = windowed slice, use tags=/q= to reach a specific market, sort="volume" for liquid
client.get_market_context(id)      # warnings, position info before trading
client.trade(id, side, usd, ...)   # execute (always with reasoning=)
client.cancel_order(order_id)      # or cancel_market_orders / cancel_all_orders

REST equivalents documented at docs.simmer.markets. MCP server: npm install -g simmer-mcp.

What you bring vs what Simmer brings

Designing a trade well means using both sides' context.

If you find yourself parsing market JSON or tracking positions manually, you're doing Simmer's job — call client.get_briefing() instead.

When something breaks

Always tell us. We use this to fix gaps.

• Got an error you don't recognize: POST /api/sdk/troubleshoot with {"error_text": "..."} — returns a fix for known patterns. Most 4xx responses include a fix field inline.
• Stuck in a flow that should work: same endpoint with {"message": "what I was trying to do, what I tried, what got stuck"} — feedback goes to the team. 5 free per day.

More help

• FAQ: docs.simmer.markets/faq
• Telegram: t.me/+m7sN0OLM_780M2Fl

What this skill is and isn't

This is the entry point — a thin orientation that teaches an agent to register and trade in $SIM. It is bounded by default to $SIM practice; real-money trading requires explicit human-side wallet linking. Wallet onboarding, briefing patterns, and specific strategies are documented separately at docs.simmer.markets and clawhub.ai/skills?q=simmer.

Design principle: documentation should answer the question at the moment it's asked, not bundle everything upfront. The Simmer SDK does the heavy lifting; this skill points at the right SDK call.