一、用途 polymarket-paper-trader 是一个 Polymarket 纸面交易（模拟交易）引擎，用于在零资金风险的前提下，针对 Polymarket 的实时价格模拟买卖。无需钱包、无需私钥、无需投入资金。投资组合通过 SQLite 在多次会话之间持久保存。
二、主要能力
- 用实时盘口价格模拟成交，而非使用中间价；市价单通过遍历订单簿（book walking）模拟成交。
- 手工费建模：默认 0%（适用于大多数市场），加密市场可配置。
- 投资组合持久化：数据保存在 ~/.polymarket-paper/portfolio.db。
- 内置风险引擎：每笔交易都会按照可配置的风险规则进行校验。
- 生成投资组合报告与交易历史。
- 会话启动健康检查：一条命令完成加载组合、获取实时价格、更新数据库、计算回撤、检查止损、评估全部风险限制，返回 GREEN/YELLOW/RED 状态。
- 可接收策略顾问给出的结构化建议并执行模拟交易，支持干跑（dry-run）校验。
三、使用方式 初始化投资组合： python ~/.agents/skills/polymarket-paper-trader/scripts/paper_engine.py --action init --balance 1000
市价买入（用实时订单簿价格买入 50 美元 YES 份额）：
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
查找 Token ID：Token ID 来自 Polymarket Gamma API。查找某市场的 Token： 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%，避免单笔押注过大。
- 最大回撤：30%，亏损过多时停止交易。
- 最大同时持仓数：5，用于分散。
- 每日亏损上限：起始余额的 5%，防止情绪化操作。
- 单一市场最大敞口：投资组合的 20%，避免集中。
- 人工审批阈值：投资组合的 15%，大额交易需要确认。 可用 --force 标志覆盖，或在初始化时传入自定义 risk_config。
五、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。
六、适用场景与限制 适用场景：练习交易、演示模式、虚拟交易、策略回测与策略测试。所有交易均为模拟，不产生真实资金风险。 限制：本技能描述中未提供真实资金下单能力、收费标准、价格信息或与真实钱包交互的说明，相关事实暂未提供。