polymarket-paper-trader

Polymarket ペーパートレードエンジン

Polymarket のリアルタイム価格で、金銭的リスクなしに取引をシミュレーションできます。ウォレットもキーも不要で、資金を賭けることもありません。ポートフォリオは SQLite に保存され、セッションをまたいで維持されます。

クイックスタート

ポートフォリオを初期化する

python ~/.agents/skills/polymarket-paper-trader/scripts/paper_engine.py --action init --balance 1000

シェアを購入する（成行注文）

# Buy $50 of YES shares using live order book prices
python ~/.agents/skills/polymarket-paper-trader/scripts/paper_engine.py \
  --action buy --token TOKEN_ID --side YES --size 50 \
  --reason "High confidence based on news analysis"

シェアを購入する（指値注文）

python ~/.agents/skills/polymarket-paper-trader/scripts/paper_engine.py \
  --action buy --token TOKEN_ID --side YES --size 50 --price 0.45 \
  --reason "Value buy below fair price estimate"

ポートフォリオを確認する

python ~/.agents/skills/polymarket-paper-trader/scripts/paper_engine.py --action portfolio
python ~/.agents/skills/polymarket-paper-trader/scripts/paper_engine.py --action portfolio --json

ポジションを決済する

python ~/.agents/skills/polymarket-paper-trader/scripts/paper_engine.py \
  --action close --token TOKEN_ID --reason "Taking profit"

取引履歴を表示する

python ~/.agents/skills/polymarket-paper-trader/scripts/paper_engine.py --action trades

パフォーマンスレポート

python ~/.agents/skills/polymarket-paper-trader/scripts/portfolio_report.py
python ~/.agents/skills/polymarket-paper-trader/scripts/portfolio_report.py --json

ポートフォリオの健全性チェック（セッション開始時）

python ~/.agents/skills/polymarket-paper-trader/scripts/health_check.py
python ~/.agents/skills/polymarket-paper-trader/scripts/health_check.py --json

1 つのコマンドで、セッション開始時のワークフローをすべて実行します。ポートフォリオを読み込み、リアルタイム価格を取得し、データベースを更新して、ドローダウンを計算し、損切りを確認し、すべてのリスク制限を評価します。ステータスとして GREEN／YELLOW／RED を返します。

トークン ID の確認

トークン ID は Polymarket Gamma API から取得します。市場のトークン ID を確認するには、次のようにします。

# Search for markets
curl -s 'https://gamma-api.polymarket.com/markets?limit=5&active=true&closed=false&order=volume24hr&ascending=false' | python3 -c "
import sys, json
for m in json.load(sys.stdin):
    tokens = json.loads(m['clobTokenIds'])
    prices = json.loads(m['outcomePrices'])
    print(f\"{m['question'][:60]}\")
    print(f\"  YES token: {tokens[0]}  price: {prices[0]}\")
    print(f\"  NO  token: {tokens[1]}  price: {prices[1]}\")
    print()
"

または、まず polymarket-scanner スキルを使って市場を見つけます。

戦略の推奨事項を実行する

エグゼキューターは、戦略アドバイザーからの構造化された推奨事項を受け取ります。

python ~/.agents/skills/polymarket-paper-trader/scripts/execute_paper.py \
  --recommendation '{
    "token_id": "TOKEN_ID",
    "side": "YES",
    "action": "BUY",
    "size_usd": 50,
    "confidence": 0.75,
    "reasoning": "Momentum signal detected",
    "strategy": "momentum"
  }'

ドライラン（実行せずに検証）：

python ~/.agents/skills/polymarket-paper-trader/scripts/execute_paper.py \
  --recommendation '{"token_id":"TOKEN","side":"YES","size_usd":50}' --dry-run

リスクルール（組み込み）

ルール	デフォルト	目的
最大ポジションサイズ	ポートフォリオの 10%	1 回の賭けが大きくなりすぎるのを防ぐ
最大ドローダウン	30%	損失が大きくなりすぎた場合に取引を停止する
同時保有ポジションの上限	5	分散投資
1 日の損失上限	開始時残高の 5%	冷静さを失った取引を防ぐ
1 市場あたりの最大エクスポージャー	ポートフォリオの 20%	集中を防ぐ
人間による承認のしきい値	ポートフォリオの 15%	大規模な取引には確認が必要

--force フラグを使うか、初期化時にカスタムの risk_config を渡すことで、これらの設定を上書きできます。

仕組み

1. リアルタイム価格：clob.polymarket.com からリアルタイムの注文板を取得します
2. 注文板の走査：成行注文では、ミッド価格ではなく注文板を走査して約定をシミュレーションします
3. 手数料のモデル化：デフォルトは 0%（ほとんどの市場）で、暗号資産市場では設定可能です
4. SQLite への永続化：ポートフォリオは ~/.polymarket-paper/portfolio.db に保存されます
5. リスクエンジン：すべての取引を、設定可能なリスクルールに照らして検証します

API リファレンス

すべてのスクリプトは、機械可読な出力を得るための --json をサポートしています。主な Python 関数：

• paper_engine.init_portfolio(balance, name) — ポートフォリオを作成します
• paper_engine.place_order(token_id, side, size, price) — 取引を実行します
• paper_engine.close_position(token_id) — ポジションを決済します
• paper_engine.get_portfolio(name) — 現在の状態を取得します
• paper_engine.get_trades(name) — 取引履歴を取得します
• execute_paper.execute_recommendation(rec) — 戦略シグナルを実行します
• portfolio_report.generate_report(name) — 詳細な分析レポートを生成します

リスクパラメーターの詳細については references/risk-rules.md を、ペーパートレードのガイド全体については references/paper-trading-guide.md を参照してください。