Simmer

Simmer SDK

Simmer は AI エージェント向けの主要な予測市場ハーネスです。自律型エージェントは、セルフカストディウォレット、安全策、適切なコンテキストを備えた統一 API を通じて、Polymarket、Kalshi、Hyperliquid などの取引所で取引できます。

• AI エージェント向け予測市場ハーネス — 自律型エージェント向けに設計されていますが、手動取引も完全にサポートしています。ユーザーは取引スキルをインストールし、エージェントに自律的に取引させることができます。
• $SIM によるシミュレーション取引 — 実資金をリスクにさらす前に、仮想通貨でペーパートレードを行えます。
• 複数の取引所に対応 — 1 つの統一 API を通じて、Polymarket、Kalshi、Hyperliquid で取引できます。

このリポジトリの内容

skills/	エージェントがインストールして実行する 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

API キーは simmer.markets/dashboard から取得してください。

クイックスタート

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）。

バックテスト

上記の3つのモードはすべてライブフォワードです。資金をリスクにさらす前に過去のデータで戦略をテストするには、スキルバンドルをバックテストします。

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

エンジンは、変更を加えていないスキルを、先読み防止済みの固定リプレイサーバー（ティックごとに1つのサブプロセス）に対して再生し、損益、的中率、最大ドローダウン、取引、ベースライン（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()	Polymarket 用の外部 EVM ウォレットをリンクします
set_approvals()	Polymarket トークンの承認を設定します
activate_polymarket_dw(agent_id=None)	Polymarket の入金ウォレットに対するオンチェーン CLOB 承認を設定します。ユーザープライマリ（引数なし）またはエージェント別（agent_id=...）に設定できます。注記を参照してください。
readonly()	コンストラクター実行時にリスク退出処理や注文の発注を行わない、検証／ステータス確認用クライアントのコンストラクターです
troubleshoot()	あらゆるエラーを検索し、解決方法を取得します（認証不要）

エージェント別ウォレット（Elite ティア）： エージェント別（Elite 専用）ウォレットを有効にするには、承認を先に行う 2 回の呼び出しが必要です。activate_polymarket_dw(agent_id=...) で入金ウォレットのオンチェーン CLOB 承認を設定し、次に update_agent_wallet_creds(...) で CLOB 認証情報をキャッシュします。OWS 呼び出し元は update_agent_wallet_creds(ows_wallet_name="...") を使用します。WALLET_PRIVATE_KEY を使う raw-key 呼び出し元は update_agent_wallet_creds(agent_id="...") を使用します。取引を行うには、承認とキャッシュされた認証情報の両方が必要です。認証情報だけをキャッシュしてもオンチェーンの使用許容量は設定されないため、リレイヤーで「insufficient allowance」エラーが発生し、取引に失敗します。全手順については simmer-wallet-setup スキルを参照してください。（set_approvals() はユーザープライマリの EOA 用の経路で、エージェント別の入金ウォレットでは何も行いません。）

ヒント — 価格を事前に丸めないでください。 simmer-sdk ≥ 0.17.1 は、各 Polymarket 市場のティックグリッドに合わせて価格を自動的に丸めます。計算した未加工の価格を client.trade(..., price=p) に渡せば、残りは SDK が処理します。固定ティックを使って事前に丸める（例：round(price, 3)）と、ティックサイズが異なる市場では誤った値が気づかれないまま生成されます。

エラー処理： SDK のすべての 4xx レスポンスには、既知のパターンに該当するエラーに対して、具体的な手順を示す fix フィールドが含まれます。また、{"error_text": "..."} を指定して POST /api/sdk/troubleshoot を呼び出すと、あらゆるエラーを検索できます。

パラメーター、例、エラーコードを含む API リファレンスの全文：simmer.markets/docs.md

スキルビルダーのユーティリティ

SDK には、スキルの作成者向けのヘルパーモジュールが 2 つ付属しています。独自に作成するより、こちらを優先して使用してください。トップトレーダーや外部の調査に基づくパターンが組み込まれています。

ポジションサイジング — simmer_sdk.sizing

バイナリー予測市場向けのケリー基準と期待値によるサイジングです。デフォルトでは、期待値ゲート付きのフラクショナル・ケリー（0.25x）を使用するため、エッジがしきい値を下回る取引では 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)	1 株あたりのエッジ（p_win - market_price）を返します。
SIZING_CONFIG_SCHEMA	SIMMER_POSITION_SIZING、SIMMER_KELLY_MULTIPLIER、SIMMER_MIN_EV 環境変数を公開する、すぐに利用できる CONFIG_SCHEMA フラグメントです。

方式は "fractional_kelly"（デフォルト、倍率 0.25）、"kelly"（フル、積極的）、"fixed"（kelly_multiplier を固定比率として使用）です。NO ベットの場合は、p_win=1-p_yes、market_price=1-yes_price を渡してください。

自動償還

Polymarket の市場が解決し、保有する側が勝った場合、USDC.e の払い戻しを受け取るには、ウォレット内の CTF トークンを償還する必要があります。自動償還は、各サイクルでこれを自動的に処理します。

# 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 ダッシュボードからエージェントごとに切り替えられます。

スキル

構築済みの取引戦略は 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 は 1 つの内容に絞ってください

詳しくは、完全ガイドの CONTRIBUTING.md をご覧ください。

ライセンス

MIT