polymarket-paper-trader
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.
- Installs
- 200
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/mjunaidca/polymarket-skills --skill polymarket-paper-trader- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads polymarket-paper-trader automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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
API Reference
All scripts support --json for machine-readable output. Key Python functions:
paper_engine.init_portfolio(balance, name)— Create portfoliopaper_engine.place_order(token_id, side, size, price)— Execute tradepaper_engine.close_position(token_id)— Close positionpaper_engine.get_portfolio(name)— Get current statepaper_engine.get_trades(name)— Trade historyexecute_paper.execute_recommendation(rec)— Execute strategy signalportfolio_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.
FAQ
What does the polymarket-paper-trader skill do?
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.
How do I install polymarket-paper-trader?
Run npx skills add https://github.com/mjunaidca/polymarket-skills --skill polymarket-paper-trader in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/polymarket-paper-trader/ (personal) or .claude/skills/polymarket-paper-trader/ (project).
Which AI agents can use polymarket-paper-trader?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is polymarket-paper-trader safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains polymarket-paper-trader?
It is published by mjunaidca in mjunaidca/polymarket-skills. It has 200 recorded installs.
More from mjunaidca/polymarket-skills
polymarket-analyzer
mjunaidca/polymarket-skills
Use this skill whenever the user wants to find trading opportunities, detect arbitrage, analyze a market, perform edge detection, find mispricing, do probability analysis, evaluate orderbook depth, find momentum signals, or assess Polymarket market quality. Triggers: "find opportunities", "detect arbitrage", "analyze market", "edge detection", "mispricing", "probability analysis", "orderbook analysis", "momentum scanner", "market inefficiency", "price gap", "volume surge", "trading edge", "market analysis".
polymarket-strategy-advisor
mjunaidca/polymarket-skills
Use this skill whenever the user wants trading strategy advice, trade recommendations, portfolio guidance, or prediction market analysis that leads to actionable trades. Triggers: "trading strategy", "trade recommendation", "should I buy", "should I sell", "what to trade", "portfolio advice", "prediction market strategy", "position sizing", "Kelly criterion", "risk management", "entry criteria", "exit criteria", "market edge", "expected value", "when to trade", "stop trading", "drawdown", "strategy review", "daily review", "performance analysis", "paper trading strategy", "which markets", "best opportunities".
polymarket-scanner
mjunaidca/polymarket-skills
Use this skill whenever the user wants to browse, search, scan, or explore Polymarket prediction markets. This includes finding markets by topic or category, checking current prices and order books, getting market data, viewing trading volumes, looking up prediction market odds, or fetching live Polymarket data. Trigger on: polymarket, prediction market, browse markets, scan markets, market data, trading prices, order book, market odds, betting odds, event contracts, binary options, crypto prices polymarket, polymarket volume, market liquidity, polymarket search, find markets.
polymarket-monitor
mjunaidca/polymarket-skills
Use this skill whenever the user wants to monitor, watch, or track Polymarket prediction market prices over time. This includes setting up price alerts, watching for significant price movements, tracking spread changes, monitoring volume spikes, or getting notified about market activity. Trigger on: monitor prices, price alert, watch market, track prices, notify me, price change, polymarket alerts, market watch, price movement, volume spike, spread monitoring, track odds, prediction market alerts, continuous monitoring, price tracker, market surveillance.
polymarket-live-executor
mjunaidca/polymarket-skills
Use this skill when the user wants to execute a real trade on Polymarket, place a live order, go live, buy or sell on Polymarket, check real positions, or manage a live trading wallet. Triggers: "execute trade", "live trade", "real trade", "go live", "place order polymarket", "buy on polymarket", "sell on polymarket", "check positions", "my balance", "cancel order", "live portfolio". CRITICAL: This skill executes REAL trades with REAL money. Every trade requires explicit human confirmation before execution. Never execute autonomously.
Popular education & science skills
teach
mattpocock/skills
Teach the user a new skill or concept, within this workspace.
scaffold-exercises
mattpocock/skills
Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. Use when user wants to scaffold exercises, create exercise stubs, or set up a new course section.
paper-context-resolver
lllllllama/rigorpilot-skills
Rigor Paper Context helper for README-first deep learning repo reproduction. Use only when the README and repository files leave a narrow reproduction-critical gap and the task is to resolve a specific paper detail such as dataset split, preprocessing, evaluation protocol, checkpoint mapping, or runtime assumption from primary paper sources while recording conflicts. Do not use for general paper summary, repo scanning, environment setup, command execution, title-only paper lookup, or replacing README guidance by default.
caveman-learn
juliusbrussee/caveman
Act on a Caveman learn report - review the ranked token sinks, apply cost-lowering fixes with per-edit consent, and report what those fixes returned. Use when asked to lower an agent's token cost, what caveman has saved, to trim a heavy CLAUDE.md, or to offload re-pasted context into cavemem.
gsap-plugins
greensock/gsap-skills
Official GSAP skill for GSAP plugins — registration, ScrollToPlugin, ScrollSmoother, Flip, Draggable, Inertia, Observer, SplitText, ScrambleText, SVG and physics plugins, CustomEase, EasePack, CustomWiggle, CustomBounce, GSDevTools. Use when the user asks about a GSAP plugin, scroll-to, flip animations, draggable, SVG drawing, or plugin registration.
teach-impeccable
pbakaus/impeccable
DEPRECATED: Use /impeccable teach instead. This command has been folded into the impeccable skill.