Simmer

Simmer SDK

Simmer 是面向 AI Agent 的领先预测市场交易工具。自主 Agent 通过统一的 API 在 Polymarket、Kalshi 和 Hyperliquid 等平台交易，支持自托管钱包、安全防护和智能上下文。

• 面向 AI Agent 的预测市场交易工具——专为自主 Agent 设计，同时也全面支持手动交易。用户安装交易技能后，即可让 Agent 自主交易。
• $SIM 模拟交易——使用虚拟货币进行模拟交易，再决定是否投入真实资金。
• 多平台——通过一个统一的 API 在 Polymarket、Kalshi 和 Hyperliquid 交易。

此仓库包含什么

skills/	Agent 安装并运行的 28 个技能。skills/simmer/SKILL.md 是 simmer.markets/skill.md 的权威来源。
mcp/	MCP 服务，已发布到 npm，包名为 simmer-mcp。
simmer_sdk/	Python SDK，已发布到 PyPI，包名为 simmer-sdk。

安装

pip install simmer-sdk

从 simmer.markets/dashboard 获取 API 密钥。

快速开始

OpenClaw 技能模式（推荐）

大多数 Simmer 用户都在 OpenClaw 中运行交易技能。标准模式使用延迟初始化的单例客户端，并从环境变量读取配置：

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)

设置环境变量：

export SIMMER_API_KEY=sk_live_...
export TRADING_VENUE=sim            # sim | polymarket | kalshi
export WALLET_PRIVATE_KEY=0x...    # Required for Polymarket self-custody

默认使用模拟模式。 技能应要求通过 --live 才能执行真实交易。在 $SIM 中进行模拟交易，直到交易优势稳定后，再转向真实资金交易。

原始 SDK

适用于构建自定义集成的开发者：

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}")

交易平台

平台	货币	说明
sim	$SIM（虚拟）	默认选项。在 Simmer 的 LMSR 市场进行模拟交易。
polymarket	USDC.e（真实）	在 Polymarket（Polygon）进行真实交易。需要 WALLET_PRIVATE_KEY。
kalshi	USDC（真实）	在 Kalshi 进行真实交易。需要 Pro 计划。

# 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 环境变量——OpenClaw 技能使用此变量在启动时选择交易平台，无需更改代码。

构造函数副作用： 对于配置了 WALLET_PRIVATE_KEY 或 OWS_WALLET 的 Polymarket 实盘客户端，常规的 SimmerClient(...) 构造会检查待处理的风险警报，并可能提交止损／止盈平仓订单。这是为了自托管安全而有意设计的：Simmer 服务无法为这些平仓订单签名。传入 process_risk_alerts=False 可在模拟运行时跳过此构造检查。对于 API 密钥验证、预检查／状态检查和其他非交易场景，请使用 SimmerClient.readonly(...)。

价差提示： $SIM 即时成交（AMM，无价差）。真实平台存在 2–5% 的订单簿价差。在 $SIM 中目标价差应高于 5%，再转向真实资金交易。

Polymarket 订单类型： 省略 order_type 时，SDK／服务端会采用智能默认值：买单使用 FAK（立即成交可用数量），卖单使用 GTC（挂单等待，以提高流动性较低的订单簿中的成交率）。对于流动性结构性不足的市场或做市式限价入场，请传入 order_type="GTC" 和明确的 price。

在真实平台进行模拟交易

传入 live=False，即可使用真实市场价格模拟交易——无需钱包或 USDC。对于 Polymarket，成交模拟会考虑 CLOB 买卖价差，以便更真实地计算盈亏。已结算的市场会自动结算（获胜份额支付 $1，失败份额支付 $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}")

进阶路径： sim（即时成交、无价差）→ polymarket + live=False（真实价格、模拟价差）→ polymarket 实盘（真实 USDC）。

回测

以上三种模式都是实时前向模式。要在投入资金前，使用历史数据测试策略，请对技能包进行回测：

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

引擎会针对冻结且防止前视的回放服务（每个时点启动一个子进程），重放你未经修改的技能，并报告 pnl、命中率、最大回撤、交易、基准（买入并持有 YES／随机）、真实性差异以及可复现的 config_hash。对应的编程接口：

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"])

回测使用交易记录价格（不含订单簿），因此衡量的是决策质量，而非执行真实性——每份报告都会列出其 realism_gaps。时间窗口切片从 Simmer 的交易记录服务获取，并缓存在 ~/.simmer/tapes/ 下；传入 --tape <dir> 即可使用自己的数据。目前数据覆盖范围截至约 2026-05-05。

关键方法

方法	描述
get_markets()	列出市场（按状态、来源、场所、标签、关键词筛选）
trade()	买入或卖出份额
get_positions()	所有持仓及盈亏
get_held_markets()	持仓对应的 market_id → 来源标签映射
check_conflict()	检查是否有其他技能在某个市场持仓
get_open_orders()	CLOB 上未完成的 GTC/GTD 订单
maker_rewards_status(market_id)	Polymarket 流动性奖励配置：最大价差、每日奖励池、资格
get_portfolio(venue="all")	投资组合摘要，按场所分类（sim/polymarket/kalshi/total）
get_market_context(market_id, venue="all")	各场所的持仓和交易安全措施
get_trades(venue="all")	合并各场所的交易历史，每行均标注场所
get_price_history()	用于趋势检测的价格历史
import_market()	通过 URL 导入 Polymarket 市场
import_kalshi_market()	通过 URL 导入 Kalshi 市场
list_importable_markets()	查找可导入的市场
check_market_exists()	检查市场是否已在 Simmer 上（不消耗配额）
set_monitor()	为持仓设置止损／止盈
cancel_order()	按 ID 取消单个未完成订单
cancel_market_orders()	取消某个市场上的所有未完成订单（可选按方向筛选）
cancel_all_orders()	取消所有市场上的全部未完成订单
create_alert()	创建价格提醒，可选使用 webhook
register_webhook()	接收交易、结算和价格变动的推送通知
redeem()	赎回指定的 Polymarket 获胜持仓
auto_redeem()	扫描所有持仓，并自动赎回所有获胜持仓
get_paper_summary()	模拟交易模式下的投资组合摘要（余额、盈亏、持仓）
get_settings() / update_settings()	配置交易限额和通知
link_wallet()	关联外部 EVM 钱包以用于 Polymarket
set_approvals()	设置 Polymarket 代币授权
activate_polymarket_dw(agent_id=None)	设置 Polymarket 存款钱包的链上 CLOB 授权——用户主钱包（不传参数）或单个 Agent（agent_id=...）。参见说明。
readonly()	用于验证／状态客户端的构造函数；此类客户端不得处理构造时的风险退出或提交订单
troubleshoot()	查询错误并获取修复方法（无需身份验证）

单个 Agent 钱包（Elite 级别）： 激活单个 Agent（Elite 专用）钱包需要调用 两次，先设置授权：activate_polymarket_dw(agent_id=...) 设置存款钱包的链上 CLOB 授权，然后 update_agent_wallet_creds(...) 缓存 CLOB 凭据。OWS 调用方使用 update_agent_wallet_creds(ows_wallet_name="...")；使用 WALLET_PRIVATE_KEY 的原始密钥调用方使用 update_agent_wallet_creds(agent_id="...")。交易前必须同时设置授权并缓存凭据——仅缓存凭据不会设置链上额度，因此交易会在中继器处因 "insufficient allowance" 而失败。完整流程请参见 simmer-wallet-setup 技能。（set_approvals() 用于用户主 EOA 路径；对单个 Agent 存款钱包则不执行任何操作。）

提示——不要提前对价格取整。 simmer-sdk ≥ 0.17.1 会自动按照各 Polymarket 市场的最小变动价位网格取整。将计算出的原始价格传给 client.trade(..., price=p)，其余工作由 SDK 处理。使用硬编码的最小变动价位提前取整（例如 round(price, 3)），会导致最小变动价位不同的市场静默产生错误值。

错误处理： 当 SDK 4xx 响应中的错误符合已知模式时，所有此类响应都会包含一个 fix 字段，其中提供可操作的说明。你也可以调用 POST /api/sdk/troubleshoot 并传入 {"error_text": "..."} 来查询任何错误。

包含参数、示例和错误代码的完整 API 参考：simmer.markets/docs.md

技能构建工具

SDK 为技能作者提供了两个辅助模块。建议优先使用它们，而不是自行实现——其中封装了顶尖交易者和外部研究中的常见模式。

仓位规模 — simmer_sdk.sizing

用于二元预测市场的凯利准则 + 期望值仓位规模计算。默认使用分数凯利（0.25 倍）并设置期望值门槛，因此低于优势阈值的交易会返回 0.0，技能可以直接跳过。

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")

函数	用途
size_position(p_win, market_price, bankroll, method=, kelly_multiplier=, min_ev=, max_fraction=)	返回交易金额。当优势 ≤ min_ev、凯利值为负或输入无效时，返回 0.0。
kelly_fraction(p_win, market_price)	原始凯利比例 (p - c) / (1 - c)。
expected_value(p_win, market_price)	每份额的优势（p_win - market_price）。
SIZING_CONFIG_SCHEMA	可直接使用的 CONFIG_SCHEMA 片段，用于公开 SIMMER_POSITION_SIZING、SIMMER_KELLY_MULTIPLIER、SIMMER_MIN_EV 环境变量。

方法："fractional_kelly"（默认，乘数为 0.25）、"kelly"（完整凯利，激进）、"fixed"（将 kelly_multiplier 作为固定比例）。对于 NO 下注，请传入 p_win=1-p_yes 和 market_price=1-yes_price。

自动赎回

当 Polymarket 市场结算且你持有的一方获胜时，必须赎回钱包中的 CTF 代币，才能领取 USDC.e 兑付金额。自动赎回功能会在每个周期自动处理。

# 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']}")

• 获取 redeemable: true 且已设置 redeemable_side 的持仓（仅限 Polymarket）
• 对于自托管钱包（WALLET_PRIVATE_KEY）：在链上签名并广播
• 对于托管钱包：由服务器处理签名，无需本地密钥
• 需要显式启用的实盘客户端（live=True）；模拟盘和隐式模拟客户端会报错

可在 Simmer 控制面板中为每个 Agent 单独切换自动赎回功能。

技能

预构建的交易策略已发布在 ClawHub，并列入 Simmer 注册表。可在 simmer.markets/skills 浏览和安装。

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

此仓库（skills/）中的技能是由 Simmer 官方维护的策略。完整的构建、改编和发布指南，请参阅 docs.simmer.markets/skills/building。

资源

平台	simmer.markets
API 参考	docs.simmer.markets
入门指南	simmer.markets/skill.md
技能注册表	docs.simmer.markets/skills
ClawHub	clawhub.ai
MCP 服务	npm install -g simmer-mcp — 提供文档和错误排查内容作为 MCP 资源（npm）
Telegram	t.me/+m7sN0OLM_780M2Fl

贡献

欢迎改进 SDK 和修复错误。如果你遇到 SimmerClient 的边缘情况，或有实用的改进建议，请提交 PR。

• 技能应发布到 ClawHub，而不是此仓库——请参阅 docs.simmer.markets/skills/building
• API 错误或功能请求 → 请先提交 issue
• 欢迎借助 AI 编写 PR——只需在 PR 描述中注明
• PR 请聚焦于单一事项

完整指南请参阅 CONTRIBUTING.md。

许可证

MIT