Simmer

io.github.adlai88由 GitHub 帳號 adlai88 發布v3.3.2更新於 Oct 24, 2026

Trade prediction markets with AI agents — skill discovery, autoresearch, and execution.

已驗證STDIO僅桌面金融AI 與機器學習

概覽

AI 產生的概覽

Simmer 讓 AI 助理探索預測市場、研究並以虛擬資金模擬交易,也可選擇在 Polymarket、Kalshi 與 Hyperliquid 上真實下單。

可以做什麼
  • 瀏覽並匯入各平台的預測市場,可依狀態、成交量、標籤與關鍵字篩選。
  • 研究市場並取得交易脈絡,包括風控、滑價與衝突偵測。
  • 以虛擬貨幣模擬買賣,或在真實平台上送出訂單。
  • 檢視持倉、投資組合、損益、交易紀錄、未成交訂單與價格歷史。
  • 管理訂單與風險:停損停利監控、取消訂單、價格提醒與 webhook。
  • 贖回獲勝持倉,並查詢錯誤的修正方式。
適用情境
當你希望助理研究並交易預測市場,或先用模擬資金演練策略再投入真實資金時使用。它既適合自主交易技能,也適合由助理協助的手動瀏覽市場與訂單管理。
執行需求
透過 npx 在本機執行(需要 Node.js)。Pro 工具(autoresearch、交易、簡報)需要 SIMMER_API_KEY 中的 Simmer API 金鑰;免費工具不需金鑰。Polymarket 實盤交易需要錢包金鑰(WALLET_PRIVATE_KEY)或託管錢包,Kalshi 實盤交易需要 Pro 方案。需要連線至 Simmer 與各平台的網路。
安裝前請注意
交易可能動用真實資金:實盤交易由 SIMMER_MCP_ALLOW_LIVE 控制,未設定時所有訂單以模擬模式執行。Polymarket 實盤交易需要錢包私鑰,且建立實盤用戶端時可能自動送出停損停利平倉單。自動贖回會簽署鏈上交易。建議先使用模擬模式,確認設定後再啟用實盤。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Simmer,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

Simmer SDK

[PyPI version]

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/28 skills an agent installs and runs. skills/simmer/SKILL.md is the canonical source for simmer.markets/skill.md.
mcp/MCP server, published to npm as simmer-mcp.
simmer_sdk/Python SDK, published to PyPI as simmer-sdk.

Installation

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

python
import osfrom simmer_sdk import SimmerClient
SKILL_SLUG = "my-skill-slug"   # Must match your ClawHub slugTRADE_SOURCE = f"sdk:{SKILL_SLUG}"
_client = Nonedef 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 | kalshiexport 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&Lfor p in client.get_positions():    print(f"{p.question[:50]}: P&L ${p.pnl:.2f}")

Trading Venues

VenueCurrencyDescription
sim$SIM (virtual)Default. Paper trading on Simmer's LMSR markets.
polymarketUSDC.e (real)Real trades on Polymarket (Polygon). Requires WALLET_PRIVATE_KEY.
kalshiUSDC (real)Real trades on Kalshi. Requires Pro plan.
python
# Paper trading (default)client = SimmerClient(api_key="sk_live_...", venue="sim")
# Real trading on Polymarketclient = 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 tradeclient.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:

FieldCurrent marketsProtocol V2 markets
polymarket_protocol_versionAbsent or "v1""v2"
polymarket_position_idAbsent or nullYES position ID as a decimal uint256 string
polymarket_no_position_idAbsent or nullNO position ID as a decimal uint256 string
polymarket_neg_riskExisting booleantrue 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 summarysummary = 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 30dsimmer 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

MethodDescription
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

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 SimmerClientfrom 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")
FunctionPurpose
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_SCHEMADrop-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 winningsresults = 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 and listed in the Simmer registry. Browse and install at simmer.markets/skills.

bash
# Install a skill via ClawHub CLIclawhub install polymarket-weather-trader

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

Platformsimmer.markets
API Referencedocs.simmer.markets
Onboarding Guidesimmer.markets/skill.md
Skills Registrydocs.simmer.markets/skills
ClawHubclawhub.ai
MCP Servernpm install -g simmer-mcp — docs + error troubleshooting as MCP resources (npm)
Telegramt.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, 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

來源:README.md,提交 4c891c0

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包,因此其工具未知。

版本歷史

1
  1. v3.3.2最新Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分