polymarket-paper-trader

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Polymarket Paper Trading Engine

Simulate trades against live Polymarket prices with zero financial risk. No wallet, no keys, no money at stake. Portfolio persists across sessions in SQLite.

基于Polymarket实时价格进行模拟交易，无任何财务风险。无需钱包、密钥，无资金风险。投资组合通过SQLite在会话间持久化保存。

Quick Start

快速开始

Initialize a Portfolio

初始化投资组合

bash

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

bash

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

Buy Shares (Market Order)

买入份额（市价单）

bash

undefined

bash

undefined

Buy $50 of YES shares using live order book prices

以实时订单簿价格买入价值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"

undefined

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"

undefined

Buy Shares (Limit Order)

买入份额（限价单）

bash

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"

bash

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"

Check Portfolio

查看投资组合

bash

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

bash

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

Close a Position

平仓

bash

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

bash

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

View Trade History

查看交易历史

bash

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

bash

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

Performance Report

业绩报告

bash

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

bash

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

Portfolio Health Check (Session Start)

投资组合健康检查（会话启动时）

bash

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

Runs the full session-start workflow in one command: loads portfolio, fetches live prices, updates DB, calculates drawdown, checks stop losses, evaluates all risk limits. Returns GREEN/YELLOW/RED status.

bash

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

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

Finding Token IDs

获取Token ID

Token IDs come from the Polymarket Gamma API. To find them for a market:

bash

undefined

Token ID来自Polymarket Gamma API。如需查找某一市场的Token ID：

bash

undefined

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() "


Or use the **polymarket-scanner** skill to discover markets first.


也可先使用**polymarket-scanner**技能发现市场。

Execute Strategy Recommendations

执行策略建议

The executor takes structured recommendations from strategy advisors:

bash

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"
  }'

Dry run (validates without executing):

bash

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

执行器接受策略顾问提供的结构化建议：

bash

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"
  }'

试运行（仅验证不执行）：

bash

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

Risk Rules (Built In)

内置风险规则

Rule	Default	Purpose
Max position size	10% of portfolio	No single bet too large
Max drawdown	30%	Stop trading if losing too much
Max concurrent positions	5	Diversification
Daily loss limit	5% of starting balance	Prevent tilt
Max single market exposure	20% of portfolio	No concentration
Human approval threshold	15% of portfolio	Large trades need confirmation

Override with

--force

flag or by passing custom risk_config on init.

规则	默认值	目的
最大持仓规模	投资组合的10%	避免单一赌注过大
最大回撤	30%	亏损过多时停止交易
最大并发持仓数	5	分散投资
每日亏损限额	初始余额的5%	避免情绪化交易
单一市场最大敞口	投资组合的20%	避免过度集中
人工审批阈值	投资组合的15%	大额交易需确认

可使用

--force

标志覆盖，或在初始化时传入自定义risk_config。

How It Works

工作原理

Real prices: Fetches live order book from
```
clob.polymarket.com
```
Book walking: Market orders simulate fills by walking the order book (not mid-price)
Fee modeling: Default 0% (most markets), configurable for crypto markets
SQLite persistence: Portfolio at
```
~/.polymarket-paper/portfolio.db
```
Risk engine: Every trade validated against configurable risk rules

实时价格：从
```
clob.polymarket.com
```
获取实时订单簿
订单簿遍历：市价单通过遍历订单簿模拟成交（而非使用中间价）
费用建模：默认0%（大多数市场），可针对加密货币市场配置
SQLite持久化：投资组合存储于
```
~/.polymarket-paper/portfolio.db
```
风险引擎：每笔交易均需通过可配置的风险规则验证

API Reference

API参考

All scripts support

--json

for machine-readable output. Key Python functions:

paper_engine.init_portfolio(balance, name)

— Create portfolio

paper_engine.place_order(token_id, side, size, price)

— Execute trade

```
paper_engine.close_position(token_id)
```
— Close position
```
paper_engine.get_portfolio(name)
```
— Get current state
```
paper_engine.get_trades(name)
```
— Trade history

execute_paper.execute_recommendation(rec)

— Execute strategy signal

```
portfolio_report.generate_report(name)
```
— Full analytics

See

references/risk-rules.md

for detailed risk parameters and

references/paper-trading-guide.md

for the full paper trading guide.

所有脚本均支持

--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

。