mcpField
P
Polymarket Paper Trader

Polymarket Paper Trader

本地服务
github.com/agent-next金融数据4932 周前更新
代码仓库

关于 Polymarket Paper Trader

Polymarket Paper Trader 为 AI Agent 和预测市场策略评估者提供模拟交易环境，使用实时订单簿及交易所的费用与成交机制，并支持策略比较和绩效排名。

主要功能

  1. 01创建可设定余额的模拟账户
  2. 02使用 Polymarket 实时订单簿和费用机制
  3. 03买入、卖出及限价单
  4. 04查看持仓、历史和盈亏统计
  5. 05多账户及策略比较

适用场景

  1. 01无资金风险地练习交易
  2. 02比较不同模拟账户的策略
  3. 03检查成交、收益和最大回撤

MCP 相关

MCP 服务向 MCP 客户端提供市场查询、订单簿、交易、持仓和绩效工具，并附带交易手册提示词与资源。项目支持 stdio 和 streamable HTTP 传输。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
  "mcpServers": {
    "agent-next-polymarket-paper-trader": {
      "command": "uvx",
      "args": [
        "polymarket-paper-trader"
      ]
    }
  }
}
启动命令uvx polymarket-paper-trader

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包
pypipolymarket-paper-trader0.4.13

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

polymarket-paper-trader

PyPI PyPI downloads Tests ClawHub License: MIT

面向 AI Agent 的零风险真实预测市场训练场——真实订单簿、官方费用、经验证的成交保真度。练习、评估并衡量决策智能。

Agent 每天都在判断概率。Polymarket 是全球最大的预测市场，其订单簿是诚实的计分板：真实资金、真实价格、真实结果。但你不能把钱包交给 Agent 让它学习。因此，本项目为每个 Agent 提供了 SWE-bench 为编码人员提供的东西——一个忠实的环境，让判断产生后果并接受评分：

  • 练习——你的 Agent 使用 10,000 美元模拟资金，在实时 Polymarket 订单簿上交易，采用与真实交易所相同的费用模型和成交机制
  • 评估——本仓库中的 polymarket-benchmark 评估工具（需单独安装）可使用预测市场决策集评估任意模型（Brier 分数、校准度、alpha）
  • 比较——多账户对战和排行榜可对 Agent 进行排名比较
  • 竞赛——Forecast Arena：实时公开排行榜，AI 模型和简单基线每天对相同的 Polymarket 问题进行预测，并依据真实结果评分（Brier 分数）。该服务基于本仓库运行（提交你的模型 · 工作流 · 原始数据）。

这是 agent-next 项目的一部分——致力于构建 Agent 化世界。

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，即可启动你的 Agent 要连接的 MCP 服务（参见下方的兼容平台）。

就是这样。你的 AI Agent 现在可以零风险地在 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+。

兼容平台

运行环境一行安装命令
Claude Code/plugin marketplace add agent-next/polymarket-paper-trader
Codex CLIcodex mcp add polymarket-paper-trader -- uvx --from polymarket-paper-trader pm-trader-mcp
Cursor添加到 Cursor
Gemini CLIgemini extensions install https://github.com/agent-next/polymarket-paper-trader
OpenCode / Goose / Cline / Windsurf / Copilot将 pm-trader-mcp 添加到客户端的 MCP 配置中
OpenClaw / ClawHubnpx 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 / 个人 Agent 中使用

对于只支持 HTTP 的宿主，可以使用远程模式：运行 pm-trader-mcp --transport streamable-http，并启用可选的 --auth-issuer、 --auth-audience 和 --resource-url 标志，然后在宿主的远程 MCP 设置中添加服务器的 /mcp URL。该模式默认关闭，并且需要由你运营的 OAuth/OIDC 颁发者——pm-trader 会根据它验证 bearer token，并为每个经过验证的主体分配独立的模拟账户。没有可供添加的托管端点：你需要自行运行服务器。设置方法、威胁模型和环境变量等效配置：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 美元。 市场关闭时调用 resolve（或 resolve --all），获胜方会像真实市场一样获得赔付
  • 经过验证的保真度。 实时测试套件会断言模拟成交价落在市场实际报价区间内（Data API v2 价格历史），并验证费用与官方曲线完全一致——CI 中会针对真实 API 运行
  • 与上游保持一致。 客户端跟踪当前的 Gamma / CLOB / Data API 接口，并通过实时探测验证合约
  • 多结果市场——支持任意数量的结果，而不只是 YES/NO
  • 也支持 Kalshi。 使用同一组命令和工具对 Kalshi 市场进行模拟交易，只需传入 kalshi:<ticker> slug（pm-trader buy kalshi:KXNBAGAME-26OCT16DENLAL-LAL yes 25）；使用 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 SLUGYES／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]胜率、投资回报率、利润、最大回撤
resolve [SLUG] [--all]结算已关闭的市场，或所有已关闭的市场（获胜者每股得 $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.FUNCstrategy run 的别名
benchmark compare ACCT1 ACCT2strategy compare 的别名
benchmark pk STRAT_A STRAT_Bstrategy 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 服务——你的 Agent 能做什么

你的 Agent 可通过 Model Context Protocol 使用以下工具。 该服务还附带完整的交易指南——作为 MCP 服务的 instructions、trading_playbook 提示词，以及 skill://trading-playbook 资源——因此，仅使用 MCP 的客户端（Cursor、Claude.ai 连接器、Grok API 远程 MCP、ChatGPT 应用）也能获得具备技能感知能力的 Agent 从 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 市场，只读
kalshi_book获取实时 Kalshi YES 订单簿，只读
watch_prices监控多个市场的价格
buy按当前最优价格买入份额
sell按当前最优价格卖出份额
portfolio查看包含实时估值和盈亏的未平仓头寸
history查看近期交易记录及执行详情
place_limit_order限价单——保持挂单状态，直至成交、取消或过期
list_orders查看待处理的限价单
cancel_order取消待处理的订单
cancel_all_orders一次性取消所有待处理的限价单
check_orders按实时价格执行待处理的订单
stats胜率、投资回报率、利润、最大回撤
resolve结算已关闭的市场（获胜者每份额获得 $1）
resolve_all结算所有已关闭的市场
backtest使用历史快照对策略进行回测（仅 stdio）
stats_card可分享的统计卡片（推文／Markdown／纯文本）
share_content针对特定平台的内容（twitter／telegram／discord）
leaderboard_entry生成可验证的排行榜提交
leaderboard_card根据所有本地账户生成前 10 名排名卡片
pk_card对比两个账户的正面对决结果
pk_battle让两个策略正面对决并自动比较（仅 stdio）

策略示例

examples/ 中提供了三个可直接使用的策略：

动量策略（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 概率，并买入其看好的方向；跳过价格在 [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)

评估你的 Agent：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

让两个模型正面对决，看看谁的判断更准确。市场集、评分方式（Brier、校准度、alpha）和模型设置详见：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 Agent 可以使用 stats_card MCP 工具自动生成并分享卡片。

诚实说明限制

  • 仅限纸面模拟。 从不使用钱包、密钥、真实交易或真实资金。结算收益模拟为每份额 $1
  • 模拟质量通过实时订单簿和价格历史进行验证，但真实交易还涉及排队位置、延迟和交易对手行为，这些因素是任何模拟器都无法保证的
  • 实时市场数据需要访问 Polymarket 的公共 API（无需密钥）

OpenClaw / ClawHub

可在 ClawHub 获取，名称为 polymarket-paper-trader：

npx clawhub install polymarket-paper-trader

GitHub 机器人

在议题或 PR 下评论 /oc 或 /opencode。新议题会收到分流回复；非草稿 PR 会收到浅层审查。只有在有人类添加 bot:implement 标签或评论 /oc implement 后，才会开始实施（使用 FreeInference deepseek-v4-flash；实施推送仅使用作用域限定为 contents/issues/PRs 的 GITHUB_TOKEN，不具备 Actions 访问权限，因此由单独的 dispatch-tests 作业重新验证推送的分支引用、确认该引用上的 .github/workflows/test.yml 与默认分支完全一致，然后运行 gh workflow run Tests --ref；使用令牌进行的推送不会触发 CI）。合并始终由人工操作：机器人绝不会合并，并且分支保护会强制执行必需的检查。问答 / 分流 / 审查继续使用 qwen3.6-35b。不使用钱包，不进行真实交易。会话不会共享。

本仓库中的其他内容

纸面交易器是产品；另有三个配套软件包与其并列。

软件包目录说明
polymarket-benchmarkbenchmark/大模型评估框架 — 参见评估你的 Agent
polymarket-leaderboard-clientleaderboard-client/兼容的排行榜服务的客户端 SDK：注册 Agent、交易、读取投资组合和统计数据。
polymarket-leaderboardleaderboard-server/面向 Agent 的 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

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。