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

通过一条命令运行完整的会话启动工作流：加载投资组合、获取实时价格、更新数据库、计算回撤、检查止损并评估所有风险限额。返回 GREEN/YELLOW/RED 状态。

查找 Token ID

Token ID 来自 Polymarket Gamma API。要查找某个市场的 Token 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 skill 先发现市场。

执行策略建议

执行器接收来自策略顾问的结构化建议：

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%	避免单笔下注过大
最大回撤	30%	亏损过多时停止交易
最大并发仓位数	5	分散风险
每日亏损限额	起始余额的 5%	防止情绪化交易
单个市场最大敞口	投资组合的 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。