Polymarket Paper Trader

polymarket-paper-trader

実際の予測市場でAIエージェントがリスクゼロで練習できる環境です。実際の注文板、公式の手数料、検証済みの約定精度を備えています。判断力を練習、評価、ベンチマークできます。

エージェントは日々、確率に関する判断を行っています。Polymarketは世界最大の予測市場であり、その注文板は正直な評価基準です。実際のお金、実際の価格、実際の結果が反映されます。しかし、学習のためにエージェントへウォレットを渡すことはできません。そこでこのプロジェクトでは、SWE-benchがコーディングエージェントに提供したものと同じように、判断が結果をもたらし、スコアとして評価される忠実な環境をすべてのエージェントに提供します。

• 練習 — エージェントはPolymarketのライブ注文板を相手に、1万ドルのペーパーマネーで取引します。実際の取引所と同じ手数料モデルと約定の仕組みを利用します。
• 評価 — このリポジトリにある polymarket-benchmark ハーネス（別途インストール）が、予測市場の意思決定セットを使ってあらゆるモデルを評価します（Brierスコア、較正、アルファ）。
• 比較 — 複数アカウントでの対戦とリーダーボードにより、エージェント同士の順位を決定します。
• 競争 — Forecast Arena：AIモデルとシンプルなベースラインが毎日同じPolymarketの質問を予測し、実際の結果に基づいてスコアが付けられる、公開中のライブリーダーボードです（Brierスコア）。このリポジトリから実行できます（モデルを登録 · ワークフロー · 生データ）。

agent-nextの一環として、エージェント中心の世界を構築しています。

60秒デモ

pip install polymarket-paper-trader
pm-trader init --balance 10000                 # $10k paper money
pm-trader markets search "bitcoin"             # find markets
pm-trader buy will-bitcoin-hit-100k yes 500    # buy $500 of YES
pm-trader stats --card                         # shareable stats card

インストールせずに使いたい場合は、uvx --from polymarket-paper-trader pm-trader-mcpを実行すると、エージェントが接続するMCP サーバーを起動できます（下記の対応環境を参照）。

これで完了です。AIエージェントはリスクゼロでPolymarketの取引を始められます。

インストール

# via pip (CLI + MCP server)
pip install polymarket-paper-trader

# or the MCP server alone, with no install
uvx --from polymarket-paper-trader pm-trader-mcp

# from source (development)
uv pip install -e ".[dev]"

Python 3.10以降が必要です。

対応環境

ランタイム	1行でインストール
Claude Code	/plugin marketplace add agent-next/polymarket-paper-trader
Codex CLI	codex mcp add polymarket-paper-trader -- uvx --from polymarket-paper-trader pm-trader-mcp
Cursor
Gemini CLI	gemini extensions install https://github.com/agent-next/polymarket-paper-trader
OpenCode / Goose / Cline / Windsurf / Copilot	クライアントのMCP設定に pm-trader-mcp を追加
OpenClaw / ClawHub	npx clawhub install polymarket-paper-trader
Hermes Agent / LangChain / OpenAI Agents SDK / CrewAI	uvx --from polymarket-paper-trader pm-trader-mcpをラップ
ChatGPT / Claude.ai（リモートMCP）	ホストのリモートMCP設定にリモートの /mcp URLを追加

上記すべてのランタイム（Grok/xAIのリモートMCPを含む）向けの、コピーしてすぐ使える完全な設定はこちらです：docs/integrations.md。 MCP Appsを実装するホストでは portfolio と stats がインラインダッシュボードとして表示されます。それ以外のホストでは同じテキスト結果が表示されます。

ChatGPT / Claude.ai / 個人用エージェントから利用する

HTTP のみを扱うホスト向けに、リモートモードが用意されています。オプトインの --auth-issuer、 --auth-audience、--resource-url フラグを指定して pm-trader-mcp --transport streamable-http を実行し、ホストのリモート MCP 設定でサーバーの /mcp URL を追加します。デフォルトでは無効で、運用する OAuth/OIDC 発行者が必要です。pm-trader は発行者に対してベアラートークンを検証し、検証済みの各サブジェクトに専用のペーパーアカウントを割り当てます。追加できるホスト型エンドポイントはありません。サーバーは自分で実行します。セットアップ、脅威モデル、環境変数での同等設定については、docs/remote-mcp.md を参照してください。

クイックスタート

# Initialize with $10k paper balance
pm-trader init --balance 10000

# Browse markets
pm-trader markets list --sort liquidity
pm-trader markets search "bitcoin"

# Trade
pm-trader buy will-bitcoin-hit-100k yes 100      # buy $100 of YES
pm-trader sell will-bitcoin-hit-100k yes 50       # sell 50 shares

# Check portfolio and P&L
pm-trader portfolio
pm-trader stats

仕組み — そして信頼できる理由

• 注文は実際の板を動きます。 買い注文は、実際のテイカー注文と同様に、最も安い価格から順にライブの売り板を消費します。スリッページは実際に発生し、ベーシスポイントで報告されます
• 手数料は公式の約定ごとの計算式に従います — fee = C × rate × p × (1-p) を小数点以下 5 桁に丸め、メイカーは免除されます（正確な仕様は CHANGELOG を参照）。概算ではなく、各市場が公開する手数料体系に基づいて、約定した各価格レベルごとに課金されます
• ペーパーマネーでも、実際と同じ規律です。 指値買い注文は資金を確保し、部分約定では残りの注文が有効なまま保持され、終了または一時停止中の市場では取引が拒否されます。また、指値はティックサイズに照らして検証されます
• 決済時は 1 株あたり 1 ドルが支払われます。 市場が終了したら resolve（または resolve --all）を呼び出すと、勝者には実際と同様に払い戻されます
• 検証済みの忠実度。 ライブテストスイートでは、シミュレーション約定価格が市場で実際に提示された価格帯（Data API v2 の価格履歴）に収まること、および手数料が公式の計算式と完全に一致することを検証します。CI では実 API に対して実行します
• 上流との整合性。 クライアントは最新の Gamma / CLOB / Data API の仕様に対応しており、ライブプローブでコントラクトを検証済みです
• 複数結果の市場 — YES/NO だけでなく、任意の数の結果に対応します
• Kalshi にも対応。 kalshi:<ticker> スラッグを渡すと（pm-trader buy kalshi:KXNBAGAME-26OCT16DENLAL-LAL yes 25）、同じコマンドとツールで Kalshi 市場をペーパートレードできます。kalshi markets で市場を検索できます。手数料は各シリーズが公開する計算式に従います（docs/kalshi.md）
• コアパッケージのカバレッジゲートは 100% で、ライブ API に対するエンドツーエンドテストもあります

CLI コマンド

コマンド	説明
init [--balance N]	ペーパートレーディング口座を作成
balance	現金、拘束中／利用可能な現金、ポジション価値、損益合計を表示
reset --confirm	すべてのデータを消去
markets list [--limit N] [--sort volume|liquidity]	アクティブなマーケットを閲覧
markets search QUERY	マーケットを全文検索
markets get SLUG	マーケットの詳細
markets tags	すべてのマーケットカテゴリ／タグを一覧表示
markets event SLUG	イベントの詳細 — 関連するマーケットのグループ
price SLUG	YES／NO の中間価格とスプレッド
book SLUG [--depth N]	オーダーブックのスナップショット
watch SLUG [SLUG...] [--outcome yes|no]	ライブ価格を監視
buy SLUG OUTCOME AMOUNT [--type fok|fak]	成行価格で購入
sell SLUG OUTCOME SHARES [--type fok|fak]	成行価格で売却
portfolio	ライブ価格付きのオープンポジション
history [--limit N]	取引履歴
kalshi markets [--limit N] [--status open|closed|settled] [--series T] [--event T]	Kalshi のマーケット（読み取り専用）
kalshi market TICKER	Kalshi の単一マーケット（読み取り専用）
kalshi book TICKER [--depth N]	Kalshi の YES オーダーブック（読み取り専用）
orders place SLUG OUTCOME SIDE AMOUNT PRICE	指値注文（GTC/GTD）
orders list	オープン中の指値注文（未約定および一部約定）
orders cancel ID	指値注文をキャンセル
orders cancel-all	すべての未約定の指値注文を一括キャンセル
orders check	価格が指定価格を超えた場合に指値注文を約定
stats [--card|--tweet|--plain]	勝率、ROI、利益、最大ドローダウン
resolve [SLUG] [--all]	クローズ済みマーケット、またはすべてのクローズ済みマーケットを確定（勝者は1株あたり$1を獲得）
leaderboard	ローカル口座のランキング
pk ACCOUNT_A ACCOUNT_B	対決：どちらのトレーダーが優れているか？
export trades [--format csv|json]	取引履歴をエクスポート
export positions [--format csv|json]	ポジションをエクスポート
strategy run MODULE.FUNC	トレーディング戦略を実行
strategy compare ACCT1 ACCT2	口座のパフォーマンスを比較
strategy pk STRAT_A STRAT_B	対決：どちらのトレーダーが優れているか？
benchmark run MODULE.FUNC	strategy run のエイリアス
benchmark compare ACCT1 ACCT2	strategy compare のエイリアス
benchmark pk STRAT_A STRAT_B	strategy pk のエイリアス
accounts list	名前付き口座を一覧表示
accounts create NAME	A/B テスト用の口座を作成
accounts delete NAME --confirm	名前付き口座とそのすべてのデータを削除
mcp	MCP サーバーを起動（stdio トランスポート）

グローバルフラグ：--data-dir PATH、--account NAME（または環境変数 PM_TRADER_DATA_DIR、PM_TRADER_ACCOUNT）。

MCP サーバー — エージェントでできること

エージェントは、Model Context Protocol を通じて次のツールを利用できます。 サーバーにはトレーディングのプレイブックも含まれています。MCP サーバーの instructions、trading_playbook プロンプト、skill://trading-playbook リソースとして提供されるため、MCP のみを利用するクライアント（Cursor、Claude.ai コネクター、Grok API リモート MCP、ChatGPT アプリ）も、スキル対応エージェントが skill/polymarket-paper-trader/SKILL.md から得るものと同じガイダンスを利用できます。

pm-trader-mcp  # starts on stdio

# or, with no local install:
uvx --from polymarket-paper-trader pm-trader-mcp

Claude Code の設定に追加します：

{
  "mcpServers": {
    "polymarket-paper-trader": {
      "command": "pm-trader-mcp"
    }
  }
}

リモートトランスポート（streamable-http）

HTTP のみを使用する MCP クライアントでは、--transport streamable-http を付けてサーバーを実行します：

pm-trader-mcp --transport streamable-http --host 127.0.0.1 --port 8000
# or: pm-trader mcp --transport streamable-http --host 127.0.0.1 --port 8000

MCP エンドポイントは http://<host>:<port>/mcp になります。呼び出し元ごとの分離はありません。 サーバーに接続できる全員が、すべてのペーパー口座を共有します。セルフホスト専用であり、公開されたマルチユーザーサービスではありません。このトランスポートには認証がありません。 ポートに接続できる人は誰でも、公開されているすべてのツールを呼び出せます。backtest と pk_battle（ローカルファイルの読み取りとローカル戦略モジュールの実行）は stdio 専用であり、streamable-http 経由で提供する場合は登録されません。

Docker

docker build -t pm-trader-mcp .
docker run -p 127.0.0.1:8000:8000 -v pm-trader-data:/root/.pm-trader pm-trader-mcp

ポートは（上記のように）127.0.0.1 のみに公開してください。認証プロキシを前段に置く場合はその限りではありません。コンテナ自体には認証機能がありません。

MCP ツール

ツール	機能
init_account	初期残高を設定してペーパーアカウントを作成
get_balance	現金、予約済み／利用可能な現金、ポジション評価額、損益合計
reset_account	すべてのデータを消去して、最初から開始
search_markets	キーワードでマーケットを検索
list_markets	出来高／流動性順にマーケットを表示
get_tags	絞り込み用のすべてのマーケットカテゴリ／タグ
get_markets_by_tag	特定のカテゴリ／タグのマーケット
get_event	イベントの詳細 — 関連するマーケットのグループ
get_market	結果と価格を含むマーケットの詳細
get_order_book	ライブのオーダーブックスナップショット（買い注文＋売り注文）
kalshi_markets	Kalshi のマーケット。読み取り専用（オープン／クローズ／決済済み、シリーズまたはイベント別）
kalshi_market	ティッカー指定の Kalshi マーケット1件。読み取り専用
kalshi_book	ライブの Kalshi YES オーダーブック。読み取り専用
watch_prices	複数のマーケットの価格を監視
buy	利用可能な最良価格で株式を購入
sell	利用可能な最良価格で株式を売却
portfolio	ライブ評価額と損益を含む未決済ポジション
history	約定詳細を含む最近の取引履歴
place_limit_order	指値注文 — 約定、キャンセル、または期限切れまで未決済のまま
list_orders	保留中の指値注文
cancel_order	保留中の注文をキャンセル
cancel_all_orders	保留中の指値注文をすべて一括キャンセル
check_orders	保留中の注文をライブ価格に対して執行
stats	勝率、ROI、利益、最大ドローダウン
resolve	クローズしたマーケットを決済（勝者は1株あたり$1を獲得）
resolve_all	クローズしたすべてのマーケットを決済
backtest	過去のスナップショットを使って戦略をバックテスト（stdio のみ）
stats_card	共有可能な統計カード（tweet/markdown/plain）
share_content	プラットフォーム別のコンテンツ（twitter/telegram/discord）
leaderboard_entry	検証可能なリーダーボード投稿を生成
leaderboard_card	すべてのローカルアカウントを対象としたトップ10ランキングカード
pk_card	2つのアカウントの直接比較
pk_battle	2つの戦略を直接対戦させ、自動比較（stdio のみ）

戦略の例

examples/ にすぐに使える戦略が3つあります。

モメンタム（examples/momentum.py）

YES 価格が0.55を上回ったときに購入し、0.70で利益確定、0.35で損切りします。

pm-trader strategy run examples.momentum.run

平均回帰（examples/mean_reversion.py）

YES 価格が公正価値の0.50を12セント以上下回ったときに購入し、価格が戻ったら売却します。

pm-trader strategy run examples.mean_reversion.run

指値グリッド（examples/limit_grid.py）

現在価格より低い価格に指値買い注文をグリッド状に並べ、より高い価格に利益確定の売り注文を出します。

pm-trader strategy run examples.limit_grid.run

Jev エッジ（examples/jev_edge.py）

「Jev 対マーケット」：Jev に各バイナリマーケットの YES 確率を尋ね、Jev が有利と判断した側を購入します。手数料の影響が大きい、価格が[0.05, 0.95]の範囲外のマーケットはスキップします — pm-trader strategy run examples.jev_edge.run（pip install -e "benchmark" が必要です）。

独自の戦略を書く

戦略はexamples.パッケージからインポートされるため（許可リストはpm_trader/benchmark.pyにあります）、ファイルをそこに配置してください。

# examples/my_strategy.py
from pm_trader.engine import Engine

def run(engine: Engine) -> None:
    """Your strategy receives a fully initialized Engine."""
    markets = engine.api.search_markets("crypto")
    for market in markets:
        if market.closed or market.yes_price < 0.3:
            continue
        engine.buy(market.slug, "yes", 100.0)

pm-trader strategy run examples.my_strategy.run

過去データを使ってバックテストするには：

def backtest_strategy(engine, snapshot, prices):
    """Called once per historical price snapshot."""
    if snapshot.midpoint > 0.6:
        engine.buy(snapshot.market_slug, snapshot.outcome, 50.0)

エージェントを評価する：polymarket-benchmark

ペーパートレーダーは練習場で、このリポジトリのpolymarket-benchmarkパッケージはスコアボードです。これは別途インストールするパッケージです（pm-trader CLI の一部ではありません — pm-trader strategyは取引戦略を再生します（pm-trader benchmarkは引き続きエイリアスとして利用できます）。CLI の表は上記を参照してください）。

pip install -e "benchmark[dev]"
cd benchmark && polymarket-benchmark run --model opencode/jev-1.13-free --market-set mini

2つのモデルを直接対戦させ、どちらの判断が実際に優れているかを確認します。マーケットのセット、スコアリング（Brier、キャリブレーション、アルファ）、モデルのセットアップについては、benchmark/README.mdを参照してください。

複数アカウントのサポート

アカウントを分離して、複数の戦略を並行して実行できます。

pm-trader --account aggressive init --balance 5000
pm-trader --account conservative init --balance 5000

pm-trader --account aggressive buy some-market yes 500
pm-trader --account conservative buy some-market yes 100

pm-trader strategy compare aggressive conservative

結果を共有する

共有可能な統計カードを生成し、X/Twitter に投稿します。

pm-trader stats --tweet    # X/Twitter optimized
pm-trader stats --card     # markdown for Telegram/Discord
pm-trader stats --plain    # plain text

AI エージェントは stats_card MCP ツールを使用して、カードを自動的に生成・共有できます。

正直な制限事項

• ペーパー取引のみです。 ウォレット、キー、実際の取引、実際のお金は一切使用しません。決済額は 1 株あたり 1 ドルとしてシミュレーションされます。
• シミュレーションの品質は、実際のオーダーブックと価格履歴に照らして検証されていますが、実際の取引では、シミュレーターが保証できない注文キューでの順位、レイテンシー、取引相手の挙動が加わります。
• ライブ市場データの取得には、Polymarket の公開 API へのネットワークアクセスが必要です（キーは不要です）。

OpenClaw / ClawHub

ClawHub で polymarket-paper-trader として利用できます。

npx clawhub install polymarket-paper-trader

GitHub ボット

Issue または PR に /oc または /opencode とコメントしてください。新しい Issue にはトリアージの返信が付き、ドラフトではない PR には簡易レビューが行われます。人間が bot:implement を追加するか、/oc implement とコメントした場合にのみ実装が始まります（FreeInference deepseek-v4-flash。実装のプッシュでは、contents/issues/PRs のみにスコープを限定した GITHUB_TOKEN が使用され、Actions へのアクセス権はありません。そのため、actions: write を持つ唯一のジョブである別の dispatch-tests ジョブが、プッシュされたブランチ ref を再検証し、その ref 上の .github/workflows/test.yml がデフォルトブランチと同一であることを確認してから、gh workflow run Tests --ref を実行します。トークンによるプッシュでは CI は起動しません）。マージは常に手動です。ボットがマージすることはなく、必須チェックはブランチ保護によって適用されます。Q&A／トリアージ／レビューには引き続き qwen3.6-35b を使用します。ウォレットも実際の取引もありません。セッションは共有されません。

このリポジトリに含まれるもの

ペーパートレーダーが製品であり、3 つの関連パッケージが同じリポジトリ内にあります。

パッケージ	ディレクトリ	内容
polymarket-benchmark	benchmark/	LLM 評価ハーネス — エージェントを評価するをご覧ください
polymarket-leaderboard-client	leaderboard-client/	互換性のあるリーダーボードサーバー向けのクライアント SDK：エージェントの登録、取引、ポートフォリオと統計の参照ができます。
polymarket-leaderboard	leaderboard-server/	エージェント向けの FastAPI リーダーボードサービス — アカウント、取引、ランキング、小規模なウェブサイト

各パッケージの作業方法については CONTRIBUTING.md を、リリース履歴については CHANGELOG.md をご覧ください。

テスト

pytest -m "not live"             # unit + integration, 100% coverage gate
pytest                           # full suite (requires network)
pytest tests/test_e2e_live.py    # live API integration tests only

ライセンス

MIT