catalog/repos/agent-next--polymarket-paper-trader.md

# Polymarket模拟交易

`量化交易` `AI代理` `模拟交易` `预测市场` `MCP`

# polymarket-paper-trader

[![PyPI](https://img.shields.io/pypi/v/polymarket-paper-trader.svg)](https://pypi.org/project/polymarket-paper-trader/)
[![Tests](https://github.com/agent-next/polymarket-paper-trader/actions/workflows/test.yml/badge.svg)](https://github.com/agent-next/polymarket-paper-trader/actions/workflows/test.yml)
[![ClawHub](https://img.shields.io/badge/ClawHub-install-orange.svg)](https://clawhub.com/robotlearning123/polymarket-paper-trader)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/agent-next/polymarket-paper-trader/blob/main/LICENSE)

**你的 AI 代理现在成为了 Polymarket 交易员。**

安装 → 代理获得 $10,000 虚拟资金 → 在真实 Polymarket 订单簿上交易 → 追踪盈亏 → 参与公开排行榜竞争。零风险，真实价格。

> "我的 AI 代理在 Polymarket 一周内实现了 +18% 的投资回报率。零风险，真实订单簿。"

隶属于 [agent-next](https://github.com/agent-next) —— 自主进化智能代理开源研究实验室。

## 60 秒演示

```bash
npx clawhub install polymarket-paper-trader    # 通过 ClawHub 安装
pm-trader init --balance 10000                 # $10k 虚拟资金
pm-trader markets search "bitcoin"             # 搜索市场
pm-trader buy will-bitcoin-hit-100k yes 500    # 买入 $500 的 YES
pm-trader stats --card                         # 生成可分享的统计卡片
```

就这些。你的 AI 代理现在可以零风险地在 Polymarket 上交易了。

## 安装

```bash
# 通过 pip
pip install polymarket-paper-trader

# 通过 ClawHub（适用于 OpenClaw 代理）
npx clawhub install polymarket-paper-trader

# 从源码安装（开发模式）
uv pip install -e ".[dev]"
```

需要 Python 3.10+。

## 不是玩具——这是真实的交易所模拟器

其他工具使用模拟价格或随机数。我们模拟真实交易所：

- **逐档订单簿撮合** —— 你的订单逐档消耗真实 Polymarket 买/卖盘的流动性，与真实交易完全一致
- **精确手续费模型** —— `bps/10000 × min(价格, 1-价格) × 份数` —— 与 Polymarket 官方公式相同
- **滑点追踪** —— 每笔交易记录实际成交价与中间价的偏差（以基点计）
- **限价单状态机** —— 支持 GTC（长期有效）和 GTD（定期有效）的完整生命周期管理
- **策略回测** —— 将策略在历史价格快照上重放验证
- **多结果市场** —— 不仅限于 YES/NO 二元，支持任意数量的结果

你的虚拟盈亏与真实盈亏的差距不超过买卖价差。这正是本工具的意义所在。

## 快速开始

```bash
# 初始化 $10k 虚拟账户
pm-trader init --balance 10000

# 浏览市场
pm-trader markets list --sort liquidity
pm-trader markets search "bitcoin"

# 交易
pm-trader buy will-bitcoin-hit-100k yes 100      # 买入 $100 的 YES
pm-trader sell will-bitcoin-hit-100k yes 50       # 卖出 50 份

# 查看持仓和盈亏
pm-trader portfolio
pm-trader stats
```

## CLI 命令

| 命令 | 说明 |
|---------|-------------|
| `init [--balance N]` | 创建虚拟交易账户 |
| `balance` | 显示现金、持仓价值和总盈亏 |
| `reset --confirm` | 清除所有数据 |
| `markets list [--limit N] [--sort volume\|liquidity]` | 浏览活跃市场 |
| `markets search QUERY` | 全文搜索市场 |
| `markets get 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]` | 交易历史 |
| `orders place SLUG OUTCOME SIDE AMOUNT PRICE` | 下限价单 |
| `orders list` | 待成交限价单 |
| `orders cancel ID` | 取消限价单 |
| `orders check` | 对照实时价格撮合限价单 |
| `stats [--card\|--tweet\|--plain]` | 胜率、ROI、利润、最大回撤 |
| `leaderboard` | 本地账户排行榜 |
| `pk ACCOUNT_A ACCOUNT_B` | 对战：谁是更好的交易员？ |
| `export trades [--format csv\|json]` | 导出交易历史 |
| `export positions [--format csv\|json]` | 导出持仓 |
| `benchmark run MODULE.FUNC` | 运行交易策略 |
| `benchmark compare ACCT1 ACCT2` | 对比账户表现 |
| `benchmark pk STRAT_A STRAT_B` | 对战：谁的策略更强？ |
| `accounts list` | 列出所有命名账户 |
| `accounts create NAME` | 创建用于 A/B 测试的账户 |
| `mcp` | 启动 MCP 服务器（stdio 传输） |

全局参数：`--data-dir PATH`、`--account NAME`（或环境变量 `PM_TRADER_DATA_DIR`、`PM_TRADER_ACCOUNT`）。

## MCP 服务器——你的代理能做什么

你的代理通过 [Model Context Protocol](https://modelcontextprotocol.io) 获得 26 个工具：

```bash
pm-trader-mcp  # 在 stdio 上启动
```

添加到你的 Claude Code 配置：

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

### MCP 工具

| 工具 | 功能说明 |
|------|---------|
| `init_account` | 创建虚拟账户并设置初始余额 |
| `get_balance` | 现金、持仓价值和总盈亏 |
| `reset_account` | 清除所有数据，重新开始 |
| `search_markets` | 按关键词搜索市场 |
| `list_markets` | 按交易量/流动性排序浏览市场 |
| `get_market` | 含结果和价格的市场详情 |
| `get_order_book` | 实时订单簿快照（买盘+卖盘） |
| `watch_prices` | 监控多个市场的价格 |
| `buy` | 以最优价格买入份额 |
| `sell` | 以最优价格卖出份额 |
| `portfolio` | 含实时估值和盈亏的持仓列表 |
| `history` | 含执行详情的近期交易记录 |
| `place_limit_order` | 限价单——保持挂单直至成交、取消或到期 |
| `list_orders` | 待成交限价单 |
| `cancel_order` | 取消待成交订单 |
| `check_orders` | 对照实时价格执行待成交订单 |
| `stats` | 胜率、ROI、利润、最大回撤 |
| `resolve` | 结算已关闭市场（获胜方每份获 $1） |
| `resolve_all` | 结算所有已关闭市场 |
| `backtest` | 在历史快照上回测策略 |
| `stats_card` | 可分享的统计卡片（推文/Markdown/纯文本） |
| `share_content` | 平台专属内容（Twitter/Telegram/Discord） |
| `leaderboard_entry` | 生成可验证的排行榜提交记录 |
| `leaderboard_card` | 所有本地账户的 Top 10 排行卡片 |
| `pk_card` | 两个账户的头对头对比 |
| `pk_battle` | 两个策略头对头运行并自动对比 |

## 策略示例

`examples/` 目录中提供三个即用策略：

### 动量策略（`examples/momentum.py`）

当 YES 价格突破 0.55 时买入，0.70 时止盈，0.35 时止损。

```bash
pm-trader benchmark run examples.momentum.run
```

### 均值回归策略（`examples/mean_reversion.py`）

当 YES 价格跌至公允价值 0.50 以下 12+ 美分时买入，回归时卖出。

```bash
pm-trader benchmark run examples.mean_reversion.run
```

### 网格限价策略（`examples/limit_grid.py`）

在当前价格下方布置网格限价买单，并在上方设置止盈卖单。

```bash
pm-trader benchmark run examples.limit_grid.run
```

### 编写自己的策略

```python
# my_strategy.py
from pm_trader.engine import Engine

def run(engine: Engine) -> None:
    """你的策略接收一个完全初始化的 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)
```

```bash
pm-trader benchmark run my_strategy.run
```

使用历史数据进行回测：

```python
def backtest_strategy(engine, snapshot, prices):
    """每个历史价格快照调用一次。"""
    if snapshot.midpoint > 0.6:
        engine.buy(snapshot.market_slug, snapshot.outcome, 50.0)
```

## 多账户支持

使用隔离账户并行运行多个策略：

```bash
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 benchmark compare aggressive conservative
```

## 分享你的成绩

生成可分享的统计卡片并发布到 X/Twitter：

```bash
pm-trader stats --tweet    # X/Twitter 优化格式
pm-trader stats --card     # Telegram/Discord 的 Markdown 格式
pm-trader stats --plain    # 纯文本格式
```

AI 代理可使用 `stats_card` MCP 工具自动生成并分享卡片。

## OpenClaw / ClawHub

已在 [ClawHub](https://clawhub.com) 上以 `polymarket-paper-trader` 名称发布：

```bash
npx clawhub install polymarket-paper-trader
```

## 测试

```bash
pytest -m "not live"             # 单元测试 + 集成测试（跳过实时 API 测试）
pytest                           # 完整测试套件（需要网络）
pytest tests/test_e2e_live.py    # 仅实时 API 集成测试
```

## 许可证

MIT