Agent Skills › mjunaidca/polymarket-skills › polymarket-paper-trader

polymarket-paper-trader

GitHub

Polymarket模拟交易引擎，支持零风险虚拟交易、投资组合管理及策略回测。通过调用脚本执行买卖、查看持仓与历史，并集成健康检查以监控风险指标，利用实时价格进行仿真。

polymarket-paper-trader/SKILL.md mjunaidca/polymarket-skills

Trigger Scenarios

用户希望进行无风险的模拟交易或练习用户需要查询模拟投资组合状态或交易历史

Install

npx skills add mjunaidca/polymarket-skills --skill polymarket-paper-trader -g -y

More Options

Non-standard path

npx skills add https://github.com/mjunaidca/polymarket-skills/tree/main/polymarket-paper-trader -g -y

Use without installing

npx skills use mjunaidca/polymarket-skills@polymarket-paper-trader

指定 Agent (Claude Code)

npx skills add mjunaidca/polymarket-skills --skill polymarket-paper-trader -a claude-code -g -y

安装 repo 全部 skill

npx skills add mjunaidca/polymarket-skills --all -g -y

预览 repo 内 skill

npx skills add mjunaidca/polymarket-skills --list

SKILL.md

Frontmatter

{
    "name": "polymarket-paper-trader",
    "description": "Use this skill whenever the user wants to paper trade, simulate trades, virtual trading, demo mode, practice trading, backtest strategies, test strategy performance, use paper money, manage a virtual portfolio, track simulated P&L, or do risk-free trading on Polymarket prediction markets. Also use when the user asks about their portfolio, positions, trade history, or performance report for paper trading. This is the core trading engine — it executes simulated trades against real live Polymarket prices with zero financial risk."
}

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.

Quick Start

Initialize a Portfolio

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

Buy Shares (Market Order)

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

Buy Shares (Limit Order)

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

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

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

View Trade History

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

Performance Report

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)

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.

Finding Token IDs

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

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

Execute Strategy Recommendations

The executor takes structured recommendations from strategy advisors:

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

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.

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